1.1.2 Tile

Release Version

This reference documents version 1.1.2 (the release version) of the MapData Services Tile API. This release version of the API is a feature-stable version of the API whose interfaces are guaranteed to remain as documented within these pages until this version is retired.

What is The Tile API?

The Tile API is a service that serves raster data in small pieces known as “tiles”. You will need to use a mapping API, such as the following, in order to combine the tiles to get a more complete view of the raster data.

MDS Tile API provides Tiles in the Mercator projection for 18 levels/Scales based on the Bing Maps Tile System standard:
http://msdn.microsoft.com/en-us/library/bb259689.aspx

NT: For a look at Tile Sets the Tile API can give you access to please check the "Available Tile Sets" section.

Security

This service supports basic authentication for https requests or key referer authentication for http(s) requests.

(HTTPS) Basic Authentication

When the user agent wants to send the server authentication credentials it may use the Authorization attribute in the HTTPS header.
The Authorization header is constructed as follows:

- Username and password are combined into a string "username:password"
- The resulting string literal is then encoded using Base64
- The authorization method and a space i.e. "Basic " is then put before the encoded string.

For example, if the user agent uses 'Aladdin' as the username and 'open sesame' as the password then the header is formed as follows:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

(HTTP/HTTPS) Key referer Authentication

The API can use an API key to identify your application. The key is attached to the request uri as a HTTP(S) GET parameter.
The key is linked to the authorized URI's that are checked using the HTTP request referer attribute.

For example:

http(s)://api{subdomain}.nowwhere.com.au/1.1.2/tile/?key=YOUR KEY HERE

Request

Requests to the tile service must include a tileset id, zoom, x and y.
Requests can be made via HTTP GET or POST.
NT: POST requests can use basic authentication, POST or GET requests can use key / referer authentication. Check the security section for more info.

(GET/POST) By Tile XYZ

    http(s)://api{subdomain}.nowwhere.com.au/1.1.2/tile/{tileset}/{zoom}/{x}/{y}

Parameters

PARAMETERS are url path parameters in the structure “domain/parameter/”. The following table describes the available parameters.

Parameter Type Description
subdomain Integer subdomains: 1-4
Tileset Integer ID for a unique tileset eg: color or greyscale
zoom Integer Zoom level of map
x String X-Cordinate of tile within the map
y String Y-Cordinate of tile within the map

Response

The service will respond with either a image tile from the requested tileset, or a image missing tile if something went wrong with the request or the tile requested does not exist. These scenarios are outlined in more detail in the success & failure scenarios below.
NT: Both Success & fail tiles will be returned with a HTTP 200 (OK) status code.

(Success) 256/256px PNG Image

If the request was Successful: the service responds with a 256/256px png (Portable Network Graphics) image, example below:

Demo Tile
NT: This is an example only. Image size, appearance and file type may vary depending on tileset.

(Fail) 256/256px PNG Image

If the request failed: the service responds with a 256/256px png (Portable Network Graphics) image, example below.
Reasons for failure can be incorect parameters, or a tile not being available at the requested location.

Demo Tile
NT: This is an example only. Image size, appearance and file type may vary depending on tileset.

Attribution

The Tiles must include the following attribution and logo which must be visible on the map or on the web page near the map.

© “Year” MapData Services Pty Ltd (MDS), PSMA. MapData Services

Available Tile Sets

A Tile Set is a Raster Visualisation of a Data Set. The following Tile Sets are available via the Tile Service.

MDS Foundation Map

The MDS Foundation Map Tile Set is a Colour Base Map for Australia and New Zealand

MDS Foundation Map GreyScale

The MDS Foundation Map Grey Scale Tile Set is a Grey Scale Base Map for Australia and New Zealand

Custom Tile Sets

The Tile API can support custom tile sets, contact MapData Services to discuss options for adding your data to / or creating a Custom Tile Set.

Examples

The following examples outline how the tile service can be integrated into JavaScript web applications using three common JavaScript mapping libraries: Open Layers, Leaflet and ArcGIS API for JavaScript.

Open Layers Example

  
<!DOCTYPE html>
<html dir="ltr" lang="en-AU">
    <head>
        <meta charset="UTF-8" />
        <title>Simple Example of MDSFoundationMap with OpenLayers</title>
        <script type="text/javascript" src="/Portals/2/OpenLayers.js"></script>
        <link rel="stylesheet" href="./css/layout.css" type="text/css" />
        <script type="text/javascript">
            function init() {
                var map, layer, centre;
           
                var MapDS = {
                    ApiKey: 'YOUR_API_KEY_HERE'
                };
           
                OpenLayers.Util.onImageLoadError = function() { this.style.display="none"; }
                map = new OpenLayers.Map( 'map', {
                        controls: [
                            new OpenLayers.Control.PanZoomBar(),
                            new OpenLayers.Control.ScaleLine(),
                            new OpenLayers.Control.Navigation(),
                            new OpenLayers.Control.Attribution()
                        ]
                    }
                );
           
                layer = new OpenLayers.Layer.XYZ( "MDSFoundationMap", [
                        'http://api1.nowwhere.com.au/1.1.2/tile/50/${z}/${x}/${y}?key='+MapDS.ApiKey,
                        'http://api2.nowwhere.com.au/1.1.2/tile/50/${z}/${x}/${y}?key='+MapDS.ApiKey,
                        'http://api3.nowwhere.com.au/1.1.2/tile/50/${z}/${x}/${y}?key='+MapDS.ApiKey,
                        'http://api4.nowwhere.com.au/1.1.2/tile/50/${z}/${x}/${y}?key='+MapDS.ApiKey
                    ], {
                        transitionEffect: "resize",
                        buffer:0,
                        sphericalMercator: true,
                        projection: new OpenLayers.Projection ("EPSG:3857"),
                        attribution: "<a href=\"http://www.mapds.com\"><img src=\"http://apps.nowwhere.com.au/MDSQuickMap/img/MDSLogo.png\"></a> <a href=\"http://www.nowwhere.com.au/lic/NowWhereLic.htm\">© 1998 - 2018</a>"
                    }
                );
           
                map.addLayer(layer);
           
                // set transformation functions from/to alias projection
                OpenLayers.Projection.addTransform("EPSG:4326", "EPSG:3857", OpenLayers.Layer.SphericalMercator.projectForward);
                OpenLayers.Projection.addTransform("EPSG:3857", "EPSG:4326", OpenLayers.Layer.SphericalMercator.projectInverse);
                centre = new OpenLayers.LonLat( 151, -33 );
                map.setCenter( centre.transform(new OpenLayers.Projection("EPSG:4326"), map.getProjectionObject()), 5 );
            }
        </script>
    </head>

    <body onload="init()">
        <div id="map"></div>
    </body>
</html>

Leaflet Example

  
<!DOCTYPE html>
<html dir="ltr" lang="en-AU">
<head>
    <link rel="stylesheet" href="http://cdn.leafletjs.com/leaflet-0.7.3/leaflet.css" />
    <script src="http://cdn.leafletjs.com/leaflet-0.7.3/leaflet.js"></script>

    <script type="text/javascript">
        function init() {

            var MapDS = {
                ApiKey: 'Your API Key Here'
            };


            // create a CloudMade tile layer
            var cloudmadeUrl = 'http://api{s}.nowwhere.com.au/1.1.2/tile/50/{z}/{x}/{y}?key=' + MapDS.ApiKey,
            cloudmadeAttribution = '<a href="http://www.mapdataservices.com" target="_blank" >Map data © 2015 MapData Services</a>',
            cloudmade = new L.TileLayer(cloudmadeUrl, { maxZoom: 18, attribution: cloudmadeAttribution, subdomains: '1234' });

            // initialize the map on the "map" div
            map = new L.Map('map');
            map.addLayer(cloudmade).setView(new L.LatLng(-33.825, 151.192), 3);
        }
    </script>

    <style>
        #map {
            height: 300px;
            width: 300px;
        }
    </style>
</head>

<body onload="init()">
    <div id="map"></div>
</body>
</html>

ArcGIS API for JavaScript - Web Tile Layer Example

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="initial-scale=1, maximum-scale=1,user-scalable=no">
    <title></title>

    <link rel="stylesheet" href="http://js.arcgis.com/3.8/js/dojo/dijit/themes/nihilo/nihilo.css">
    <link rel="stylesheet" href="http://js.arcgis.com/3.8/js/esri/css/esri.css">
    <style>
      html, body, #map { 
        height: 100%; width: 100%;
        margin: 0; padding: 0;
      } 
      body{
        background-color: #fff; overflow:hidden; 
        font-family: sans-serif;
      } 
      #header {
        padding: 4px 15px 4px 0;
        background-color: #F2F2EC; 
        color: #575757; 
        font-size: 16pt; 
        text-align: right; 
        font-weight: bold;
        height:55px;
      }
      #subheader {
        color: #575757;
        font-size: small;
        padding: 5px 0 0 0;
        text-align: right;
      }
      #subheader a { color: #575757; }

      .ds { background: #000; overflow: hidden; position: absolute; z-index: 2; }
      #ds-h div { width: 100%; }
      #ds .o1 { filter: alpha(opacity=10); opacity: .1; }
      #ds .o2 { filter: alpha(opacity=8); opacity: .08; }
      #ds .o3 { filter: alpha(opacity=6); opacity: .06; }
      #ds .o4 { filter: alpha(opacity=4); opacity: .04; }
      #ds .o5 { filter: alpha(opacity=2); opacity: .02; }
      #ds .h1 { height: 1px; }
      #ds .h2 { height: 2px; }
      #ds .h3 { height: 3px; }
      #ds .h4 { height: 4px; }
      #ds .h5 { height: 5px; }
    </style>

    <script src="http://js.arcgis.com/3.8/"></script>
    <script>
        var map;
        require([
        "esri/map", "esri/layers/WebTiledLayer", "dojo/parser",

        "dijit/layout/BorderContainer", "dijit/layout/ContentPane", "dojo/domReady!"
      ], function (
        Map, WebTiledLayer, parser
      ) {
          parser.parse();

          //setup map object
        map = new esri.Map("map", {
            center: [151.206990, -33.867487],
            zoom: 13
        });    

            //tile server subdomain names
        var ts = ["1", "2", "3", "4"];

        //API key
        var MapDS = {
            ApiKey: 'YOUR_API_KEY_HERE'
        };

        // info used to create web tile layers
        var layers = [{
            "options": {
                "id": "MapData Services Foundation Map",
                "visible": true, 
                "subDomains": ts,
                "attribution": "2014 MapData Services "
            },
            "url": "http://api{subDomain}.nowwhere.com.au/1.1.2/tile/50/${level}/${col}/${row}?key=" + MapDS.ApiKey
        }];                        
        
        // create and add the layers
        dojo.forEach(layers, function(l) {
            var lyr = new WebTiledLayer(l.url, l.options);
            map.addLayer(lyr);
        });

      });
    </script>
  </head>
  <body class="nihilo">
    <div id="mainWindow" 
         data-dojo-type="dijit/layout/BorderContainer" 
         data-dojo-props="design:'headline',gutters:false"
         style="width: 100%; height: 100%; margin: 0;">
      <div id="map" class="shadow" 
           data-dojo-type="dijit/layout/ContentPane"
           data-dojo-props="region:'center'">

        <!-- drop shadow divs -->
        <div id="ds">
          <div id="ds-h">
            <div class="ds h1 o1"></div>
            <div class="ds h2 o2"></div>
            <div class="ds h3 o3"></div>
            <div class="ds h4 o4"></div>
            <div class="ds h5 o5"></div>
          </div>
        </div> 
        <!-- end drop shadow divs -->
            
      </div>
    </div>
  </body>
</html>