Using LDS XYZ services in Leaflet

A step-by-step guide to setting up a Leaflet map using LDS XYZ tiles.

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

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:

script src="https://cdnjs.cloudflare.com/ajax/libs/proj4js/2.4.4/proj4.js">script> script src="http://rawgit.com/kartena/Proj4Leaflet/master/src/proj4leaflet.js">script>

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.

html>
head>

meta charset="utf-8" />

meta name="description" content="NZ Topo50 Web Mercator EPSG:3857 demo(Leaflet)" />

link rel="stylesheet" href="https://unpkg.com/leaflet@1.3.1/dist/leaflet.css" />

script src="https://unpkg.com/leaflet@1.3.1/dist/leaflet.js">script>

head>
body>
div id="map">div>
body>
style>
html, body {
height:100%;
padding:0;
margin:0;
}
#map {
height: 100%;
}
style>
script>
// Enter your LDS API key
var APIKey = 'YOUR_API_KEY';

// LDS tile URL
var urlTemplate = 'http://tiles-{s}.data-cdn.linz.govt.nz/services;key=' + APIKey + '/tiles/v4/layer=50767/EPSG:3857/{z}/{x}/{y}.png'

var settings = {
maxZoom: 17,
continuousWorld: true,
attribution: 'Sourced from LINZ. CC BY 4.0',
subdomains:'abcd'
};

var map = new L.Map('map', {
crs: L.CRS.EPSG3857,
continuousWorld: true,
worldCopyJump: false,
zoomControl: false
});

var tilelayer = new L.TileLayer(urlTemplate, settings);
map.addLayer(tilelayer);

map.setView([-40.852931, 172.762057], 6);
script>
html>

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.

html>
head>
meta charset="utf-8" />
meta name="description" content="NZ Aerial Imagery NZTM demo (Leaflet)" />

link rel="stylesheet" href="https://unpkg.com/leaflet@1.3.1/dist/leaflet.css" />

script src="https://unpkg.com/leaflet@1.3.1/dist/leaflet.js">script>

script src="https://cdnjs.cloudflare.com/ajax/libs/proj4js/2.4.4/proj4.js">script>

script src="http://rawgit.com/kartena/Proj4Leaflet/master/src/proj4leaflet.js">script>

/head>
body>
div id="map">div>
body>
style>
html, body {
height:100%;
padding:0;
margin:0;
}
#map {
height: 100%;
}
style>
script>
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]
}
);

// LDS API key. Please use your own API key
var APIKey = 'YOUR_API_KEY';

// LDS tile URL
var urlTemplate = 'http://tiles-{s}.data-cdn.linz.govt.nz/services;key=' + APIKey + '/tiles/v4/set=4702/EPSG:2193/{z}/{x}/{y}.png'

var settings = {
maxZoom: 17,
continuousWorld: true,
attribution: 'Sourced from LINZ. LINZ. CC BY 4.0', 
//Simple attribution for linz subdomains:'abcd'
};

var map = new L.Map('map', {
crs: crs,
continuousWorld: true,
worldCopyJump: false,
zoomControl: false
});

var tilelayer = new L.TileLayer(urlTemplate, settings);
map.addLayer(tilelayer);

map.setView([-40.852931, 172.762057], 2);
script>
html>
Last updated