Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Warning

This API is now deprecated. We are continuing to support this API for existing integrations, however new integrations should be using the new Tile API, in conjunction with the Coverage API.

At a future time this API will become unavailable. We will communicate the plan for removing the API with customers soon, with a substantial notice period.

This guide includes the following sections:

Table of Contents

Introduction

Nearmap provides access to its vertical imagery via a subset of the Tile Map Service Vertical and Panorama Imagery via a Tile API (TMS) protocol. TMS The Tile protocol 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.

Panorama Imagery

Nearmap Panorama imagery is an orthorectified mosaic of 45 degree imagery from each cardinal direction (North, South, East, West), intended for visualisation use only.

The intended use of the Panorama TMS API is integration of Panorama imagery in a third-party web application, also for visualisation only.

Because it is created by combining many images, metadata that is normally associated with oblique imagery (such as pose and calibration), is not available. All the metadata available for panorama imagery is described under Getting a List of Surveys by Date for a Location.

Info

Availability

The Panorama imagery is only available to customers with a Nearmap Panorama or Nearmap Oblique product.

Integration of Panorama tiles into a mapping application is complex. You will need to have significant experience with coordinate system geometry and map projections, and experience developing non-trivial mapping applications with a mapping framework such as OpenLayers or Leaflet.

Authentication

Access to Nearmap imagery is only available to authenticated subscribers. Tiles may be requested from Nearmap servers with an API Key. Please refer to the API Key Authentication guide for details on how to obtain and use an API Key.

Data Types Available through the API

Nearmap Tile API consists of a couple of individual HTTP APIs, which are used in conjunction:

  • Info API -  for retrieving imagery dates
  • TMS

...

  • API -  for retrieving vertical and panorama tiles

URL Requests

Tile API is designed to be accessed by an application in an automated fashion via URL requests. We recommend that you use a mapping framework designed to consume tiled maps, such as Google Maps JavaScript APIOpenLayersLeaflet, etc. PhotoMaps

TMS API URL Format

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

  • http://[RC][NUMBER].nearmap.com/maps?parameters
  • https://[RC][NUMBER].nearmap.com/maps?parameters

The following parameters may be specified: 

...

Parameters

RequiredNameTypeDescription

(tick)

RCstringThe region code. For example, au or us. Note: the region code for New Zealand is also au.
yes

(tick)

NUMBER
Domain
integer

The domain rotation number. Valid numbers are 0-3.

yes

Domain rotation is used to drive traffic from multiple domains to a single IP address. 

(tick)

xintegerThe X tile coordinate (column)
*yes
. Uses the Google XYZ scheme.

(tick)

yintegerThe Y tile coordinate (row)
*yes
. Uses the Google XYZ scheme.

(tick)

z
Zoom level (
integer

The zoom level. The highest resolution is typically 21

) *yesnmlMust be set to vyesnmdDate, in the format YYYYMMDD - for

. Uses the Google XYZ scheme.

Read about the zoom levels.

(tick)

nmlstring

The orientation of the imagery:

Vertical Imagery:

  • For vertical imagery, set: nml=V

Panorama Imagery:

  • For North panorama imagery, set: nml=N
  • For East panorama imagery, set: nml=E
  • For South panorama imagery, set: nml=S
  • For West panorama imagery, set: nml=W

(error)

nmdinteger

The date in the format YYYYMMDD. For example, 20151031.

Notes:

  • 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 

See Getting a

list

List of

surveys

Surveys by

date

Date for a

location for

Location for instructions on retrieving options for setting this parameter.

no

(error)

excludestringMust be set to background. Used to exclude tertiary satellite imagery when Nearmap imagery is not available.
no

(tick)

versionintegerThe version number. Must be set to 2.
yes

(tick)

httpauth
Whether
BooleanIndicates whether the tile server should prompt for HTTP
Basic
basic authentication. Set this to false (
as
we no longer support HTTP
Basic
basic authentication).
yes

(tick)

apikeystringYour API
Key
key.
See 
See API Key Authentication for more information.
yes

 

* tile coordinates use the Google XYZ scheme.

...

Examples

The following examples show two typical URL requests, one over http, and the other over https:

Code Block
themeEclipse
http://

...

au0.nearmap.com/maps?x=

...

115995&y=

...

79117&z=

...

17&nml=v&version=2

...

&httpauth=false&apikey=

...

ZjNhZDkyNDUtZjIyMS00NTkwLWJlMzYtZDJlNWUyNDkxNjE4

https://

...

us1.nearmap.com/maps?x=

...

119799&y=

...

215845&z=

...

19&nml=v&version=2

...

&httpauth=false&apikey=

...

ZjNhZDkyNDUtZjIyMS00NTkwLWJlMzYtZDJlNWUyNDkxNjE4

Getting a List of Surveys by Date for a Location

This section includes how to get a list of surveys by date for a location using the INFO API, and an explanation about the survey lists in the JSON response.

INFO API URL Format

Nearmap surveys may be requested by URLs in the following format:

http://[RC][NUMBER].nearmap.com/maps?ll=LAT,LONG&nmq=INFO&nmf=json&z=18
&apikey=YOUR_API_KEY

URL Parameters 

...

Parameters

RequiredNameTypeDescription

(tick)

RC
Region
stringThe region code.
Either us or au. Note: the region code for New Zealand is also au.usNUMBERDomain
For example, au or us.

(tick)

NUMBERinteger, integer

The domain rotation number. Valid numbers are 0-3.

0

Domain rotation is used to drive traffic from multiple domains to a single IP address. 

(tick)

llintegerLatitude and longitude of the location on which to centre the image, in the format LAT,LONG
. For example, 37.334849,-122.008946.

(tick)

z
Image zoom (
integerThe zoom level. The web mercator zoom
). Has to be
is used. This parameter must be set to 18.
18

(tick)

nmq
Must
string

The request. The parameter must be set to INFO.

INFO

(tick)

nmf
Must
integer

The response format. The parameter must be set to json.

json

(tick)

httpauthBoolean
Whether
Indicates whether the tile server should prompt for HTTP
Basic
basic authentication. Set this to false (
as
we no longer support HTTP
Basic
basic authentication).
 false

(tick)

apikeystringYour API
Key
key.
 See 
See API Key Authentication for more information.
A325BF1343...

Survey

...

Lists in JSON Response

The JSON response contains a set of lists of dates for which vertical imagery is available at the given location.  The dates are presented in The response contains an array with the label "Vert". 

Example for a US Location

...

for each of the different content types.

Attributes

NameDescription
VertVertical imagery
E__East panorama imagery
N__North panorama imagery
S__South panorama imagery
W__West panorama imagery
within_allowed_areaInternal use only.
coverage_statusInternal use only. Not applicable for requests made with ll=LAT,LON parameter
area_typeInternal use only. Not applicable for requests made with ll=LAT,LON parameter

Example

The following example is a for a US location:

Request

Code Block
languagejs
themeEclipse
http://us0.nearmap.com/maps/?ll=4030.729991273363957766705,-7397.84412774441599980008&z=18&nmq=INFO&versionnmf=2
json&nmfz=json18&httpauthversion=false2&apikey=YOUR_API_KEY
Response: 

{	
  ZjNhZDkyNDUtZjIyMS00NTkwLWJlMzYtZDJlNWUyNDkxNjE4

Response

Code Block
languagejs
themeEclipse
linenumberstrue
{
	"layers": 
    {

		"E___": [
			"/Date(1493251200000)/"
  "Vert		],
		"N___": [
			"/Date(1493251200000)/"
		],
		"S___": [
			"/Date(1493251200000)/"
		],
		"Vert": [
			"/Date(14107392000001416873600000)/",
			"/Date(1420243200000)/",
       			"/Date(1437350400000)/",
			"/Date(14287968000001447977600000)/",
        			"/Date(14414976000001453593600000)/",
        			"/Date(14458176000001477008000000)/",
        			"/Date(14607648000001485648000000)/",
        			"/Date(14764896000001493251200000)/"
      		],
		"W___": [
			"/Date(1493251200000)/"
		]
	},
    	"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   January 1 1970 UTC.