topomap.co.nz API documentation
A description, not available elsewhere, of the https://www.topomap.co.nz/ 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
https://www.topomap.co.nz/NZTopoMap
The URL for embedded service is
https://www.topomap.co.nz/NZTopoMapEmbedded
The URL for the GPX proxy service is
https://www.topomap.co.nz/proxy.ashx
Parameter details are described using Regex.
Usage
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).
Embedded
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="https://www.topomap.co.nz/etc...">
</iframe>
</div>
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)
Parameters
ll=latitude,longitude
llbs=latitude,longitude;latitude,longitude[;latitude,longitude...]
nzne=northing,easting
nzbs=northing,easting;northing,easting[;northing,easting...]
mapref=mapref
kml="url"
gpx="url"
pin=1
label="string"
zoom=number
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
Examples
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('https://www.topomap.co.nz/proxy.ashx?' . 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('https://www.topomap.co.nz/proxy.ashx?' . 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 https://www.topomap.co.nz/ 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
2014-05-30%252013_54_13.kml
and for the gpx file the encoding is
2010%2010%2023.gpx
The inconsistency is that for kml files spaces are encoded as @2520 and for gpx files spaces are encoded as @20.
Notes
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/vnd.google-earth.kml+xml
- gpx =
application/gpx+xml[2]
Searching on topomap.co.nz
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;
References
