Recent Changes - Search:

add Cookbook page







Visitor's book Site map pmwiki-2.3.2

NZ Topo API API documentation

A description, not available elsewhere, of the API, as used to display an excerpt from a map in PmWiki using the Cookbook:NZTopo recipe, see NZTopo.

Note that code examples below use PHP.

The URL for browser service is

The URL for embedded service is

The URL for the GPX proxy service is

Parameter details are described using Regex.


You can specify a locale as a decimal WGS84 latitude and longitude (ll), in NZTM coordinates (nzne), as a Topo50 map reference (mapref), or specify a publicly accessible the URL of a gpx or kml file to overlay on the map (kml, gmx).

The scale of the map, but not the image, will automatically resize to the area covered by the kml / gpx data.

You can specify bounds of an area, by latitude and longitude (llbs), or NZTM coordinates (nzbs).

You can optionally specify to show a pin marker (pin), and again optionally show a tool tip label for the marker (label).


The embedded service inserts an image in the iframe provided, e.g.

<div class="nztopo" >
  <iframe class="nztopoframe" seamless frameborder="0" scrolling="no" marginheight="0" marginwidth="0" width=999px height=99px src="">

The image is ~80 pixels per centimetre to provide base scale for maps (guess, as no information was available when requested)


v=2 -- version must be 2
  • ll= -- centre point of the map as a decimal latitude,longitude
  • llbs= -- decimal latitude longitude bounds: latitude,longitude;latitude,longitude[;latitude,longitude...]
  • nzne= -- centre point of the map as an NZTM northing,easting
  • nzbs= -- NZTM bounds: northing,easting;northing,easting[;northing,easting...]
  • mapref= -- NZ Topo50 grid reference, AAxxxyyy, e.g. BN33991890
  • kml= -- URL to kml/GeoRSS file
  • gpx= -- URL to gpx file

Only one of: ll; llbs; nzne; nzbs; kml; gpx; can be specified

  • raw=1 -- DropBox files (1)
  • pin=1 -- show pin (1)
  • label= -- tool tip label for pin
  • zoom= -- scale factor for map (5 to 15), zoom is ignored when bounds parameters are supplied
    zoom 5 to 12 show the Topo250 map series
    zoom 13 to 15 show the Topo50.
  • new=1 -- open in new window (1)


Preparing kml and gpx parameters

nztopomap processes gml and kml parameters differently. To ensure that gml and kml URLs are parsed correctly by nztopomap they must be encoded differently.

gpx processing

$enc_url = rawurlencode('' . htmlentities(rawurldecode(trim($gpx_url, ' \'\"'))));

kml processing

For the kml parameter the topomap API is inconsistent. The kml path is urlencoded separately to the full url string, specifically

rawurlencode('' . rawurldecode(trim(filename.gpx, ' \'\"'))) works, but
rawurlencode( rawurldecode(trim(filename.kml, ' \'\"'))) does not

Code example:

function encode_kml ($kml_url) {
    $temp_url = # decode for parse_url and to start with known state (user may for example provide spaces in the URL string)
        htmlentities(         # protect against injection attacks
            rawurldecode(trim($kml_url, ' \'\"'))); # trim single and double quotes and spaces
    $parsed_url = parse_url($temp_url); # extract url components
    $parsed_url['path'] = rawurlencode(substr($parsed_url['path'], 1)); # encode path separately again,  dropping leading '/'
    $enc_url = ''; # reconstruct URL
    $enc_url .= (bool) $parsed_url['scheme'] ? $parsed_url['scheme'] . '://' : ''; # aka http or https
    $enc_url .= (bool) $parsed_url['host']   ? $parsed_url['host']           : ''; # domain name
    $enc_url .= (bool) $parsed_url['port']   ? ':' . $parsed_url['port']     : ''; # port
    $enc_url .= (bool) $parsed_url['path']   ? '/' . $parsed_url['path']     : ''; # add '/' dropped before as topomap considers it part of the host
    # query and fragment omitted
    return rawurlencode ($enc_url); # finally encode url and return it  
): # end encode_kml

PHP functions used are:

kml and gpx examples

Test files are

When loaded to in the 'share map' add KML / GPX overlay, this is the 'test on map' link generated by topomap

Specifically note that for the kml file the encoding is


and for the gpx file the encoding is


The inconsistency is that for kml files spaces are encoded as @2520 and for gpx files spaces are encoded as @20.


For the bounds llbs and nzbs parameters only two coordinates need to be supplied, but they take any number of coordinates. If a user had a bunch of coordinates they're interested in they don't need to manually calculate the two corner points to pass in themselves. Passing in all of them and allows the map work out what the bounding box is, e.g. they might have 10 waypoints from a tramp - they can just pass all 10 coordinates in and the map will adjust its bounds to make sure all 10 waypoint coordinates are visible.

The API for specifying a gpx file differs from that for specifying a kml file. See the code for the extra handling required to use the API with a kml file.

Web server

The gpx and kml files must be publically readable, e.g. from your website, Google Driver, OneDrive, or DropBox. If you are serving them from a website your web server must be able to serve gpx and kml files. You will need to add the media types

  • kml = application/
  • gpx = application/gpx+xml[2]


Page last modified on 2022 Jan 11 23:25

Edit - History - Recent Changes - WikiHelp - Search - email page as link -> mailto:?Subject=KiwiWiki: NZ Topo API&Body=From KiwiWiki: NZ Topo API (https://kiwiwiki [period] nz/pmwiki/pmwiki [period] php/Cookbook/NZTopoAPI) - topomap [period] co [period] nz API documentation