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:
- Retrieve Metadata for a Given Polygon
- Retrieve Metadata for a Given Point
- Retrieve Metadata for a Given Tile Coordinate
There are two ways you can retrieve coverage boundaries:
- Retrieve Content Boundaries for a Given Polygon
- Retrieve Aggregated Coverage Boundaries
This API also follows our new standard for Nearmap APIs, as explained in New Standard for Nearmap APIs.
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).
API | Use Cases | Input | Output |
|---|
/coverage/v2/poly/ | Use this API for querying dates and other attributes for a small geographic area. For example, in interactive web applications. | Area of Interest as a polygon | Metadata for survey resources that the user can access via the API, taking into account area and content types. |
/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. | Area of Interest as a point | Metadata for survey resources that the user can access via the API, taking into account area and content types. |
/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. | Area of Interest as a Web Mercator tile | Metadata for survey resources that the user can access via the API, taking into account area and content types. |
/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. | Area of Interest as a polygon | Metadata and the survey polygons that the user can access via the API, taking into account area and content types. |
/coverage/v2/aggregate/boundaries.geojson | Use this API for visualisation of aggregated Nearmap coverage. For example, to create an interactive map that shows where there is Nearmap coverage. | No way to specify the area | Aggregated coverage polygons per content type (Vertical, Oblique, 3D), regardless of the user access level. |
Authentication
Access to Nearmap imagery is only available to authenticated subscribers. Tiles may be requested from Nearmap servers with an API Key. Refer to the API Key Authentication 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 OpenLayers, Leaflet, Google 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.
Filter Surveys
By adding a filter, you can restrict the surveys which are considered for rendering. You can filter by date or by tag or by a combination of both, for a more powerful restriction.
Filter by date
Use the Since and Until parameters to restrict surveys by a date range.
Filter by tag
Use the Include and Exclude parameters to filter on tags. Tags are additional metadata attributes available for a s mall number of surveys that were flown after select events.
While each tag must have a type and a name, you can filter on any or both type and name. For example, post catastrophe captures are tagged with type “disaster” with the name corresponding to the nature of the event, e.g. “hurricane”, “tornado”, etc.
The include and exclude parameters only filter on tags, not on any other metadata.
The example below includes all surveys that have a disaster type of hurricane. NOTE that if the value for disaster tag is empty it is not tagged at all and will not return "include=disaster".
GET 'https://api.nearmap.com/coverage/v2/point/-78.2942417882549648,33.9229164227871252?apikey=APIKEY&include=disaster&fields=id,captureDate,tags'
{
"limit": 20,
"offset": 0,
"surveys": [
{
"captureDate": "2019-09-06",
"id": "c64e4b46-d1b0-11e9-8bdd-07792c721697",
"tags": {
"disaster": "hurricane"
}
}
],
"total": 1
}
Current tags of Type = disaster
Note that this list is a guideline only.
| Tag | notes |
hurricane |
|
cyclone |
|
typhoon |
|
tornado |
|
tsunami |
|
flood |
|
blizzard |
|
earthquake |
|
hail |
|
flood |
|
avalanche |
|
landslide | Landslide (including land deformation) |
fire | Wildfire (NA) or Bushfire (AU) |
volcano |
|
drought |
|
meteor | Asteroid impact (any material impacting from space) |
misc | Property damage for other reasons
(Not caused by weather/cosmic events) |
| inundation |
|
| wind |
|
| storm |
|
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:
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
Required | Name | API / query | Type | Description |
|---|
✔️ | polygon | API | string | 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 |
✔️ | apikey | query | string | Your API key. See API Key Authentication for more information. |
❌ | since | query | string | 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 | query | string | 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. |
❌ | limit | query | integer | 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. |
❌ | offset | query | integer | 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 | query | string | 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 | query | string | 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 |
❌ | overlap | query | string | Controls whether surveys that partially cover the requested polygon are returned. The possible values are as follows: ◾️ all (default) - all surveys that partially or fully overlap with requested polygon are returned ◾️ full - only the surveys that fully cover the requested polygon are returned |
❌ | include | query | string | Filters surveys so that only those tagged with the type and name specified are returned. Tags are a type:name combination. You can also filter on type and name separately. By comma separating you can include multiple tags, types and/or names. ◾️ type:name, e.g. disaster:hurricane ◾️ type, e.g. disaster ◾️ name, e.g. hurricane |
❌ | exclude | query | string | Filters surveys so that only those not tagged with the type and name specified are returned. Tags are a type:name combination. You can also filter on type and name separately. By comma separating you can include multiple tags, types and/or names. ◾️ type:name, e.g. disaster:hurricane ◾️ type, e.g. disaster ◾️ name, e.g. hurricane |
Examples
In this example we request surveys for a given polygon, limiting the response to two surveys.
Australia
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:
Code | Description |
|---|
| 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. |
| 403 | Forbidden. Returned when not allowed to access the requested location. |
| 404 | Not Found. Returned when cannot find any surveys for the requested condition. |
| 429 | Too Many Requests. Returned when the rate limit is reached. |
| 5XX | Server 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
Required | Name | API / query | Type | Description |
|---|
✔️ | point | API | string | 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. |
✔️ | apikey | query | string | Your API key. See API Key Authentication for more information. |
❌ | since | query | string | 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. |
❌ | until | query | string | 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. |
❌ | limit | query | integer | 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. |
❌ | offset | query | integer | 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 | query | string | 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 | query | string | 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 |
❌ | include | query | string | Filters surveys so that only those tagged with the type and name specified are returned. Tags are a type:name combination. You can also filter on type and name separately. By comma separating you can include multiple tags, types and/or names. ◾️ type:name, e.g. disaster:hurricane ◾️ type, e.g. disaster ◾️ name, e.g. hurricane |
❌ | exclude | query | string | Filters surveys so that only those not tagged with the type and name specified are returned. Tags are a type:name combination. You can also filter on type and name separately. By comma separating you can include multiple tags, types and/or names. ◾️ type:name, e.g. disaster:hurricane ◾️ type, e.g. disaster ◾️ name, e.g. hurricane |
Example
In this example we retrieve surveys for a given LONG,LAT point, limiting the response to two surveys for a location in Australia.
NOTE: For a location other than in Australia, for example in the US, substitute the LONG LAT values. E.g. Request for Texas State Capitol Building:
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 Tile 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
Required | Name | API / query | Type | Description |
|---|
✔️ | z | API | integer | The zoom level. The highest resolution is typically 21. Uses the Google Maps Tile Coordinates. |
✔️ | x | API | integer | The X tile coordinate for which the surveys are retrieved (column). Uses the Google Maps Tile Coordinates. |
✔️ | y | API | integer | The Y tile coordinate for which the surveys are retrieved (row). Uses the Uses the Google Maps Tile Coordinates. |
✔️ | apikey | query | string | Your API key. See API Key Authentication for more information. |
❌ | since | query | string | 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. |
❌ | until | query | string | 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. |
❌ | limit | query | integer | 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. |
❌ | offset | query | integer | 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 | query | string | 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 | query | string | 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 |
❌ | include | query | string | Filters surveys so that only those tagged with the type and name specified are returned. Tags are a type:name combination. You can also filter on type and name separately. By comma separating you can include multiple tags, types and/or names. ◾️ type:name, e.g. disaster:hurricane ◾️ type, e.g. disaster ◾️ name, e.g. hurricane |
❌ | exclude | query | string | Filters surveys so that only those not tagged with the type and name specified are returned. Tags are a type:name combination. You can also filter on type and name separately. By comma separating you can include multiple tags, types and/or names. ◾️ type:name, e.g. disaster:hurricane ◾️ type, e.g. disaster ◾️ name, e.g. hurricane |
Example
In this example we retrieve surveys for a given tile x/y/z coordinate , limiting the response to two surveys for a location in Australia:
NOTE: For a location other than in Australia, for example in the US, substitute the x/y/z coordinates.
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.
The 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 for a location in Australia.
NOTE: For a location other than in Australia, for example in the US, substitute the LONG LAT values.
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 for a location in Asutralia.
NOTE: For a location other than in Australia, for example in the US, substitute the LONG LAT values.
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
Required | Name | API / query | Type | Description |
|---|
✔️ | fileFormat | API | string | The response file format. The supported file format is geojson. |
✔️ | polygon | query | string | 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 |
✔️ | apikey | query | string | Your API key. See API Key Authentication for more information. |
❌ | since | query | string | 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 | query | string | 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. |
❌ | limit | query | integer | 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. |
❌ | offset | query | integer | 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. |
❌ | resources | query | string | 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. |
❌ | overlap | query | string | Controls whether surveys that partially cover the requested polygon are returned. The possible values are as follows: ◾️ all (default) - all surveys that partially or fully overlap with requested polygon are returned ◾️ full - only the surveys that fully cover the requested polygon are returned |
❌ | include | query | string | Filters surveys so that only those tagged with the type and name specified are returned. Tags are a type:name combination. You can also filter on type and name separately. By comma separating you can include multiple tags, types and/or names. ◾️ type:name, e.g. disaster:hurricane ◾️ type, e.g. disaster ◾️ name, e.g. hurricane |
❌ | exclude | query | string | Filters surveys so that only those not tagged with the type and name specified are returned. Tags are a type:name combination. You can also filter on type and name separately. By comma separating you can include multiple tags, types and/or names. ◾️ type:name, e.g. disaster:hurricane ◾️ type, e.g. disaster ◾️ name, e.g. hurricane |
Example
The following example is for Australian content.
NOTE: For a location other than in Australia, for example in the US, substitute the LONG LAT values.
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 (partial)
{
"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:
Code | Description |
|---|
| 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.
NOTE: Currently aggregate boundaries are updated weekly. You may therefore see a delay between content available on MapBrowser and the aggregate dataset. We are working on automating this part of the process to ensure that the aggregate boundaries are always up to date.
API URL Format
https://api.nearmap.com/coverage/v2/aggregate/boundaries.{fileFormat}?apikey={YOUR_API_KEY}
Read more about the API URL format.
Parameters
Required | Name | API / query | Type | Description |
|---|
✔️ | fileFormat | API | string | The response file format. The supported file format is geojson. |
❌
| types | query | string | Comma-separated list of categories to include in the response. The types possible values are: If not specified, then all categories are returned. |
✔️ | apikey | query | string | Your 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 (partial)
{
"type":"FeatureCollection",
"features":[
{
"type":"Feature",
"geometry":{
"type":"MultiPolygon",
"coordinates":[
[
[
[
-73.39778063733444,
40.597624678639875
],
[
-73.39692479743157,
40.597064516856086
],
[
-73.39889835574029,
40.59471911929547
]
]
]
]
},
"properties":{
"type":"3D"
}
}
]
}
Responses
The following table describes the possible HTTP response status codes to the URL request and the surveys response fields:
|
Code | Description |
|---|
| 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 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.
