git.gag.com Git - web/altusmetrum/blob - AltOS/doc/map-loading.html

   1 <!DOCTYPE html>
   2 <html lang="en">
   3 <head>
   4 <meta charset="UTF-8">
   5 <meta http-equiv="X-UA-Compatible" content="IE=edge">
   6 <meta name="viewport" content="width=device-width, initial-scale=1.0">
   7 <meta name="generator" content="Asciidoctor 2.0.16">
   8 <meta name="author" content="Keith Packard">
   9 <meta name="copyright" content="Keith Packard 2018">
  10 <title>Loading Map Tiles from Google Maps</title>
  11 <link rel="stylesheet" href="./am-notoc.css">
  12 </head>
  13 <body class="article">
  14 <div id="header">
  15 <h1>Loading Map Tiles from Google Maps</h1>
  16 <div class="details">
  17 <span id="author" class="author">Keith Packard</span><br>
  18 <span id="email" class="email"><a href="mailto:keithp@keithp.com">keithp@keithp.com</a></span><br>
  19 <span id="revdate">06 Oct 2021</span>
  20 </div>
  21 </div>
  22 <div id="content">
  23 <div class="sect1">
  24 <h2 id="_the_google_maps_problem">The Google Maps Problem</h2>
  25 <div class="sectionbody">
  26 <div class="paragraph">
  27 <p>Until recently, Google Maps could be used without fee to fetch map
  28 tiles. Applications could load map tiles anonymously or using a key;
  29 when used anonymously, the number of tiles that could be loaded per
  30 day and the rate at which tiles could be loaded was throttled to make
  31 the API practical only for development purpose. With an application
  32 key, the number of tiles available per day was much higher, and there
  33 was no rate limiting. This was usually sufficient for Altos Metrum
  34 customer use.</p>
  35 </div>
  36 <div class="paragraph">
  37 <p>However, this has changed and now there is no way to load map tiles
  38 anonymously, and any application key must be tied to a credit
  39 card. The tile cap for free usage is now monthly instead of
  40 daily. Because the key is tied to a credit card, we should not ship it
  41 with the application any longer. And because the cap is monthly
  42 instead of daily, we need some way to control usage by our
  43 applications.</p>
  44 </div>
  45 <div class="sect2">
  46 <h3 id="_the_proposed_solution_an_intermediate_service">The Proposed Solution — An Intermediate Service</h3>
  47 <div class="paragraph">
  48 <p>To give us some measure of control over tile loading, we will want to
  49 interpose a server controlled by us between the application and Google
  50 Maps. This will let us store the Google Maps key in a secure location,
  51 and also control tile loading by each user.</p>
  52 </div>
  53 <div class="imageblock text-center">
  54 <div class="content">
  55 <img src="map-loading.svg" alt="map loading">
  56 </div>
  57 </div>
  58 </div>
  59 </div>
  60 </div>
  61 <div class="sect1">
  62 <h2 id="_altos_map_service">AltOS Map Service</h2>
  63 <div class="sectionbody">
  64 <div class="paragraph">
  65 <p>This service receives a URL request and replies with either a map tile
  66 or an error. It is functionally equivalent to the Google Maps service,
  67 except that it can control use of the Google Maps API.</p>
  68 </div>
  69 <div class="sect2">
  70 <h3 id="_altos_map_cgi_script">AltOS Map CGI Script</h3>
  71 <div class="paragraph">
  72 <p>The AltOS Map CGI Script is a straightforward script which connects to
  73 the AltOS Map Cache Manager, transmits a URL describing the desired
  74 map tile and receives back a filename (or error), then sends the
  75 contents of that file back through Apache to the requesting
  76 application. The name of the script is 'altos-map'.</p>
  77 </div>
  78 <div class="sect3">
  79 <h4 id="_inputs">Inputs</h4>
  80 <div class="paragraph">
  81 <p>The AltOS Map CGI Script will parse the provided AltOS Map URI or
  82 AltOS Version URI.</p>
  83 </div>
  84 </div>
  85 <div class="sect3">
  86 <h4 id="_outputs">Outputs</h4>
  87 <div class="paragraph">
  88 <p>For AltOS Map URLs, the CGI Script will return either the contents of
  89 the associated Google Map tile or an error indicating what failed:</p>
  90 </div>
  91 <div class="paragraph">
  92 <p><em>200 OK</em>: The map tile image data or version information</p>
  93 </div>
  94 <div class="paragraph">
  95 <p><em>400 Bad Request</em>: The URL is malformed or not compatible with the
  96 version supported by the service</p>
  97 </div>
  98 <div class="paragraph">
  99 <p><em>403 Forbidden</em>: The map tile is outside the areas supported by the
 100 current AltOS Map service area</p>
 101 </div>
 102 <div class="paragraph">
 103 <p><em>408 Request Timeout</em>: Attempts to fetch the tile from Google Maps
 104 timed out.</p>
 105 </div>
 106 <div class="paragraph">
 107 <p><em>503 Service Unavailable</em>: The service is temporarily refusing to
 108 satisfy this request due to resource limitations.</p>
 109 </div>
 110 </div>
 111 </div>
 112 <div class="sect2">
 113 <h3 id="_altos_map_cache_manager">AltOS Map Cache Manager</h3>
 114 <div class="paragraph">
 115 <p>This is a service running on the local machine and available over a
 116 local network socket. It translates an AltOS Map URL into a local
 117 filename containing the contents of the associated Google Maps
 118 tile. The name of the cache manager is 'altos-mapd'. It will listen
 119 for requests on port 16717.</p>
 120 </div>
 121 </div>
 122 <div class="sect2">
 123 <h3 id="_altos_map_uri">AltOS Map URI</h3>
 124 <div class="paragraph">
 125 <p>AltOS uses a limited subset of the Google Maps, and the AltOS Map URIs
 126 only encode those elements which we currently use. This specification
 127 describes AltOS Map URI format version 1.0.0. The application is
 128 required to provide URIs compatible with the format supported by the
 129 server. The elements of the  elements are:</p>
 130 </div>
 131 <div class="ulist">
 132 <ul>
 133 <li>
 134 <p>Latitude of center point</p>
 135 </li>
 136 <li>
 137 <p>Longitude of center point</p>
 138 </li>
 139 <li>
 140 <p>Zoom level (from bushes to planets)</p>
 141 </li>
 142 </ul>
 143 </div>
 144 <div class="paragraph">
 145 <p>Encoding this in a URI is straightforward:</p>
 146 </div>
 147 <div class="literalblock">
 148 <div class="content">
 149 <pre>altos-map?lat=&lt;lat&gt;&amp;lon=&lt;lon&gt;&amp;zoom=&lt;zoom&gt;</pre>
 150 </div>
 151 </div>
 152 <div class="paragraph">
 153 <p>Latitude and longitude are both encoded using decimal degrees with 6
 154 digits following the decimal point.</p>
 155 </div>
 156 <div class="paragraph">
 157 <p>Zoom levels can range from 1 (world) to 20 (buildings). Higher zoom
 158 levels show smaller areas at greater detail.</p>
 159 </div>
 160 <div class="paragraph">
 161 <p>The only Google Map type supported by version 1.0.0 of the service is
 162 “hybrid”, which combines road graphics on top of satellite images.</p>
 163 </div>
 164 <div class="paragraph">
 165 <p>Version 1.0.0 always returns images which are 512x512 pixels.</p>
 166 </div>
 167 <div class="paragraph">
 168 <p>If we need additional elements in the URL, we can add them in the
 169 future and bump the supported version number.</p>
 170 </div>
 171 </div>
 172 <div class="sect2">
 173 <h3 id="_altos_version_uri">AltOS Version URI</h3>
 174 <div class="paragraph">
 175 <p>To allow applications to discover what AltOS Map URI version is supported by the
 176 AltOS Map service, the application may query the version of the API
 177 supported using the Version URI. The application provides the version
 178 that it supports and the AltOS Map service returns a version not
 179 greater than the client version:</p>
 180 </div>
 181 <div class="literalblock">
 182 <div class="content">
 183 <pre>altos-map?version=&lt;client-major&gt;.&lt;client-minor&gt;.&lt;client-revision&gt;
 184 →
 185 &lt;server-major&gt;.&lt;server-minor&gt;.&lt;server.revision&gt;</pre>
 186 </div>
 187 </div>
 188 </div>
 189 <div class="sect2">
 190 <h3 id="_altos_tile_request">AltOS Tile Request</h3>
 191 <div class="paragraph">
 192 <p>The AltOS Map CGI Script parses the Map URI and passes that
 193 information to the AltOS Map Cache Manager using the AltOS Tile
 194 Specifier syntax. This is a JSON representation of the same data
 195 provided by the URI:</p>
 196 </div>
 197 <div class="literalblock">
 198 <div class="content">
 199 <pre>{
 200         "lat": &lt;latitude&gt;,
 201         "lon": &lt;longitude&gt;,
 202         "zoom": &lt;zoom-level&gt;,
 203         "remote_addr": "&lt;IPv4 or IPv6 address of requesting client&gt;"
 204 }</pre>
 205 </div>
 206 </div>
 207 <div class="paragraph">
 208 <p>Latitude and longitude are both encoded using decimal degrees with 6
 209 digits following the decimal point.</p>
 210 </div>
 211 </div>
 212 <div class="sect2">
 213 <h3 id="_altos_tile_reply">AltOS Tile Reply</h3>
 214 <div class="paragraph">
 215 <p>Sent back from the Cache Manager to the CGI Script, this encodes the
 216 status of the request and the filename of any tile data available. It
 217 is encoded in JSON format:</p>
 218 </div>
 219 <div class="literalblock">
 220 <div class="content">
 221 <pre>{
 222         "status": &lt;HTTP status&gt;,
 223         "filename": "&lt;absolute path to image file&gt;",
 224         "content_type": "&lt;HTTP content-type&gt;"
 225 }</pre>
 226 </div>
 227 </div>
 228 <div class="paragraph">
 229 <p>The “filename” and “content-type” elements are only included when
 230 the status is <em>200 OK</em>.</p>
 231 </div>
 232 </div>
 233 <div class="sect2">
 234 <h3 id="_altos_tile_filename">AltOS Tile Filename</h3>
 235 <div class="paragraph">
 236 <p>While the current AltOS Map URI version only supports a limited subset
 237 of the Google Maps functionality, we&#8217;ll encode more of that data in
 238 filenames to allow for easy expansion of functionality in the
 239 future. The elements of an AltOS Tile filename consist of :</p>
 240 </div>
 241 <div class="ulist">
 242 <ul>
 243 <li>
 244 <p>Latitude, with N/S indicator (instead of a sign)</p>
 245 </li>
 246 <li>
 247 <p>Longitude, with E/W indicator (instead of a sign)</p>
 248 </li>
 249 <li>
 250 <p>Map type.</p>
 251 </li>
 252 <li>
 253 <p>Zoom level</p>
 254 </li>
 255 <li>
 256 <p>Scale factor. Scale, and the preceding hyphen are omitted for a scale factor of 1.</p>
 257 </li>
 258 <li>
 259 <p>Image format suffix. '.jpg' for JPEG files and '.png' for PNG files.</p>
 260 </li>
 261 </ul>
 262 </div>
 263 <div class="paragraph">
 264 <p>Latitude and longitude are both encoded using decimal degrees with 6
 265 digits following the decimal point.</p>
 266 </div>
 267 <div class="paragraph">
 268 <p>Map type is one of :</p>
 269 </div>
 270 <div class="paragraph">
 271 <p><em>hybrid</em>: Road graphics over satellite images
 272 <em>roadmap</em>: Symbolic road map
 273 <em>satellite</em>: Un-annotated satellite images
 274 <em>terrain</em>: Topographic map</p>
 275 </div>
 276 <div class="paragraph">
 277 <p>Here&#8217;s what map filenames look like:</p>
 278 </div>
 279 <div class="literalblock">
 280 <div class="content">
 281 <pre>map-{N,S}&lt;lat&gt;,{E,W}&lt;lon&gt;-&lt;type&gt;-&lt;zoom&gt;[-&lt;scale&gt;].&lt;format&gt;</pre>
 282 </div>
 283 </div>
 284 <div class="literalblock">
 285 <div class="content">
 286 <pre>map-N36.508532,W107.823944-hybrid-18.jpg</pre>
 287 </div>
 288 </div>
 289 <div class="paragraph">
 290 <p>To transmit this name from the AltOS Map Cache Manager back to the
 291 Altos Map CGI script, the filename will be wrapped in a JSON string</p>
 292 </div>
 293 </div>
 294 </div>
 295 </div>
 296 <div class="sect1">
 297 <h2 id="_implementation">Implementation</h2>
 298 <div class="sectionbody">
 299 <div class="paragraph">
 300 <p>The AltOS Map CGI Script and AltOS Map Cache Manager will both be
 301 implemented in Java as much of the required Google Maps infrastructure
 302 is already available in that language.</p>
 303 </div>
 304 <div class="sect2">
 305 <h3 id="_access_control">Access Control</h3>
 306 <div class="paragraph">
 307 <p>No access control to the service is planned at this point. If
 308 necessary, we could implement username/password access control for each
 309 user of the service.</p>
 310 </div>
 311 </div>
 312 <div class="sect2">
 313 <h3 id="_location_restrictions">Location Restrictions</h3>
 314 <div class="paragraph">
 315 <p>To avoid unbounded usage, and confine the utility of this service to
 316 AltOS users, the service will only offer map tiles whose center
 317 location is within 10 miles of one of the sites registered in
 318 our launch sites database.</p>
 319 </div>
 320 <div class="paragraph">
 321 <p>To allow testing of the registered launch site database, a database of
 322 privileged clients will be supported. Privileged clients will have
 323 unlimited access to the service.</p>
 324 </div>
 325 </div>
 326 <div class="sect2">
 327 <h3 id="_per_client_restrictions">Per-Client Restrictions</h3>
 328 <div class="paragraph">
 329 <p>We should implement a per-day limit on the number of tiles provided to
 330 a particular requesting client. We can also rate limit clients to a
 331 certain number of tiles per minute to reduce the bandwidth consumed
 332 out of our server.</p>
 333 </div>
 334 </div>
 335 <div class="sect2">
 336 <h3 id="_cache_lifetime_restrictions">Cache Lifetime Restrictions.</h3>
 337 <div class="paragraph">
 338 <p>The Google Maps API allows for caching of map data for no more than 30
 339 days. To honor this, the Cache Manager will re-fetch any requested
 340 tiles when the cached version is older than this. If the fetch fails,
 341 the cache manager will continue to serve the data from the cached
 342 version of the file.</p>
 343 </div>
 344 </div>
 345 </div>
 346 </div>
 347 </div>
 348 <div id="footer">
 349 <div id="footer-text">
 350 Last updated 2021-10-06 22:33:16 -0600
 351 </div>
 352 </div>
 353 </body>
 354 </html>