Support

nearmap TMS integration

Last Updated: Mar 02, 2016 10:38AM AEDT

Important: This article is for Australian customers. Information for US customers can be found here: nearmap TMS integration for US customers.

Contents

 

   

nearmap provides access to its PhotoMaps imagery via a subset of the Tile Map Service (TMS) protocol. TMS splits a map into a pyramid of 256x256-pixel map tiles at multiple zoom levels. An application typically downloads a collection of adjacent tiles to cover a given region.

 

Only the Web Mercator projection is supported by nearmap’s TMS (EPSG:3857; also known as EPSG:3785 and EPSG:900913). nearmap’s Web Map Service (WMS) is recommended for other projections.

 

 

TMS URL Request Format

 

 

TMS is designed to be accessed by an application in an automated fashion via URL requests.

 

PhotoMaps imagery (called tiles in this documentation) may be requested by URLs in the following formats:

 
  • http://au.nearmap.com/maps?parameters


  • https://au.nearmap.com/maps?parameters

 

The following parameters may be specified:

 
Parameter Value Required?
x X tile coordinate (column)* yes
y Y tile coordinate (row)* yes
z Zoom level (highest resolution is typically 21) yes
nml Set the nml parameter according to the imagery type you want to retrieve. Note that not all imagery types are available for all locations and dates.
 
  • For vertical imagery, set: nml=V
  • For north oblique imagery, set: nml=N
  • For east oblique imagery, set: nml=E
  • For south oblique imagery, set: nml=S
  • For west oblique imagery, set: nml=W

To see the availability of imagery types, refer to the section on Getting a list of surveys by date for a location.
yes
nmd Date, in the format YYYYMMDD - for example, 20151031.
 
  • If specified, and imagery at that location at that date exists, the request returns the imagery.
  • If specified, and imagery at that location at that date does not exist, the request returns imagery of the closest previous date.
  • If not specified, the request returns the latest imagery.

See Getting a list of surveys by date for a location for instructions on retrieving options for setting this parameter.
no
version Must be set to 2 yes
ticket An authentication ticket can be provided via this parameter (see "Authentication via Ticket" below) no
username Although not recommended, the username for authentication can be provided via this parameter (in conjunction with a password), in lieu of a ticket no
password Although not recommended, the password for authentication can be provided via this parameter (in conjunction with a username), in lieu of a ticket no
httpauth Whether the tile server should prompt for HTTP basic authentication (default is true) no
 

* tile coordinates use the Google XYZ scheme.

 

A typical URL would be:

 

 

http://au.nearmap.com/maps?x=1206&y=1539&z=12&nml=v&version=2&httpauth=false

 

 

 

https://au.nearmap.com/maps?x=1206&y=1539&z=12&nml=v&version=2&httpauth=false

 

 

 

Authentication

 

 

nearmap tile access is only available to authenticated subscribers.

 

Authentication via username and password parameters

 

One authentication approach is to put the username and password onto each tile URL as indicated in the parameters list.

 

This is not optimal for security reasons, as the password remains visible in history on the user’s computer.

 

Authentication via ticket

 

The client application retrieves an authentication token, which it then supplies with each imagery request.

 

The following URL authentication scheme uses opaque authentication tokens.

 
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
 

This 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"
    		}
    		

     


  3. The Mashup backend must configure the mashup page to use nearmap tile urls containing the returned ticket:

     

     

    var nearmapTileUrlTemplate = 
    			"http://au.nearmap.com/maps?x={X}&y={Y}&z={Z}&nml=v
    			&ticket=ABCDEF1234&httpauth=false&version=2"

     

 

This 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).

 

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

 

 

Getting a list of surveys by date for a location

 

 

URL Format

 

 

http://au.nearmap.com/maps?ll=LAT,LONG&nmq=INFO&nmf=json&zoom=18

 

 

URL Parameters

 
Parameter Meaning Example
RC Region code us
ll Latitude and longitude of the location on which to centre the image in the format LAT,LONG 37.334849,-122.008946
zoom Image zoom (web mercator zoom). Has to be 18. 18
nmq Must be set to INFO INFO
nmf Must be set to json json
ticket Authentication ticket A325BF1343...
 

Survey date lists in JSON response

 

The JSON response contains a set of lists of oblique and vertical image types, with the dates for which imagery is available in the given location. Not all image types will necessarily be available for a location.

 
JSON Item Meaning Example
"E___"
A list of survey dates with oblique imagery facing East
"E___":["\/Date(1430352000000)\/"]
"N___"
A list of survey dates with oblique imagery facing North
"N___":["\/Date(1430352000000)\/"]
"S___"
A list of survey dates with oblique imagery facing South
"S___":["\/Date(1430352000000)\/"]
"Vert"
A list of survey dates with vertical imagery
"Vert":[
"\/Date(1349222400000)\/",
"\/Date(1394668800000)\/",
"\/Date(1430352000000)\/"
]
 

Example 1: An Australian location with oblique imagery and verticals

 

Request:

 

 

http://au.nearmap.com/maps?ll=-38.190225,146.249136&nmq=INFO&nmf=json&zoom=18

 

 

Response:

 

 

{	
	"layers": 
	{
		"E___":["\/Date(1430352000000)\/"],
		"N___":["\/Date(1430352000000)\/"],
		"S___":["\/Date(1430352000000)\/"],
		"Vert":[
			"\/Date(1349222400000)\/",
			"\/Date(1394668800000)\/",
			"\/Date(1430352000000)\/"
			],
		"W___":["\/Date(1430352000000)\/"]
	},
	"within_allowed_area":1,
	"coverage_status": "full", 
	"area_type": null 
}

 

The values are timestamps formatted using ASP.NET AJAX date format. The numeric value inside the parenthesis is number of milliseconds since epoch - January 1 1970 UTC.

 

See the description of the TMS URL Request Format for instructions on using the date as a parameter to request imagery.

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