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

This guide also provides hints and tips for using LDS XYZ tile services in Leaflet, and includes examples using XYZ style tile requests.

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.

See Using LINZ basemaps in Javascript for useful 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 developing 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}.data-cdn.linz.govt.nz/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 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‑{a‑d}.data‑cdn.linz.govt.nz/services;key=YOUR_API_KEY/tiles/v4/set=SET_ID/EPSG:CRS/{z}/{x}/{y}.png

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 the full VectorQuery API documentation.

How to attribute LINZ

All LDS tile service supported layers are available under a Creative Commons Attribution 4.0 International 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.

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, 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 the aerial image attribution page:

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

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.

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

Reference Category: Map tile services
Reference Tags: XYZ tile services, Leaflet, Javascript
Last Updated: 
11 July 2018