The LINZ Basemaps APIs allow you to programmatically access LINZ map tile services to integrate into your mobile, web or GIS app. This documentation provides an overview of our map tile APIs and how to use them.

WMTS map tile services

LINZ Basemaps supports WMTS version 1.0.0. While best suited for use in GIS apps, WMTS can also be deployed in Javascript clients.

Visit the Open Geospatial Consortium website for information about the standard.

Open Geospatial Consortium

If you're looking for step-by-step instructions for using WMTS in GIS apps, you can follow the same process we describe for using LINZ Data Service WMTS in QGIS and ArcGIS Desktop.

WMTS URL syntax

https://basemaps.linz.govt.nz/v1/tiles/{tileset_name}/WMTSCapabilities.xml?api={api_key}
Required parametersDescriptionValues
tileset_name

Unique identifier of the LINZ Basemaps map tiles API

'aerial'
api_keyInsert your allocated API key 

Example request: Retrieve map tiles via WMTS

As an example, a complete URL for a WMTS request for the Aerial Imagery map tile API would look like the following. Simply replace the api_key placeholder with your own.

https://basemaps.linz.govt.nz/v1/tiles/aerial/WMTSCapabilities.xml?api={api_key}

XYZ map tile services

LINZ Basemaps supports XYZ style requests, for integration of our APIs in mapping clients such as Leaflet and OpenLayers. Some of the latest versions of GIS apps also now support XYZ map tiles services.

XYZ URL syntax

https://basemaps.linz.govt.nz/v1/tiles/{tileset_name}/{crs}/{z}/{x}/{y}.{format}?api={api_key}
Required parametersDescriptionValues
tileset_nameUnique identifier of the LINZ Basemaps map tiles API'aerial'
crsTileset projection to request'2193' (for NZTM2000); or '3857' (for Web Mercator)
zSpecifies the tile's zoom level, as described in the Tileset schema 
x ySpecifies the tile's column {x} and row {y}, as described in the Tileset schema 
formatImage format to request'png'; 'jpeg'; or 'webp'
api_keyInsert your allocated API key 

Example request: Retrieve map tiles via XYZ

As an example, a complete URL for a XYZ request for the Aerial Imagery map tile API in WGS84 would look like the following. Simply replace the api_key placeholder with your own.

https://basemaps.linz.govt.nz/v1/tiles/aerial/3857/9/502/321.png?api={api_key}

Adding a LINZ Basemap API to your map

This example shows the basic elements required to add the LINZ Aerial Imagery Basemap in Web Mercator to an OpenLayers map:

<div id="map" style="width: 600px; height: 400px;"></div>

<script>

var url = "https://basemaps.linz.govt.nz/v1/tiles/aerial/3857/{z}/{x}/{y}.webp?api={api_key}";

var attr = '<a href="//www.linz.govt.nz/data/linz-data/linz-basemaps/data-attribution">LINZ CC BY 4.0 © Imagery Basemap contributors</a>';

var map = new ol.Map({

   target: "map",

   layers: [

      new ol.layer.Tile({

         source: new ol.source.XYZ({

            url: url,

            attributions: [attr]

         })

      })

   ],

   view: new ol.View({

      center: [19467552, -5074414];

      zoom: 6

   })

});

</script>

This example shows the basic elements required to add the LINZ Aerial Imagery Basemap in Web Mercator to a Leaflet map:

<div id="map" style="width: 600px; height: 400px;"></div>

<script>

var url = "https://basemaps.linz.govt.nz/v1/tiles/aerial/3857/{z}/{x}/{y}.webp?api={api_key}";

var attr = '<a href="//www.linz.govt.nz/data/linz-data/linz-basemaps/data-attribution">LINZ CC BY 4.0 © Imagery Basemap contributors</a>';

var tiles = L.tileLayer(url, {

   attribution: attr

});

var map = L.map("map")

   .addLayer(tiles)

   .setView([-40.5, 173], 6);

</script>

Adding the LINZ Aerial Imagery Basemap using WMTS requires additional elements. The following example shows how you can do this using OpenLayers:

<div id="map" style="width: 500px; height: 500px;"></div>

<script>

var proj_str = "EPSG:3857";

var url = "https://basemaps.linz.govt.nz/v1/tiles/aerial/3857/WMTSCapabilities.xml?api=api_key";

var attributions = '<a href="//www.linz.govt.nz/data/linz-data/linz-basemaps/data-attribution">LINZ CC BY 4.0 © Imagery Basemap contributors</a>';

var projection = ol.proj.get(proj_str);

var size = ol.extent.getWidth(projection.getExtent()) / 256;

var resolutions = new Array(14);

var matrixIds = new Array(14);

for (var z = 0; z < 14; ++z) {

    resolutions[z] = size / Math.pow(2, z);

    matrixIds[z] = z;

}

var parser = new ol.format.WMTSCapabilities();

var grid = new ol.tilegrid.WMTS({

    origin: ol.extent.getTopLeft(projectionExtent),

    resolutions: resolutions,

    matrixIds: matrixIds

});

fetch(url).then(async resp => {

    var text = await resp.text();

    var result = parser.read(text);

    var options = ol.source.WMTS.optionsFromCapabilities(result, {

        layer: "aerial-3857",

        projection: proj_str,

        tileGrid: grid,

        style: "default"

    });

    var tiles = new ol.layer.Tile({

        source: new ol.source.WMTS(options),

        projection: projection,

    });

    var map = new ol.Map({

        layers: [tiles],

        target: "map",

        view: new ol.View({

            center: [19467552, -5074414],

            zoom: 6

        });

    });

});

</script>

Adding attribution

You must properly attribute and link to LINZ and our data sources when using the LINZ Basemaps API. Mapping libraries like Leaflet and OpenLayers do not do this for you automatically, so you must add it yourself.

This example for Leaflet uses the attribution control and addAttribution function:

var credits = L.control.attribution().addTo(map); credits.addAttribution('© <a href="//www.linz.govt.nz/linz-copyright">LINZ CC BY 4.0</a> © <a href="//www.linz.govt.nz/data/linz-data/linz-basemaps/data-attribution">Imagery Basemap contributors</a>');
Last Updated: 22 July 2020