This guide provides information on using LDS XYZ tile services in Leaflet, and includes examples using XYZ style tile requests. It is not a guide to using Leaflet and assumes a good understanding of JavaScript.
Refer to the official Leaflet documentation for help.
See Using LINZ basemaps in Javascript for information on available map services, URL syntax, domains and response formats.
Notes before you begin
- The code snippets in this guide and referenced examples use Leaflet version 1.3.1.
- 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 without additional code.
Read the guide
- Adding an LDS tiled layer to your map
- How to attribute Toitū Te Whenua
- Using a custom map projection - NZTM tile set
- Working examples of LDS imagery tile service
Adding an LDS tiled layer to your map
To add a single LDS tiled layer the simple format is:
L.tileLayer('http://tiles-{s}.tiles-cdn.koordinates.com/services;key=YOUR_API_KEY/tiles/v4/layer=LAYER_ID/EPSG:3857/{z}/{x}/{y}.png’)
Then specify the subdomains within the TileLayer class’s options parameter. This will allow Leaflet to get tiles from all 4 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. This method is not suitable if you need to toggle individual layers on and off.
http://tiles {a d}.tiles cdn.koordinates.com/services;key=YOUR_API_KEY/tiles/v4/set=SET_ID/EPSG:CRS/{z}/{x}/{y}.png
Vector Query API
You may want 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 the full VectorQuery API documentation.
How to attribute Toitū Te Whenua
All LDS tile service supported layers are available under a Creative Commons Attribution 4.0 International license. You are free to use, reuse and share data as long as you attribute the work to Toitū Te Whenua as the original source of the data.
Use the Tile layer attribute option setting to attribute the LINZ Data Service as the original source of the data:
attribution: ‘<a href=“http://data.linz.govt.nz”>Sourced from LINZ. CC BY 4.0</a>’
In the case of the NZ Aerial Imagery basemap and individual Aerial Photos, Toitū Te Whenua does not own the copyright of this data and requires a variation to the standard Toitū Te Whenua data attribution statement. You can make the attribution in the following way, which changes the URL to point to the aerial image attribution page:
attribution: ‘<a href="/data/licensing-and-using-data/attributing-aerial-imagery-data">Sourced from LINZ. CC BY 4.0</a>’
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 replace option when creating your map object.
Enabling custom projection support
There are a number of ways to set a projection. See Kartena’s Proj4Leaflet project for using 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
Refer to the LDS tile set definitions document for the official Proj4 definition for NZTM and other variables, such as 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] } );
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 need to reference the crs above within your Leaflet map options.
crs: crs,
Working examples of LDS imagery tile services
See below for 2 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 NZTM2000 example, you will need to call the Proj4 related resources to enable custom projections.