Support

nearmap Image APIs

Last Updated: May 14, 2015 05:31PM AEST

Authentication via ticket


nearmap tile access is only available to authenticated subscribers. When a web application would like to use nearmap imagery and have the end user of such application request tiles directly from nearmap.com servers, the end user has to pass through some sort of authentication token in order for tiles to be served.


The following URL authentication scheme uses opaque authentication tokens.


Terminology


Term Meaning
Third party website or application A website or application that wants to offer a mashup of nearmap imagery and their own functionality
Mashup A web page, or application, that uses content from more than one source (i.e. nearmap and other data) to create a single new service displayed in a single graphical interface
Consumer A user of the Third party website or application
Ticket Encrypted authentication token that allows nearmap tile servers to serve a tile to Consumer
Tile server nearmap server that hosts map tiles
Tile 256x256 pixel map image
Third party cookie Cookie that Tile server uses whilst serving a Tile from within Mashup

Preferred ticket authentication flow


The authentication flow leverages the ticket (cookie) mechanism and allows access to nearmap tiles in a manner more like API integration.


  1. Mashup backend must perform a Web API call to the nearmap checkaccess API. Use the following format:


    https://app.nearmap.com/api/0/checkaccess?
    			username={USERNAME}&password={PASSWORD}&expiry_seconds=86400


  2. The nearmap Response contains approximately the following:


    		{
    			"AccountId": "account000000",
    			"AuthenticationRequiredReason": null,
    			"CookieName": "nearmap_web3_app",
    			"Expires": "/Date(71705221200000)/",
    			"Status": "Ok",
    			"Ticket": "ABCDEF1234",
    			"Username": "mashup_site"
    		}
    		


Integration Notes


The ticket generation mechanism is designed to create long-lived cookies. This process sees nearmap issue tickets that last about 24 hours (snapped to 15 minute intervals). Note that a ticket is rendered invalid if a subsequent ticket is created for the same user, including if that user logs in to the map browser.


The tiles that are served via URLs with ticket do not themselves issue a ticket cookie, thus making those requests more stateless.


Retrieving an image centred on a location


URL Format


http://[RC].nearmap.com/staticmap?center=[CENTER LAT LON]
&size=[WIDTHxHEIGHT]&zoom=[ZOOM]&date=[DATE]&ticket=[TICKET]


URL Parameters


Parameter Meaning Example
RC Region code us
center Latitude and Longitude of the location on which to centre the image in the format 37.334849,-122.008946
size Size of the image in pixels 800x800
zoom Image zoom (web mercator zoom). 18
date Date of the image, in the format YYYYMMDD 20150314
ticket Authentication ticket A325BF1343...

Example


http://us.nearmap.com/staticmap?center=37.334849,-
122.008946&size=800x800&zoom=18&date=20150205&ticket=


Getting a bounded image for a location


URL Format


http://[RC].nearmap.com/staticmap?bbox=[BOUNDING BOX]&
zoom=[ZOOM]&date=[DATE]&ticket=[TICKET]


URL Parameters


Parameter Meaning Example
RC Region code us
bbox Bounding box in the format [MIN LAT,MIN LON,MAX LAT,MAX LON] 37.33197414633263,-122.0126095035584,
37.33767824148404,-122.00526382713622
zoom Image zoom (web mercator zoom). 18
date Date of the image, in the format YYYYMMDD 20150314
ticket Authentication ticket A325BF1343...

Example


http://us.nearmap.com/staticmap?bbox=37.33197414633263,-122.0126095035584,37.33767824148404,
-122.00526382713622&nmd=20150216&zoom=18&date=20150205&ticket=


Note on "best" zoom


When using the value "best" for zoom level, the system will generate the biggest image in terms of pixels for the specified location.

support@nearmap.com
https://cdn.desk.com/
false
desk
Loading
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
about
false
Invalid characters found
/customer/en_au/portal/articles/autocomplete