Using LDS tile services in Javascript

Get 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 easily combined with other global map tile services such as Open Street Map (OSM) or Microsoft Bing Maps.

Before you begin, please 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}.data‑cdn.linz.govt.nz/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 tile column and y tile row but your client will substitute values here for you

Please note: 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}.data‑cdn.linz.govt.nz/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 and 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}.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.

Vector Query API

You may wish to 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 use 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 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 configure 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 it reduces the configuration client side.

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, the ‘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
Reference Category: Basemaps
Reference Tags: XYZ tile services, Javascript
Last Updated: 
17 September 2018