Page tree

Versions Compared

Key

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

...

This API also follows our new standard for Nearmap APIs, as explained in Tile API.

This guide includes the following sections:

Table of Contents
maxLevel1
excludeIntroduction

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.

...

Nearmap's Coverage API has a rate limit, meaning that there is a restriction on the number of requests that can be made against an endpoint. 

Retrieved Coverage Fields

The retrieved coverage is returned as surveys in a JSON format, from most recent to least recent.

The surveys JSON includes the following fields:

  • captureDate - the survey date in the location of the survey (see Survey Date and Photo Time)
  • firstPhotoTime - the date and time in UTC of the first photo taken in the survey
  • id - the survey ID
  • lastPhotoTime - the date and time in UTC of the last photo taken in the survey
  • location - the location of the survey, includes country, region, and state. The region is usually a city or a locale, comprised of a number of surveys.
  • onlineTime - the time in UTC the survey became available online
  • pixelSize - the Ground Sample Distance in meters
  • resources - the resources available for the survey, which are the tiles. The tile set uses the Google Maps Tile Coordinates.
    • tiles -
      • id - the ID of the tile set
      • scale - the maximum zoom level for the tile set
      • type - the resource type of the tiles. The available values are:
        • Vert - for vertical imagery
        • North - for North panorama imagery
        • South - for South panorama imagery
        • East - for East panorama imagery
        • West - for West panorama imagery
  • timezone - the universal timezone abbreviation of the location of the survey
  • utcOffset- the difference in minutes between UTC and the local timezone
  • limit - the limit of the total number of surveys returned, as specified in the request
  • offset - the offset of the first survey to be displayed, as specified in the request
  • total - the total number of surveys available for this request

Retrieve Coverage for a Given Polygon

...

RequiredNameAPI / queryTypeDescription

Awesome Icon
color#001E60
iconfa-check-square-o

polygon

APIstring

The polygon for which the surveys are retrieved. The polygon is depicted by a set of LONG,LAT points, when where the last point first and the first point last points must be the same.

For example:

138.59707796614592,-34.91729448760797

138.61703360121672,-34.91729448760797

138.61703360121672,-34.927709974005474

138.59707796614592,-34.927709974005474

138.59707796614592,-34.91729448760797

 Note Notes: the

  • The API returns all surveys partially intersecting the requested polygon.
  • The LONG comes before the LAT

Awesome Icon
color#001E60
iconfa-check-square-o

apikeyquerystringYour API key. See API Key Authentication for more information.

Awesome Icon
color#001E60
iconfa-square-o

since

Anchor
since
since

querystring

The first day from which to retrieve the surveys (inclusive).

The two possible formats are:

  • For a specific date: YYYY-MM-DD, e.g. 2015-10-31 to retrieve surveys since this date.
  • For a relative date: xxY, xxM, or xxD, e.g. 5M to retrieve surveys since 5 months ago.

 The since and until parameters are used to further restrict the surveys that are returned.

Awesome Icon
color#001E60
iconfa-square-o

until

Anchor
until
until

querystring

The last day from which to retrieve the surveys (inclusive).

The two possible formats are:

  • For a specific date: YYYY-MM-DD, e.g. 2015-10-31 to retrieve surveys until this date.
  • For a relative date: xxY, xxM, or xxD, e.g. 5M to retrieve surveys until 5 months ago.

 The since and until parameters are used to further restrict the surveys that are returned.

Awesome Icon
color#001E60
iconfa-square-o

limitqueryinteger

The limit of the total number of surveys returned. The default value is 20. The surveys are returned from the most recent to the least recent survey.

Awesome Icon
color#001E60
iconfa-square-o

offsetqueryinteger

The offset of the first survey to be displayed. With no offset, the first survey to be displayed is the most recent one. If the offset is 3 for example, the first survey to be displayed is the 4th recent one.

Awesome Icon
color#001E60
iconfa-square-o

fields

Anchor
fields
fields

querystring

This is a comma-separated list of field names that will appear in the response.

The id field will always be among the returned fields, even if not specified.

If this parameter is not used in the URL request, then all the fields are returned.

The available values are:

  • captureDate
  • firstPhotoTime
  • id
  • lastPhotoTime
  • location
  • onlineTime
  • pixelSize
  • resources
  • timezone
  • utcOffset

Note: the fields values are case sensitive.

Awesome Icon
color#001E60
iconfa-square-o

sort

Anchor
sort
sort

querystring

The field by which to sort the surveys.

Only one field can be specified.

If this parameter is not used in the URL request, then the surveys are sorted by captureDate in descending order.

To sort in ascending order, pass the field name, e.g sort=lastPhotoTime. This will sort the surveys according to the lastPhotoTime from earliest to latest.

To sort in descending order, pass the field name with the "-" prefix, e.g. sort=-pixelSize. This will sort the surveys according to the pixelSize from the largest to the smallest.

If you sort by location, the following are the precedence rules for comparing location objects:

  • country
  • state
  • region

For example, "NZ, MWT, PalmerstonNorth" will come after "AU, NSW, Williamstown" if sorted in ascending order.

The available values are:

  • captureDate
  • firstPhotoTime
  • id
  • lastPhotoTime
  • location
  • onlineTime
  • pixelSize
  • timezone
  • utcOffset

...

Responses
Anchor
apiResponses
apiResponses

The following table describes the possible HTTP response status codes to the URL request areand the surveys response fields:

CodeDescription
200

OK. Surveys in JSON format as shown in the example above. The survey fields are described in the Retrieved Coverage Fields section.

The surveys are returned from most recent to least recent.

400

Bad Request. Returned when the request is invalid. This means either the format is wrong, or a value is out of range.

401

Unauthorized. Returned when the API key is invalid.

403Forbidden. Returned when not allowed to access the requested location.
404Not Found. Returned when cannot find any surveys for the requested condition.
429Too Many Requests. Returned when the rate limit is reached.
5XXServer Error. Returned when something is wrong in the server side.


Retrieve Coverage for a Given Point

...

RequiredNameAPI / queryTypeDescription

Awesome Icon
color#001E60
iconfa-check-square-o

pointAPIstring

The point for which the surveys are retrieved. The point is the longitude and latitude

and longitude

of the location on which to center the image, in the format LONG,LAT. For example, -122.008946,37.334849.

Note: the LONG comes before the LAT.

Awesome Icon
color#001E60
iconfa-check-square-o

apikeyquerystringYour API key. See API Key Authentication for more information.

Awesome Icon
color#001E60
iconfa-square-o

sincequerystring

The first day from which to retrieve the surveys (inclusive).

The two possible formats are:

  • For a specific date: YYYY-MM-DD, e.g. 2015-10-31 to retrieve surveys since this date.
  • For a relative date: xxY, xxM, or xxD, e.g. 5M to retrieve surveys since 5 months ago.

Awesome Icon
color#001E60
iconfa-square-o

untilquerystring

The last day from which to retrieve the surveys (inclusive).

The two possible formats are:

  • For a specific date: YYYY-MM-DD, e.g. 2015-10-31 to retrieve surveys until this date.
  • For a relative date: xxY, xxM, or xxD, e.g. 5M to retrieve surveys until 5 months ago.

Awesome Icon
color#001E60
iconfa-square-o

limitqueryinteger

The limit of the total number of surveys returned. The default value is 20. The surveys are returned from the most recent to the least recent survey.

Awesome Icon
color#001E60
iconfa-square-o

offsetqueryintegerThe offset of the first survey to be displayed. With no offset, the first survey to be displayed is the most recent one. If the offset is 3 for example, the first survey to be displayed is the 4th recent one.

Awesome Icon
color#001E60
iconfa-square-o

fieldsquerystring

This is a comma-separated list of field names that will appear in the response.

The id field will always be among the returned fields, even if not specified.

If this parameter is not used in the URL request, then all the fields are returned.

The available values are:

  • captureDate
  • firstPhotoTime
  • id
  • lastPhotoTime
  • location
  • onlineTime
  • pixelSize
  • resources
  • timezone
  • utcOffset

Note: the fields values are case sensitive.

Awesome Icon
color#001E60
iconfa-square-o

sortquerystring

The field by which to sort the surveys.

Only one field can be specified.

If this parameter is not used in the URL request, then the surveys are sorted by captureDate in descending order.

To sort in ascending order, pass the field name, e.g sort=lastPhotoTime. This will sort the surveys according to the lastPhotoTime from earliest to latest.

To sort in descending order, pass the field name with the "-" prefix, e.g. sort=-pixelSize. This will sort the surveys according to the pixelSize from the largest to the smallest.

If you sort by location, the following are the precedence rules for comparing location objects:

  • country
  • state
  • region

For example, "NZ, MWT, PalmerstonNorth" will come after "AU, NSW, Williamstown" if sorted in ascending order.

The available values are:

  • captureDate
  • firstPhotoTime
  • id
  • lastPhotoTime
  • location
  • onlineTime
  • pixelSize
  • timezone
  • utcOffset

...

The possible HTTP response status codes to the URL request are the same as the previous API.

The survey fields are described in the Retrieved Coverage Fields section.

Retrieve Coverage for a Given Tile Coordinate

...

The possible HTTP response status codes to the URL request are the are the same as the previous API. 

he survey fields are described in the Retrieved Coverage Fields section.

Additional Examples

Using the since and until Parameters

...

Using the sort Parameter

The sort parameter specifies the field by which to sort the retrieved surveys requested by the Coverage API.

In this example we retrieve surveys for a given polygon, sorting the response fields according to the lastPhotoTime field in an ascending order, and limiting the response to three surveys:

Code Block
languagejs
themeEclipse
Request:
https://api.nearmap.com/coverage/v2/poly/138.59707796614592,-34.91729448760797
,138.61703360121672,-34.91729448760797,138.61703360121672,-34.927709974005474,
138.59707796614592,-34.927709974005474,138.59707796614592,-34.91729448760797
?apikey=Yzc2MjEzMWUtY2Q4YS00NTM2LTgyMDgtMDljZjI2YTdhMTMz&sort=lastPhotoTime&limit=3

Response:
{
	"surveys": [
		{
			"captureDate": "2009-10-19",
			"firstPhotoTime": "2009-10-18T18:21:46Z",
			"id": "100-c54f488e-b95d-11e7-bd8e-5f787b2dc397",
			"lastPhotoTime": "2009-10-19T22:39:49Z",
			"location": {
				"country": "AU",
				"region": "Adelaide",
				"state": "SA"
			},
			"onlineTime": "2018-02-09T03:32:38Z",
			"pixelSize": 0.08,
			"resources": {
				"tiles": [
					{
						"id": "c55168f8-b95d-11e7-bd91-43d8499f1906",
						"scale": 21,
						"type": "Vert"
					}
				]
			},
			"timezone": "ACDT",
			"utcOffset": 37800
		},
		{
			"captureDate": "2009-10-29",
			"firstPhotoTime": "2009-10-28T15:52:19Z",
			"id": "100-0647ec10-b95e-11e7-ac79-4fe499e7d4d3",
			"lastPhotoTime": "2009-10-30T22:09:13Z",
			"location": {
				"country": "AU",
				"region": "Adelaide",
				"state": "SA"
			},
			"onlineTime": "2018-02-09T03:07:21Z",
			"pixelSize": 0.08,
			"resources": {
				"tiles": [
					{
						"id": "064a0180-b95e-11e7-ac7c-2fae4102c9b7",
						"scale": 21,
						"type": "Vert"
					}
				]
			},
			"timezone": "ACDT",
			"utcOffset": 37800
		},
		{
			"captureDate": "2009-12-01",
			"firstPhotoTime": "2009-11-30T16:03:36Z",
			"id": "100-c735b188-b95d-11e7-bdec-8fc52cb7008c",
			"lastPhotoTime": "2009-12-01T23:19:42Z",
			"location": {
				"country": "AU",
				"region": "Adelaide",
				"state": "SA"
			},
			"onlineTime": "2018-02-09T02:47:48Z",
			"pixelSize": 0.08,
			"resources": {
				"tiles": [
					{
						"id": "c737c9a0-b95d-11e7-bdef-1f90b15ebb7e",
						"scale": 21,
						"type": "Vert"
					}
				]
			},
			"timezone": "ACDT",
			"utcOffset": 37800
		}
	],
	"limit": 3,
	"offset": 0,
	"total": 66
}


Troubleshooting

Not Authorized to Access Area

If you receive the following error:

Info
iconfalse
{"error":"You are not authorized to access this area"}

Check whether the coordinates that you used are LONG,LAT points, and not LAT,LONG points. The order is crucial, otherwise you will be requesting surveys for an area that is outside your coverage area, and this error will be returned. 

For example:

  • The latitude and longitude for the Statue of Liberty is 40.688640, -74.043970. In the request we will change the order of the coordinates:

    Code Block
    themeConfluence
    https://api.nearmap.com/coverage/v2/point/-74.043970,40.688640?apikey={YOUR_API_KEY}


  • The latitude and longitude for the Sydney Opera House is -33.858060, 151.214850. In the request we will change the order of the coordinates:

    Code Block
    themeConfluence
    https://api.nearmap.com/coverage/v2/point/151.214850,-33.858060?apikey={YOUR_API_KEY}


This error is also returned when you request coverage for an area you are not authorized to access, for example when your API key can be used only for Australian imagery, and you request coverage for an area in the United States.

It is also possible that you requested coverage for an area that Nearmap doesn't cover.

Invalid Polygon

If you receive the following error:

Info
iconfalse
{"error": "geometry was not a valid sequence of x,y coordinates","code": "INVALID_POLYGON"}

Check whether you have an extra comma or space in your URL request. 

This error is also returned when the polygon is given in the wrong format.

API Key Not Found

If you receive the following error:

Info
iconfalse
{"error": "API key not found"}

Check whether you have are missing any part of the API key, or if you have an extra space in the API key.

This error is also returned when the API key is invalid. Check if the API Key that you are using is "Stale". You can confirm this and renew the API by following the instructions listed here.