Summer services update
Information Summer services update

Our offices and services will have reduced availability over the holiday period.  Read more about our holiday hours and services availability.

Using LDS tile services in Javascript

An overview of using LDS XYZ and WMTS tile services in Javascript clients.

LINZ Data Service tile services are available as an XYZ tile service for Javascript clients – this is our recommended service for web developers. Web Map Tile Service (WMTS) style requests are also available.

As a free, public service, our tile services are best suited for use in small- to medium-volume web mapping applications. 

This service is compatible with the Google Map API and can be combined with other global map tile services such as Open Street Map (OSM) or Microsoft Bing Maps.

Before you begin, you should familiarise yourself with the LINZ Data Service Web Map Tile Service specifications (links at bottom). Then follow a step-by-step guide for using LINZ basemaps and map services in Leaflet or OpenLayers.

LDS XYZ tile services

XYZ URL syntax

LDS web map tile services support both HTTP and HTTPS.

To access our XYZ tile services, you can use the following base URL in your application:

http://tiles {a d}.tiles cdn.koordinates.com/services;key=YOUR_API_KEY/tiles/v4/layer=LAYER_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 
  • LAYER_ID – the identifier of the LDS web map tiled layer. For example, the layer id for the Topo50 Maps is layer 50767: https://data.linz.govt.nz/layer/50767-nz-topo50-maps
  • 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 is tile column, and y is tile row, but your client will substitute values here for you.

Note that some map tile services are created from a collection of several data layers. In these cases, LAYER_ID is replaced by SET_ID in the URL:

http://tiles {a d}.tiles cdn.koordinates.com/services;key=YOUR_API_KEY/tiles/v4/set=SET_ID/EPSG:CRS/{z}/{x}/{y}.png
  • SET_ID - the identifier of the LDS web map tiled set. This follows the same principle as above.

Domains

To ensure the best 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}.tiles-cdn.koordinates.com

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.

Vector Query API

You can overlay vector data into your web map client to highlight points of interest, specific attributes or selected features. The best way to do this is using the LDS Vector Query API.

Read our Vector Query API documentation for more information

Hiding your API key

If you are integrating LDS tile services into a public map service, you will need to prevent your API key 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 configure URL requests to retrieve tiles. In this method, your web client will use the GetCapabilities request to determine the tilematrix definition. This means one more request for your client, but it reduces client-side configuration.

An example of using the LDS NZTM2000 tile set via the WMTS Get Capabilities functionality is provided in the OpenLayers guide. 

The base URL for this request format is:

https://data.linz.govt.nz/services;key=YOUR_API_KEY/wmts/1.0.0/layer/LAYER_ID/WMTSCapabilities.xml

Some of the URL components are similar to the XYZ example above:

  • YOUR_API_KEY – your LDS API key
  • LAYER_ID – the identifier of the LDS web map tiled layer. For example, the layer id for the Topo50 Maps is layer 50767: https://data.linz.govt.nz/layer/50767-nz-topo50-maps/

If you are accessing an LDS tile service comprising multiple layers, ‘layer’ is replaced by ‘set’ in the URL:

https://data.linz.govt.nz/services;key=YOUR_API_KEY/wmts/1.0.0/set/SET_ID/WMTSCapabilities.xml
  • SET_ID – the identifier of the LDS web map tiled set
Last updated