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):

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

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. 

Retrieve Coverage 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, when the last point and the first point 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: the API returns all surveys partially intersecting the requested polygon.

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

CodeDescription
200

OK. Surveys in JSON format as shown in the example above. 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

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

pointAPIstringThe point for which the surveys are retrieved. The point is the latitude and longitude of the location on which to center the image, in the format LONG,LAT. For example, -122.008946,37.334849.

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.


Retrieve Coverage 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


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
}
  • No labels