Using LDS XYZ map tile services in Leaflet and OpenLayers February 2015 1 [Note: This guide is in a draft state and has been developed for the purpose of beta testing of the LINZ Data Service imagery tile services. This content will be updated in preparation for the full public release of this service.] Overview - LDS map tile services The LDS tile services makes access to data for base maps and visualisations that much easier. This service allows you to directly incorporate LINZ data into your web or mobile application via pre- rendered map tiles that provide better performance and easier integration. LDS provides an XYZ tile service. This service is compatible with the Google Map API and can be easily combined with other global map tile services such as Open Street Map (OSM) or Microsoft Bing Maps. Tile services can also be accessed via our WMTS tile service. This guide focuses on our XYZ tile service, our recommended web API for accessing our basemaps and other tiled map data. This guide provides help with using LDS XYZ tile services in Openlayers and Leaflet. While OpenLayers supports more GIS functions, Leaflet may be easier to use for making simple web maps. LDS XYZ tile services To access LDS tile services you need to create an API or web services key. See the Web services content on the LINZ website for instructions on creating a key. You can create multiple keys to use across this and other LDS web services. Once you have created your key, you can use it within any LDS web service or API URL endpoint request. If you are logged into LDS and select a web service URL, your web service key is automatically populated in the URL. Client-side authentication is not required, as LDS recognises you as a registered user of LDS tile services through the API key. Selecting a tiled layer To support beta testing, tile services have been exposed as a service and are visible through the ‘Service’ tab on layers that support tile services. Simply select the ‘Services’ tab of any National Imagery layer on LDS, or the Topo50 or Topo250 maps, or the Hydrographic chart images to view the available tile services and the request URLs. 2 If you are logged in to LDS and have already created an API key, your API key and the layer ID will be pre-populated in the URL for you. URL syntax LDS tile services support both HTTP and HTTPS. Individual Imagery layers To access our XYZ tile services for individual National Imagery layers you can use the following base URL in your application: http://tiles-{a-d}.data-cdn.linz.govt.nz/services;key=YOUR_API_KEY/tiles/v4/layer=LA YER_ID/EPSG:CRS/{z}/{x}/{y}.png {a-d} - to support a higher volume of requests, simultaneous calls can be made to multiple sub-domains: a, b, c and d YOUR_API_KEY - your LDS API key - see above for creating a key 3 LAYER_ID - the identifier of the LDS tiled layer. For example, West Coast 0.4m Rural Aerial Photos (2009 – 2011) is layer 1928: https://data.linz.govt.nz/layer/1928-west-coast-04m- rural-aerial-photos-2009-2011/ CRS – identifier of the coordinate reference system of the tile grid you are requesting. By default, LDS tile service URLs are provided as EPSG:3857 (WGS84 Web Mercator) Z, X, Y – z is zoom level, x tile column and y tile row but your client will substitute values here for you Imagery sets (base map) The base URL for the National Imagery basemap, once it is ready for testing, will follow a similar format: http://tiles-{a-d}.data-cdn.linz.govt.nz/services;key=YOUR_API_KEY/tiles/v4/set=SET_ ID/EPSG:CRS/{z}/{x}/{y}.png SET_ID is the identifier of the LDS tiled set and follows the same principle as above Domains To ensure the performance of LDS’s tile services and to cater for high volume requests from web applications, XYZ tile service requests are made to the LINZ Data Service CDN rather than LDS core infrastructure. The XYZ tile services domain is: http://tiles-{a-d}.data-cdn.linz.govt.nz To support a higher volume of requests, simultaneous calls can be made to multiple sub-domains: a, b, c and d. See the details for using LDS tile services with Leaflet and Openlayers for the specific URL syntax to use for these subdomains. Projections Most LINZ tiled imagery layers are published in two projections: WGS84 Web Mercator (EPSG:3857) This is most likely to fit the majority of your use cases. It is most suitable for web mapping applications, compatible with the Google Map, OSM and Bing Maps tiles without need for re- projection or scaling. Coverage – Global (includes NZ Mainland and offshore Islands) Unless specified, the examples in this guide are using the default WGS84 Web Mercator projection. NZTM2000 (EPSG:2193) This tile set is most useful for New Zealand geospatial professionals and can be used for desktop GIS mapping. It is also recommended for New Zealand mainland web applications when area and distances need to be well represented on the map. This guide includes help on using XYZ tile services in NZTM2000. 4 See the LDS tile services tile set definition document for more information on the specifications of these tile sets. Rate limiting To guarantee reasonable performance levels and to guard against overuse or abuse of LINZ’s free tile services, these services are rate limited. Rate limiting will not impact the use of tile services in small to medium volume web mapping applications. Rate limiting for LDS tile services apply at the API key and IP address level, and be measured by the hour and minute. We will provide further information on the request limits and how to avoid hitting them once LDS tile services are publically released. In the meantime, we will contact you if you reach the limits. Hiding your API key If you are integrating LDS tile services into a public map service, you will need to take steps to protect your API key from being exposed to anonymous users. Web Map Tile Service LDS also supports Open Geospatial Consortium compliant Web Map Tile Service style requests. API implementation LDS supports WMTS version 1.0.0. Visit the Open Geospatial Consortium website for more information about the standard. Requests LDS tile services support RESTful requests only. KVP and SOAP request interfaces are not supported. LDS tile services support the HTTP GET method only for retrieving tiles. The following requests are supported: GetCapabilities: returns metadata about the service GetTile: returns an individual map tile from the cache GetFeatureInfo: returns descriptive information for a given map location WMTS URL syntax If you prefer, you can use our OGC WMTS tile services and style URL requests to retrieve tiles. In this method, your web client will use the GetCapabilities request to determine the tilematrix definition meaning one more request for your client, but reduces the configuration client side. An example of using the LDS NZTM2000 tile set in OpenLayers via the WMTS Get Capabilities functionality is provided. The base URL for this request format is: https://data.linz.govt.nz/services;key=YOUR_API_KEY/wmts/1.0.0/WMTSCapabilities.xml 5 Responses Tile image requests are returned from the tile cache as compressed PNGs. See the Tile services tile set definition document for information on image resolution (pixel size). PNG format was chosen as it allows the quality of images to be maintained and supports making the tile background transparent which is important for overlaying datasets. Requested tiles are cached on a rolling basis. This means there may be some fluctuation in tile responses as tiles are cached, drop off the cache store and are re-cached. 6 Using LDS tile services in OpenLayers About this guide This guide provides hints and tips and notes issues to be aware of when using LDS tile services in OpenLayers 3. This document is not a guide to using OpenLayers and assumes a good understanding of JavaScript. Please refer to the official OpenLayers documentation for help. This guide focuses on use of the LDS XYZ tile service. An example of using the WMTS functionality is also included. This method means one more request for the web application (GetCapabilities request to determine the tilematrix definition), but reduces the configuration you need to undertake client side. Notes The code snippets in this guide and referenced examples use OpenLayers version 3.1.1 The majority of examples in this guide assume use of the LDS Web Mercator (EPSG:3857) tile set. Specific guidance is provided for utilising the NZTM tile set OpenLayers 3 does not yet support the Get FeatureInfo function for vector-based tile services OpenLayers 3 does not yet support OGC WMTS GetCapabilities requests. An example of a GetCapabilities request for LDS tile services is provided, using a patched OpenLayers library Adding a LDS tiled layer to your map To add a single LDS tiled layer the simple format is: new ol.layer.Tile({ source: new ol.source.XYZ({ url: ‘http://tiles-{a-d}.data-cdn.linz.govt.nz/services;key=YOUR_API_KEY/tiles /v4/layer=LAYER_ID/EPSG:3857/{z}/{x}/{y}.png') Please note the use of the syntax {a-d}. This will allow requests to use our a, b, c, d subdomains to support more simultaneous tile requests in your browser. Adding multiple tiled layers You can return multiple layers at once by compositing layers in a single request. The request is composited server-side then returned as a single image, reducing bandwidth and processing overhead.