Using LDS XYZ Map Tile Services in Leaflet and Openlayers

Using LDS XYZ map tile services in Leaflet and OpenLayers

February 2015

[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.

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

 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.

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

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.

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. Bear in mind, this method is not suitable if you require the ability to toggle individual layers on and off:

http://tiles-{a-d}.data-cdn.linz.govt.nz/services;key=YOUR_API_KEY/tiles/v4 /layer=LAYER_ID;layer=LAYER_ID/EPSG:3857/{z}/{x}/{y}.png

How to attribute LINZ All LDS tile service supported layers are available under a Creative Commons Attribution 3.0 New Zealand license, meaning you are free to use, reuse and share data as long as you attribute the work to LINZ as the original source of the data. See the LINZ website for general information in data licensing and attribution.

Use the attributes Tile layer option attribute the LINZ Data Service as the original source of the data:

attributions: [ new ol.Attribution({ html: ['LINZ. CC-BY 3.0'] }) ]

In the case of National Imagery, LINZ does not own the copyright of this data and requires a variation to the standard LINZ data attribution statement. You can make the attribution in the following way. This simply changes the URL to point to:

attributions: [ new ol.Attribution({ html: ['

Specify the custom coordinate reference system You then need to manually define the parameters of the NZTM2000 tile grid, specifying the extents, tile matrix origin and resolution. Much of this information can be found in the LDS tile set definitions document. The required functions are:

var projection = ol.proj.get('EPSG:2193'); projection.setExtent([827933.23, 3729820.29, 3195373.59, 7039943.58]);

var origin = [-1000000, 10000000];

var resolutions = [8960, 4480, 2240, 1120, 560, 280, 140, 70, 28, 14, 7, 2.8, 1.4, 0.7, 0.28, 0.14, 0.07];

var matrixIds = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16];

Step by step, first, call the Proj4 definition for NZTM2000 (EPSG:2193) and describe the extents of the coordinate system:

var projection = ol.proj.get('EPSG:2193'); projection.setExtent([827933.23, 3729820.29, 3195373.59, 7039943.58]);

Then define the origin of the LDS NZTM tile grid:

var origin = [-1000000, 10000000];

Then define the pre-determined resolutions and matrixids (zoom levels) for the LDS NZTM tile set:

var resolutions = [8960, 4480, 2240, 1120, 560, 280, 140, 70, 28, 14, 7, 2.8, 1.4, 0.7, 0.28, 0.14, 0.07];

var matrixIds = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16];

Use a WMTS style GetTile URL Now that you have manually defined the NZTM coordinate system, you need to use WMTS GetTile URLs. This will let OpenLayers determine the x, y and z parameters itself by drawing from the projection definition you have provided.

The WMTS URL syntax is:

http://tiles-{a-d}.data-cdn.linz.govt.nz/services;key=YOUR_API_KEY/tiles/v4/layer=767 /EPSG:2193/{TileMatrix}/{TileCol}/{TileRow}.png

You will also notice that the default EPSG value has been changed to the value for NZTM2000 (ESPG:2193).

Specify Layer options To enable OpenLayers to understand your custom projections, you also need to specify a number of Tile layer options, including identifying the layer type, source, encoding, projection and tileGrid.

var layer = new ol.layer.Tile source: new ol.source.WMTS url: urlTemplate, requestEncoding: 'REST', projection: projection, tileGrid: new ol.tilegrid.WMTS origin: origin, resolutions: resolutions, matrixIds: matrixIds })

}) });

See the full example below to view the complete variables for layer within context.

Also, remember also to transform coordinates to ESPG:2193 when setting the map center or bounds, and to use WGS84 lat/long coordinates:

center: ol.proj.transform([172.762057, -40.852931], 'EPSG:4326', 'EPSG:2193'),zoom: 2

Working examples of LDS imagery tile services See below for two examples of LDS tile services in OpenLayers using XYZ style requests. Both call the New Zealand Topo50 map tiles as a demonstration.

LDS tile services OpenLayers example in Web Mercator (XYZ) With the substitution of the API key placeholder with your own, the Web Mercator example will run in the browser.

NZ Topo50 EPSG:3857 Demo (OL3)

LDS tile services OpenLayers example in NZTM2000 (XYZ) The NZTM200 example will require you to install and call the Proj4 related resources to enable custom projections.

Using a Custom Map Projection - NZTM tile set (WMTS GetCapabilities) If you prefer, you can access our tile services via an OGC WMTS GetCapabilities tile request, rather than a XYZ style request. In this example for using the NZTM2000 tile set, your web client will use the WMTS Get Capabilities functionality to determine the tile matrix definition, rather than relying on configuration client side.

Enabling custom projection support with WMTS As with the XYZ example, you will need to add additional code to your application to be able to use a WMTS-styled custom projection within OpenLayers. This example requires a modified version of OpenLayers 3 that includes the functionality provided by 2 pull requests that are in the process of being incorporated into OpenLayers 3.

To begin, you need to add the Proj4js library to the header. You can then include the following patched OpenLayer library. Please bear in mind that these are only temporarily available:

Using LDS tile services in Leaflet

About this guide This guide provides hints and tips and notes issues to be aware of in using LDS XYZ tile services in Leaflet. This document is not a guide to using Leaflet and assumes a good understanding of JavaScript.

Please refer to the official Leaflet documentation for help.

Notes  The code snippets in this guide and referenced examples use Leaflet version 0.7.3  Unless specified, the examples in this guide assume use of the LDS web mercator (EPSG:3857) tile set  Leaflet does not support the Get FeatureInfo function for vector-based tile services

Adding a LDS tiled layer to your map To add a single LDS tiled layer the simple format is:

L.tileLayer('http://tiles-{s}.data-cdn.linz.govt.nz/services;key=YOUR_API_KEY/tiles/v 4/layer=LAYER_ID/EPSG:3857/{z}/{x}/{y}.png’)

Then specify the subdomains within the var settings option. This will allow Leaflet to get tiles from all four subdomains:

subdomains:'abcd'

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. Bear in mind, this method is not suitable if you require the ability to toggle individual layers on and off:

http://tiles-{s}.data-cdn.linz.govt.nz/services;key=YOUR_API_KEY/tiles/v4/ layer=LAYER_ID;layer=LAYER_ID/EPSG:3857/{z}/{x}/{y}.png

Use the Tile layer attribute option setting to attribute the LINZ Data Service as the original source of the data:

attribution: ‘Sourced from LINZ. CC-BY 3.0’

Using a custom map projection - NZTM tile set Leaflet does not support local projections out of the box, so if you are integrating LDS NZTM tile layers into your service, you will need to build support for this. This includes calling additional scripts to support custom projections, specifying the projection the tiles are in, the origin and resolutions by setting the crs option when creating your map object.

Enabling custom projection support There are a number of ways to set a projection. A great place to start for an explanation and examples of implementing custom projections in Leaflet is to see Kartena’s write up and their Proj4Leaflet project.

This implementation uses the Proj4 definition of the coordinate reference system to set the projection.

Call the Proj.4 library and Kartena’s Proj4Leaflet project by calling the following scripts in the header:

Specify the custom coordinate reference system Please refer to the LDS tile set definitions document to source the official Proj4 definition for NZTM and other variables, such as the resolutions and extents.

Define the NZTM coordinate reference system by specifying the crs option in the following way:

var crs = new L.Proj.CRS( 'EPSG:2193', '+proj=tmerc +lat_0=0 +lon_0=173 +k=0.9996 +x_0=1600000 +y_0=10000000 +ellps=GRS80 +towgs84=0,0,0,0,0,0,0 +units=m +no_defs', { origin: [-1000000, 10000000], resolutions: [8960, 4480, 2240, 1120, 560, 280, 140, 70, 28, 14, 7, 2.8, 1.4, 0.7, 0.28, 0.14, 0.07] } );

Step by step, first, add the Proj4 definition for NZTM2000 (EPSG:2193):

var crs = new L.Proj.CRS( 'EPSG:2193', '+proj=tmerc +lat_0=0 +lon_0=173 +k=0.9996 +x_0=1600000 +y_0=10000000 +ellps=GRS80 +towgs84=0,0,0,0,0,0,0 +units=m +no_defs',

Then define the origin of the LDS NZTM tile grid and the pre-determined resolutions for the LDS NZTM tile set:

{ origin: [-1000000, 10000000], resolutions: [8960, 4480, 2240, 1120, 560, 280, 140, 70, 28, 14, 7, 2.8, 1.4, 0.7, 0.28, 0.14, 0.07] } );

Then you simply need to reference the crs above within your Leaflet map options.

crs: crs,

Working examples of LDS imagery tile services See below for two examples of LDS tile services in Leaflet. Both call the New Zealand Topo50 map tiles as a demonstration.

LDS tile services Leaflet example in Web Mercator With the substitution of the API key placeholder with your own, the Web Mercator example will run in the browser.

LDS tile services Leaflet example in NZTM2000 To run the NZTM200 example, you will need to install and call the Proj4 related resources to enable custom projections.