Page tree
Skip to end of metadata
Go to start of metadata

Introduction

Use Nearmap Coverage API to get a list of surveys by date for a location, which you can then use with Nearmap's Tile API

There are three ways you can retrieve coverage (surveys) metadata:

There are two ways you can retrieve coverage boundaries:

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

This guide includes the following sections:

Which Coverage API call is right for me?

We have multiple ways to query Nearmap coverage information. This section explains which API is most appropriate for which use cases.

You first need to establish whether you need the coverage polygons or just the metadata (e.g. resolution and capture date). 

APIUse Cases
/coverage/v2/poly/Use this API for querying dates and other attributes for a small geographic area. For example, in interactive web applications.
/coverage/v2/point/Use this API for querying dates and other attributes for a point. For example, checking if there is Nearmap coverage at a geocoded address.
/coverage/v2/coord/Use this API for querying dates and other attributes for a Google x/y/z tile coordinate. Provided for legacy compatibility reasons. Equivalent to the /`poly` request with the extent of the particular tile.
/coverage/v2/surveyresources/boundaries.geojson Use this API for downloading coverage polygons to cross reference against your own spatial database. For example, to check which of your assets are contained within a particular survey.
/coverage/v2/aggregate/boundaries.geojsonUse this API for visualisation of aggregated Nearmap coverage. For example, to create an interactive map that shows where there is Nearmap coverage.


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.


URL Requests

Nearmap's Coverage 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 OpenLayersLeafletGoogle Maps JavaScript API, etc.


Rate Limit

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 Metadata 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 Metadata for a Given Polygon

This API retrieves coverage (surveys) for a given polygon. 

API URL Format

https://api.nearmap.com/coverage/v2/poly/{polygon}?apikey={YOUR_API_KEY}

Read more about the API URL format.

Parameters

RequiredNameAPI / queryTypeDescription

polygon

APIstring

The polygon for which the surveys are retrieved. The polygon is depicted by a set of LONG,LAT points, where the first and the 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

 Notes:

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

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

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.

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.

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.

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.

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.

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

Example

In this example we request surveys for a given polygon, limiting the response to two surveys:

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&limit=2

Response:
{
	"surveys": [
		{
			"captureDate": "2018-10-29",
			"firstPhotoTime": "2018-10-29T00:33:23Z",
			"id": "100-353f704a-dcaa-11e8-b148-c715c343620e",
			"lastPhotoTime": "2018-10-29T04:45:23Z",
			"location": {
				"country": "AU",
				"region": "Adelaide",
				"state": "SA"
			},
			"onlineTime": "2018-10-31T01:13:43Z",
			"pixelSize": 0.069,
			"resources": {
				"tiles": [
					{
						"id": "3540420e-dcaa-11e8-b14b-5b94392a0156",
						"scale": 21,
						"type": "Vert"
					},
				]
			},
			"timezone": "ACDT",
			"utcOffset": 37800
		},
		{
			"captureDate": "2018-08-22",
			"firstPhotoTime": "2018-08-22T00:17:33Z",
			"id": "100-4c51ffe8-ab52-11e8-9b7a-b3f8ca0bcb81",
			"lastPhotoTime": "2018-08-22T02:51:17Z",
			"location": {
				"country": "AU",
				"region": "Adelaide",
				"state": "SA"
			},
			"onlineTime": "2018-08-29T06:10:59Z",
			"pixelSize": 0.069,
			"resources": {
				"tiles": [
					{
						"id": "4c55ec3e-ab52-11e8-9b7d-437267690635",
						"scale": 21,
						"type": "Vert"
					}
				]
			},
			"timezone": "ACST",
			"utcOffset": 34200
		}
	],
	"limit": 2,
	"offset": 0,
	"total": 66
}

Responses

The following table describes the possible HTTP response status codes to the URL request and 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 Metadata for a Given Point

This API retrieves coverage (surveys) for a given LONG,LAT point. 

API URL Format

https://api.nearmap.com/coverage/v2/point/{point}?apikey={YOUR_API_KEY}

Read more about the API URL format.

Parameters

RequiredNameAPI / queryTypeDescription

pointAPIstring

The point for which the surveys are retrieved. The point is the longitude and latitude 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.

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

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.

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.

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.

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.

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.

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

Example

In this example we retrieve surveys for a given LONG,LAT point, limiting the response to two surveys:

Request:
https://api.nearmap.com/coverage/v2/point/138.59707796614592,-34.91729448760797?apikey=Yzc2MjEzMWUtY2Q4YS00NTM2LTgyMDgtMDljZjI2YTdhMTMz&limit=2

Response:
{
	"surveys": [
		{
			"captureDate": "2018-10-29",
			"firstPhotoTime": "2018-10-29T00:33:23Z",
			"id": "100-353f704a-dcaa-11e8-b148-c715c343620e",
			"lastPhotoTime": "2018-10-29T04:45:23Z",
			"location": {
				"country": "AU",
				"region": "Adelaide",
				"state": "SA"
			},
			"onlineTime": "2018-10-31T01:13:43Z",
			"pixelSize": 0.069,
			"resources": {
				"tiles": [
					{
						"id": "3540420e-dcaa-11e8-b14b-5b94392a0156",
						"scale": 21,
						"type": "Vert"
					},
				]
			},
			"timezone": "ACDT",
			"utcOffset": 37800
		},
		{
			"captureDate": "2018-08-22",
			"firstPhotoTime": "2018-08-22T00:17:33Z",
			"id": "100-4c51ffe8-ab52-11e8-9b7a-b3f8ca0bcb81",
			"lastPhotoTime": "2018-08-22T02:51:17Z",
			"location": {
				"country": "AU",
				"region": "Adelaide",
				"state": "SA"
			},
			"onlineTime": "2018-08-29T06:10:59Z",
			"pixelSize": 0.069,
			"resources": {
				"tiles": [
					{
						"id": "4c55ec3e-ab52-11e8-9b7d-437267690635",
						"scale": 21,
						"type": "Vert"
					}
				]
			},
			"timezone": "ACST",
			"utcOffset": 34200
		}
	],
	"limit": 2,
	"offset": 0,
	"total": 66
}

Responses

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 Metadata for a Given Tile Coordinate

This API retrieves coverage (surveys) for a given tile (x/y/z) coordinate, using the Google Maps Tile Coordinates. 

API URL Format

https://api.nearmap.com/coverage/v2/coord/{z}/{x}/{y}?apikey={YOUR_API_KEY}

Read more about the API URL format.

Parameters

RequiredNameAPI / queryTypeDescription

zAPIinteger

The zoom level. The highest resolution is typically 21. Uses the Google Maps Tile Coordinates.

xAPIintegerThe X tile coordinate for which the surveys are retrieved (column). Uses the Google Maps Tile Coordinates.

yAPIintegerThe Y tile coordinate for which the surveys are retrieved (row). Uses the Uses the Google Maps Tile Coordinates.

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

since

querystring

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

There 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.

untilquerystring

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

There 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.

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.

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.

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.

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

Example

In this example we retrieve surveys for a given tile x/y/z coordinatelimiting the response to two surveys:

Request:
https://api.nearmap.com/coverage/v2/coord/16/57999/39561?apikey=Yzc2MjEzMWUtY2Q4YS00NTM2LTgyMDgtMDljZjI2YTdhMTMz&limit=2

Response:
{
	"surveys": [
		{
			"captureDate": "2018-10-29",
			"firstPhotoTime": "2018-10-29T00:33:23Z",
			"id": "100-353f704a-dcaa-11e8-b148-c715c343620e",
			"lastPhotoTime": "2018-10-29T04:45:23Z",
			"location": {
				"country": "AU",
				"region": "Adelaide",
				"state": "SA"
			},
			"onlineTime": "2018-10-31T01:13:43Z",
			"pixelSize": 0.069,
			"resources": {
				"tiles": [
					{
						"id": "3540420e-dcaa-11e8-b14b-5b94392a0156",
						"scale": 21,
						"type": "Vert"
					},
				]
			},
			"timezone": "ACDT",
			"utcOffset": 37800
		},
		{
			"captureDate": "2018-08-22",
			"firstPhotoTime": "2018-08-22T00:17:33Z",
			"id": "100-4c51ffe8-ab52-11e8-9b7a-b3f8ca0bcb81",
			"lastPhotoTime": "2018-08-22T02:51:17Z",
			"location": {
				"country": "AU",
				"region": "Adelaide",
				"state": "SA"
			},
			"onlineTime": "2018-08-29T06:10:59Z",
			"pixelSize": 0.069,
			"resources": {
				"tiles": [
					{
						"id": "4c55ec3e-ab52-11e8-9b7d-437267690635",
						"scale": 21,
						"type": "Vert"
					}
				]
			},
			"timezone": "ACST",
			"utcOffset": 34200
		}
	],
	"limit": 2,
	"offset": 0,
	"total": 66
}

Responses

The possible HTTP response status codes to the URL request 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

The since and until parameters specify the dates for which to retrieve the surveys requested in the Coverage API. 

In this example we retrieve surveys for a given polygon, since the 1st of Feb 2018 until 6 months ago:


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&since=2018-02-01&until=6M

Response:
{
	"surveys": [
		{
			"captureDate": "2018-04-19",
			"firstPhotoTime": "2018-04-19T00:10:27Z",
			"id": "100-510ace40-49b2-11e8-bb72-ff76fb415264",
			"lastPhotoTime": "2018-04-19T03:35:45Z",
			"location": {
				"country": "AU",
				"region": "Adelaide",
				"state": "SA"
			},
			"onlineTime": "2018-04-27T00:31:24Z",
			"pixelSize": 0.066,
			"resources": {
				"tiles": [
					{
						"id": "510ce2e8-49b2-11e8-bb75-cf2f2247d124",
						"scale": 21,
						"type": "Vert"
					},
					{
						"id": "51100db0-49b2-11e8-bb79-170577ffc6a6",
						"scale": 20,
						"type": "East"
					},
					{
						"id": "510f5294-49b2-11e8-bb78-ffe46b70e235",
						"scale": 21,
						"type": "South"
					},
					{
						"id": "510e8e54-49b2-11e8-bb77-131ff6e28c7d",
						"scale": 21,
						"type": "North"
					},
					{
						"id": "5110ee88-49b2-11e8-bb7a-bf00b6fd0bbd",
						"scale": 20,
						"type": "West"
					}
				]
			},
			"timezone": "ACST",
			"utcOffset": 34200
		},
		{
			"captureDate": "2018-02-26",
			"firstPhotoTime": "2018-02-26T01:26:09Z",
			"id": "100-2d147328-2028-11e8-896f-57ffd8ddb571",
			"lastPhotoTime": "2018-02-26T05:06:56Z",
			"location": {
				"country": "AU",
				"region": "Adelaide",
				"state": "SA"
			},
			"onlineTime": "2018-03-05T03:49:16Z",
			"pixelSize": 0.066,
			"resources": {
				"tiles": [
					{
						"id": "2d15d33a-2028-11e8-8972-ab630c07c403",
						"scale": 21,
						"type": "Vert"
					}
				]
			},
			"timezone": "ACDT",
			"utcOffset": 37800
		}
	],	
	"limit": 20,
	"offset": 0,
	"total": 2
}

Using the fields Parameter

The fields parameter specifies which fields will appear in the response when retrieving surveys using the Coverage API. Note that the id field is always returned, even if not specified.

In this example we retrieve surveys for a given polygon, requesting only the captureDate and firstPhotoTime fields, and limiting the response to 10 surveys:

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&fields=id,captureDate&limit=10

Response:
{
	"surveys": [
		{
			"captureDate": "2018-10-29",
			"firstPhotoTime": "2018-10-29T00:33:23Z",
			"id": "100-353f704a-dcaa-11e8-b148-c715c343620e"
		},
		{
			"captureDate": "2018-08-22",
			"firstPhotoTime": "2018-08-22T00:17:33Z",
			"id": "100-4c51ffe8-ab52-11e8-9b7a-b3f8ca0bcb81"
		},
		{
			"captureDate": "2018-04-19",
			"firstPhotoTime": "2018-04-19T00:10:27Z",
			"id": "100-510ace40-49b2-11e8-bb72-ff76fb415264"
		},
		{
			"captureDate": "2018-02-26",
			"firstPhotoTime": "2018-02-26T01:26:09Z",
			"id": "100-2d147328-2028-11e8-896f-57ffd8ddb571"
		},
		{
			"captureDate": "2018-01-16",
			"firstPhotoTime": "2018-01-15T22:36:22Z",
			"id": "100-5b9060a6-04a1-11e8-a51e-d3d4da5bcad9"
		},
		{
			"captureDate": "2017-11-21",
			"firstPhotoTime": "2017-11-20T23:33:18Z",
			"id": "100-8d0cfac6-d31a-11e7-b321-b3e831dd2b87"
		},
		{
			"captureDate": "2017-10-02",
			"firstPhotoTime": "2017-10-02T00:32:26Z",
			"id": "100-ecc6b68e-b95f-11e7-92ea-17ff5cb53b71"
		},
		{
			"captureDate": "2017-06-21",
			"firstPhotoTime": "2017-06-21T02:05:25Z",
			"id": "100-bfbe21ea-b95f-11e7-88df-632374f558b6"
		},
		{
			"captureDate": "2017-05-09",
			"firstPhotoTime": "2017-05-09T01:51:17Z",
			"id": "100-ac6c05ee-b95f-11e7-84bb-cb4aa50875c6"
		},
		{
			"captureDate": "2017-03-17",
			"firstPhotoTime": "2017-03-16T23:17:20Z",
			"id": "100-9aa1adfa-b95f-11e7-80d5-6b6ef8ac2f05"
		}
	],
	"limit": 10,
	"offset": 0,
	"total": 66
}


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:

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
}


Retrieve Content Boundaries for a Given Polygon

This API returns all survey resources with boundaries that intersect with the given polygon specified in the path. Each feature in the FeatureCollection represents a content type for a survey. This means that a survey with full panorama coverage will have 5 records - Vertical, North, West, East, South.

If your subscription does not have Panorama access via API, you will not be able to see the panorama entries. Only surveys within your subscription area are returned.

API URL Format

https://api.nearmap.com/coverage/v2/surveyresources/boundaries.{fileFormat}?apikey={YOUR_API_KEY}

Read more about the API URL format.

Parameters

RequiredNameAPI / queryTypeDescription

fileFormatAPIstring

The response file format. The supported file format is geojson.

polygon

querystring

The polygon for which the surveys are retrieved. The polygon is depicted by a set of LONG,LAT points, where the first and the 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

 Notes:

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

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

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.

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.

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.

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.

resourcesquerystring

A comma-separated list of resource classes to include in the response. The resource classes are returned in the form of "resourceClass:type" where ":type" is optional and represents all types of a resource class if not present.

The resources possible values are:

  • tiles:Vert
  • tiles:North
  • tiles:East
  • tiles:South
  • tiles:West

If not specified then all resources are returned. 

Example

Request:
https://api.nearmap.com/coverage/v2/surveyresources/boundaries.geojson?polygon=138.59707796614592,-34.91729448760797,138.61703360121672,-34.91729448760797,138.61703360121672,-34.927709974005474,138.59707796614592,-34.927709974005474,138.59707796614592,-34.91729448760797&apikey={YOUR_API_KEY}


If you copy the request into a browser URL, you will see the full response. This is a partial response, including only one survey and only a small part of the MultiPolygon:

Response:
{
	"type": "FeatureCollection",
	"features": [
		{
			"id": "100-c55168f8-b95d-11e7-bd91-43d8499f1906",
			"type": "Feature",
			"geometry": {
				"type": "MultiPolygon",
				"coordinates": [
					[
						[
							[
								138.3820699065405,
								-34.613007476508066
							],
							[
								138.38104070093576,
								-34.65155251700606
							],
							....
							[
								138.3820699065405,
								-34.613007476508066
							]
						]
					]
				]
			},
			"properties": {
				"captureDate": "2009-10-19",
				"country": "AU",
				"firstPhotoTime": "2009-10-18T18:21:46Z",
				"lastPhotoTime": "2009-10-19T22:39:49Z",
				"onlineTime": "2018-02-09T03:32:38Z",
				"pixelSize": 0.08,
				"region": "Adelaide",
				"resourceClass": "tiles",
				"scale": 21,
				"state": "SA",
				"surveyID": "c54f488e-b95d-11e7-bd8e-5f787b2dc397",
				"timezone": "ACDT",
				"type": "Vert",
				"utcOffset": 37800
			}
		},
	],
	"offset": 0,
	"total": 237
}

Country Boundaries

This section gives you the requests for the country boundaries. For each country click on the link and then insert your own API key instead of {YOUR_API_KEY}.

Request for United States Boundaries

https://api.nearmap.com/coverage/v2/surveyresources/boundaries.geojson?&apikey={YOUR_API_KEY}&polygon={US_POLYGON_STRING}&limit=1000&resources=tiles:Vert


Request for Canada Boundaries

https://api.nearmap.com/coverage/v2/surveyresources/boundaries.geojson?&apikey={YOUR_API_KEY}&polygon={CANADA_POLYGON_STRING}&limit=1000&resources=tiles:Vert


Request for Australia Boundaries

https://api.nearmap.com/coverage/v2/surveyresources/boundaries.geojson?&apikey={YOUR_API_KEY}&polygon={AU_POLYGON_STRING}&limit=1000&resources=tiles:Vert


Request for New Zealand Boundaries

https://api.nearmap.com/coverage/v2/surveyresources/boundaries.geojson?&apikey={YOUR_API_KEY}&polygon={NZ_POLYGON_STRING}&limit=1000&resources=tiles:Vert


Retrieved Coverage Fields

Some of the retrieved coverage fields are the same as in the rest of the Coverage API, as detailed here. In addition you receive the multi-polygon that represents the survey boundaries for all surveys within your specified area.

Responses

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

CodeDescription
200

OK. Survey resources with boundaries matching criteria. 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 an input parameter is wrong, or if the polygon is invalid.


Retrieve Aggregated Coverage Boundaries

This API returns the aggregate boundaries per content type for all areas where there is coverage. The survey resources are returned in GeoJSON format. Coverage information for all of Nearmap content is returned, even in the areas that are not included in your subscription.

API URL Format

https://api.nearmap.com/coverage/v2/aggregate/boundaries.{fileFormat}?apikey={YOUR_API_KEY}

Read more about the API URL format.

Parameters

RequiredNameAPI / queryTypeDescription

fileFormatAPIstringThe response file format. The supported file format is geojson.

types

querystring

Comma-separated list of categories to include in the response.

The types possible values are:

  • Vertical
  • Oblique
  • 3D

If not specified, then all categories are returned.

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

Example

Request:
https://api.nearmap.com/coverage/v2/aggregate/boundaries.geojson?apikey=Yzc2MjEzMWUtY2Q4YS00NTM2LTgyMDgtMDljZjI2YTdhMTMz


If you copy the request into a browser URL, you will see the full response. This is a partial response, including only a small part of the MultiPolygon:

Response:

Responses

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

CodeDescription
200

OK. Survey resources with boundaries matching criteria. 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 that an input parameter is wrong.


Troubleshooting

Not Authorized to Access Area

If you receive the following error:

{"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:

    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:

    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:

{"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:

{"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.


  • No labels