Recent Changes - Search:

add Cookbook page

hide Cookbook


hide Topics


show Changed


Visitor's book Site map pmwiki-2.3.33

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" title="Display NZ Topo map" load="lazy" frameborder="0" scrolling="no" marginheight="0" marginwidth="0" width=999px height=99px src="">

Set the width and height as required. 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 publicly 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]

Searching on

You can search for topo map coords and in the search results you'll see the lat lon in the search result. Examples of coordinate formats you can search for:

NZTM: 1577101E 5173728N; 1577101E,5173728N; 1577101E, 5173728N; E1577101 N5173728; 5173728N 1577101E; 5460761.411 1684102.134; BJ37, E1893018, N5641170; BX18, E1423180, N5171994;

NZTM map ref: BX24 771 737; BX24 771737; BX24771737; BX24:771-737; 771 737; 771-737; 771737

Older NZMG maps ref: M35 885 445; M35 885445; M35:885-445;


tahi Page last modified on 2022 Aug 14 11:32

Edit - History - Recent Changes - WikiHelp - Search - email page as link -> mailto:?Subject="KiwiWiki: NZ Topo API"&Body=