Tile Map Service Specification

Introduction

Document Scope

This standard specifies the behavior of a service that provides access to georeferenced maps in the form of a regularly spaced set of regularly sized squares at a finite number of scales. This standard specifies operations to retrieve a computer-readable description of the service instance and to retrieve particular tiles.

A Tile Map Service provides access to cartographic maps of geo-referenced data, not direct access to the data itself. This document standardizes the way in which map tiles are requested by clients, and the ways that servers describe their holdings.

Document Form

This specification will proceed from a description of general resources provided by the server to particular resources (such as map tiles) providing examples of access URLs and return values at each stage.

Specification

The Tiled Web Service provides access to resources, in particular, to rendered cartographic tiles at fixed scales. Access to these resources is provided via a "REST" interface, starting with a root resource describing available layers, then map resources with a set of scales, then scales holding sets of tiles.

Root Resource

The root resource describes the available versions of the <TileMapService> (and possibly other services as well).

Request:

http://tms.osgeo.org/

Response (Content-type: text/xml):

<?xml version="1.0" encoding="UTF-8" ?>
 <Services>
   <TileMapService version="1.0.0" href="http://tms.osgeo.org/1.0.0/" />
   <TileMapService version="1.1.0" href="http://tms.osgeo.org/1.1.0/" />
   <FancyFeatureService version="0.9" href="http://ffs.osgeo.org/0.9/" />
 </Services>

TileMapService Resource

The <TileMapService> resource provides description metadata about the service and lists the available <TileMaps>.

Optional elements in the resource are called out below using the pipe character. All other elements are mandatory.

Request:

http://tms.osgeo.org/1.0.0/

Response (Content-type: text/xml):

<?xml version="1.0" encoding="UTF-8" ?>
 <TileMapService version="1.0.0">
   <Title>Example Tile Map Service</Title>
   <Abstract>This is a longer description of the example tiling map service.</Abstract>
 | <KeywordList>example tile service</KeywordList>
 | <ContactInformation>
 |   <ContactPersonPrimary>
 |     <ContactPerson>Paul Ramsey</ContactPerson>
 |     <ContactOrganization>Refractions Research</ContactOrganization>
 |   </ContactPersonPrimary>
 |   <ContactPosition>Manager</ContactPosition>
 |   <ContactAddress>
 |     <AddressType>postal</AddressType>
 |     <Address>300 - 1207 Douglas Street</Address>
 |     <City>Victoria</City>
 |     <StateOrProvince>British Columbia</StateOrProvince>
 |     <PostCode>V8W2E7</PostCode>
 |     <Country>Canada</Country>
 |   </ContactAddress>
 |   <ContactVoiceTelephone>12503833022</ContactVoiceTelephone>
 |   <ContactFacsimileTelephone>12503832140</ContactFacsimileTelephone>
 |   <ContactElectronicMailAddress>pramsey@refractions.net</ContactElectronicMailAddress>
 | </ContactInformation>
   <TileMaps>
     <TileMap 
       href="http://tms.osgeo.org/1.0.0/vmap0/" 
       srs="EPSG:4326"
 |     face-id="0"
       global-profile="1">
       VMAP0 World Map
     </TileMap>
     <TileMap 
       href="http://tms.osgeo.org/1.0.0/landsat2000/"
       srs="EPSG:3005"
       global-profile="0">
       British Columbia Landsat Imagery (2000)
     </TileMap>
   </TileMaps>
 </TileMapService>

The <TileMap> element is the key to this response.

• The "href" attribute provides a URL that returns a <TileMap> document.
• The "srs" element provides the reference system that the <TileMap> will be in, using an AUTHORITY:ID pattern. The EPSG authority is the only authority in common use currently, see the #Spatial Referencing Systems section for more information about SRS details.
• The "global-profile" attribute is "1" if the <TileMap> conforms to the global profile and "0" otherwise. See the #Maximizing Interoperability section for more information.
• The "face-id" attribute is used by some advanced clients that combine multiple tile maps into a single visual output. The OSGPlanet and GeoFusion clients both use separate polar faces in conjuction with equatorial faces (an "earth cube") to create a single world view from multiple tile maps. See the #Using Faces section for more information on implemetations.

TileMap Resource

A <TileMap> is a (usually) cartographically complete map representation. Sometimes <TileMap>s are built to be used in conjunction, as a set of stacked layers, but they are generally visually complete on their own.

<TileMap>s are composed of a set of scale-appropriate cartographic renderings, each divided up into regularly spaced image tiles, called <TileSet>s. Small-scale (eg, 1:10000000) tile sets may only contain a handful of tiles. Large-scale tile sets (eg, 1:10000) may contain millions of tiles.

At a particular scale, and in a particular cartographic projection, a <TileMap> is represented by a <TileSet>, a coverage of regularly sized and spaced images that taken together form a complete visual representation of the entire area of coverage of the <TileMap>.

Each <TileMap> supports one <SRS> and one image format. To support more than one SRS or image format, define extra <TileMaps> in your <TileMapService> for each combination you want.

<TileMap>s have both a <BoundingBox> and an <Origin>. The <BoundingBox> is the extent of the data of interest -- it might be used by a client to set an initial spatial extent. The <Origin> is the lower-left corner of the 0/0 tile, and the upper right corner of tile -1/-1 (if you choose to configure your service so that negative tiles are required). The <Origin> may be outside of the visual region of interest (the <BoundingBox>), for reasons of implementation convenience.

Optional metadata elements are called out in the resource below with the pipe character.

Request:

 http://tms.osgeo.org/1.0.0/vmap0/

Response (Content-type: text/xml):

<?xml version="1.0" encoding="UTF-8" ?>
 <TileMap tilemapservice="http://tms.osgeo.org/1.0.0/">
   <Title>VMAP0 World Map</Title>
   <Abstract>A map of the world built from the NGA VMAP0 vector data set.</Abstract>
 | <KeywordList></KeywordList>
 | <Metadata type="TC211" mime-type="text/xml" href="http://www.org" />
 | <Attribution>
 |   <Title>National Geospatial Intelligence Agency</Title>
 |   <Logo width="10" height="10" href="http://nga.mil/logo.gif" mime-type="image/gif" />
 | </Attribution>
 | <WebMapServer href="http://wms.org" />
   <SRS>EPSG:4326</SRS>
   <BoundingBox minx="-180" miny="-90" maxx="180" maxy="90" />
   <Origin x="-180" y="-180" />  
   <TileFormat width="256" height="256" mime-type="image/jpeg" extension="jpg" />
   <TileSets>
     <TileSet href="http://tms.osgeo.org/1.0.0/vmap0/levelzero" units-per-pixel="0.703125" order="0" />
     <TileSet href="http://tms.osgeo.org/1.0.0/vmap0/levelone" units-per-pixel="0.3515625" order="1" />
     <TileSet href="http://tms.osgeo.org/1.0.0/vmap0/leveltwo" units-per-pixel="0.17578125" order="2" />
     <TileSet href="http://tms.osgeo.org/1.0.0/vmap0/levelthree" units-per-pixel="0.08789063" order="3" />
   </TileSets>
 </TileMap>

Request:

http://tms.osgeo.org/1.0.0/landsat2000/

Response (Content-type: text/xml):

<?xml version="1.0" encoding="UTF-8" ?>
 <TileMap tilemapservice="http://tms.osgeo.org/1.0.0/">
   <Title>British Columbia Landsat Imagery (2000)</Title>
   <Abstract>Landsat data collected in the year 2000 over British Columbia.</Abstract>
 | <KeywordList></KeywordList>
 | <Metadata type="TC211" mime-type="text/xml" href="http://www.org" />
 | <Attribution>
 |   <Title>Government of British Columbia</Title>
 |   <Logo width="10" height="10" href="http://gov.bc.ca/logo.png" mime-type="image/png" />
 | </Attribution>
 | <WebMapServer href="http://wms.gov.bc.ca" />
   <SRS>EPSG:3005</SRS>
   <BoundingBox minx="100000" miny="100000" maxx="1800000" maxy="1800000" />
   <Origin x="100000" y="100000" />
   <TileFormat width="256" height="256" mime-type="image/png" extension="png" />
   <TileSets>
     <TileSet href="http://tms.osgeo.org/1.0.0/landsat2000/32" units-per-pixel="3200" order="0" />
     <TileSet href="http://tms.osgeo.org/1.0.0/landsat2000/16" units-per-pixel="1600" order="1" />
     <TileSet href="http://tms.osgeo.org/1.0.0/landsat2000/8" units-per-pixel="800" order="2" />
     <TileSet href="http://tms.osgeo.org/1.0.0/landsat2000/4" units-per-pixel="400" order="3" />
     <TileSet href="http://tms.osgeo.org/1.0.0/landsat2000/2" units-per-pixel="200" order="4" />
     <TileSet href="http://tms.osgeo.org/1.0.0/landsat2000/1" units-per-pixel="100" order="5" />
   </TileSets>
 </TileMap>

Tile Resources

The origin of a <TileMap> is defined in the coordinates of the spatial reference system of the <TileMap>. The x-coordinate of the tile numbers increases with the x-coordinate of the spatial reference system, and the y-coordinate of the tile numbers also increases with the y-coordinate of the spatial reference system.

Tiles are addressed under the "href" specified in the <TileSet> appending the "x" tile coordinate as a directory name and using the "y" tile coordinate as the file name, with the file "extension" from the <TileFormat>.

Example:

The tile at the origin of the tile set in the first zoom level of vmap0.
http://tms.osgeo.org/1.0.0/vmap0/levelzero/0/0.jpg

The tile near the middle of the tile set in the third zoom level of vmap0.
http://tms.osgeo.org/1.0.0/vmap0/leveltwo/3/4.jpg

The tile near the middle of the tile set in the fifth zoom level of landsat2000.
http://tms.osgeo.org/1.0.0/landsat2000/1/8500/8500.png

TileMap Diagram

(This is where a diagram of how the Origin, Bounding Box, tile numbering and so on all tie together.)

Error Handling

When an error occurs in the server, it is important that the client be able easily notice that an error has occurred, and ascertain why the error occured so the user can be notified if necessary.

The tile map server uses HTTP error codes to relay the general reason for an error condition, and an XML payload to communicate the specific reason for the failure in human readable language.

Only HTTP error codes given in this specification should be used to return errors to the client.

• The client requests a nonexistent resource URL. Return HTTP error code 404 (Not Found)
• The server fails in processing a response for a valid resource URL. Return HTTP error code 500 (Internal Server Error)

Servers are allowed to return content, even when throwning an error code. The following is the XML format for a tile map server error message.

<?xml version="1.0" ?>
 <TileMapServerError>
   <Message>The requested tile is outside the bounding box of the tile map.</Message>
 </TileMapServerError>

Implementation Advice

Spatial Referencing Systems

(To be done...)

Maximizing Interoperability

Using this server specification will ensure that clients can easily consume your tiled map data. However, it will not guarantee that clients can efficiently overlay your data with data from other tile map servers. In order to maximize the interoperability of your tile map with other tile maps, you must implement the "global profile" for your tile map.

(Services implementing the "global profile" should be flagged as such by setting the "global-profile" attribute in the <TileMap> element of the <TileMapService> resource to "1".)

In order to conform to the "global profile" a TileMap must meet the following requirements:

• Must use <SRS>EPSG:4326</SRS>
• Must provide <TileSet>s with units-per-pixel meeting the following formula for any integral value of "n" greater than or equal to 0: units-per-pixel = 0.703125 / 2^n

Maximizing Cacheability

Tile maps are usually base maps, and usually represent data that changes on a very slow cycle. They are also usually large in volume, comprising potentially millions of different tiles. Given these basic facts, the aggressive use of caching strategies can optimize performance of tile map services.

Caching can happen at multiple layers between the server and the client:

• At the client itself, as the user-agent caches results on the local disk.
• In a shared cache at an intermediate ISP, allowing multiple users of the ISP to pull data from the cache.
• In a cache on the server itself, to move load from the tile generator to a simpler caching process.

In order for caching to occur at any of these layers, the caching mechanisms need to know when a resource is cachable.

If your tile server is written using a scripting or programming language, you will probably be constructing your HTTP headers yourself, and it is important to include cache control headers when doing so to allow caching to occur.

There are different cache headers for HTTP 1.0 and HTTP 1.1, and because both protocols are in active use, it is important to include both.

For HTTP 1.0, use the "Expires" header. If you expect your data to change no more than once per week, set your Expires header to one week in the future. For example, if it is January 1, 2007, and you wanted your tiles to expire no more than one week after they are retreived, you would set your header using this PHP invocation:

header('Expires: Sun, 25 Jun 2006 14:57:12 GMT');

Or, to always set the Expires header to one week in the future:

header('Expires: ' . gmdate('D, j M Y H:i:s T', time() + 7 * 24 * 60 * 60));   // time + 7 days worth of seconds

For HTTP 1.1, use the "Cache-control" header. Unlike the older "Expires" header, "Cache-control" does not have a clock reference, just a time period to reatain the data, thereby avoiding the clock sychronization issues of "Expires".

header('Cache-Control: max-age=86400, must-revalidate');
header('Cache-Control: ' . 7 * 24 * 60 * 60 );

Read about HTTP 1.1 cache control headers in the W3.org specification.

Implementing Cacheability

You can trust that the somewhere on the internet, someone will respect your cache control headers and your content will be cached, or you can set up your own cache. If you are running Apache 2.0 adding mod_cache caching to your tms is laughably easy.

Just add a mod_cache directive inside your <VirtualHost> definition:

<IfModule mod_disk_cache.c>
 CacheRoot /tmp/apache-cache 
 CacheSize 1024000
 CacheEnable disk /cgi-bin/tms
 CacheDirLevels 5
 CacheDirLength 3
</IfModule> 

This example is for a disk cache, probably what you will use for your TMS, since the data volumes tend to be high. Note how the CacheEnable directive allows you to very precisely control which content you are going to cache. In my case, I am only caching the output from my TMS server, nothing else. If I wanted, I could be even narrower and restrict caching to just one tile map inside my service, or just one tile set.

URLs That are Actually Scripts

For large implementations of the tile map server specification, the data will not be statically pre-built, but will be demand-generated by some kind of backend service. That means that URLs that appear to be static may actually be dynamic.

The CGI specification allows this trivially, by passing any path information after the CGI executable in the URL back to the executable in the PATH_INFO environment variable:

http://tms.osgeo.org/cgi-bin/tms/1.0.0/vmap0

PATH_INFO = 1.0.0/vmap0

If "tms" is the CGI executable, it can easily extract the remaining path information and use that for processing purposes.

Note that by default Microsoft IIS does not conform to the CGI specification for this behavior (Apache does). See the note at http://support.microsoft.com/kb/q184320/ for information on how to enable this bahavior in IIS.

Note that it is allowable for URLs to include "."s in the middle of paths, so that executable scripts (like PHP files) can be legally used as TMS servers.

Here is a root resource:
http://tms.osgeo.org/tms.php

Here is the a tile request on that server:
http://tms.osgeo.org/tms.php/1.0.0/thetilemap/firstlevel/2/1.jpg

In general, the simplest way to extract information from the incoming script invocation is to take the incoming PATH_INFO environment variable, strip the "/" character from the start and end of the string, and then split the string into an array using the "/" character. In this manner, the first element of the array will be the version, the second element will be the tile map, the third will be the level, the fourth will be the tile "x" and the fifth will be the tile "y" (with a .extension).

Using Faces

The "face-id" attribute of the <TileMap> referenced in the <TileMapService> is used for some specialized clients. How that attribute is used by each client is described here.

To be filled in by implementation knowledge...

Reference Implementations

• This is a first attempt at a reference server, it might not work yet, and has no error handling at all. And it is probably very slow, it just wraps up the NASA WMS Global Mosaic within the Tile Map Service specification.
  • http://mapserver.refractions.net/cgi-bin/tms

Returning Error Codes

If your tile map server is a static set of files, you will find that your web server sets the appropriate error codes automatically when people ask for resources that do not exist, or the server suffers a failure.

However, if your tile map server is dynamic, you will have to set the HTTP status codes yourself, otherwise the HTTP server will assign a code of 200 (OK) for your error message XML document, which would be wrong. In PHP, an error return function might look like this:

header("HTTP/1.0 404 Not Found");
header("Content-type: text/xml");
print "<?xml version='1.0' ?>";
print "<TileMapServerErrror>";
print "<Message>You requested a map tile [ $path_info ] that does not exist.</Message>";
print "</TileMapServerError>";

Not that in addition to setting the error code the Content-type was also correctly set. Also note that cache headers were not set, since errors are not a good thing to cache.

See Also

• HTTP Caching
• What is REST