The Coverage API returns survey metadata for a given location, letting you discover what Nearmap imagery is available, when it was captured, and at what resolution. It is also used to retrieve survey boundaries as spatial data, and to look up photo-level timestamps within a survey.
The Coverage API is most commonly used as a companion to the Tile API; query coverage to discover available surveys and obtain surveyId values, then pass those to the Tile API to request imagery for a specific capture.
Choosing the right endpoint
| Goal | Endpoint |
|---|---|
| Check if coverage exists at an address or point | /coverage/v2/point/ |
| Get available surveys for a map region specified by a polygon | /coverage/v2/poly/ |
| Same as polygon, but with a large geometry | POST /coverage/v2/aoi |
| Get surveys for a specific tile coordinate | /coverage/v2/coord/ |
| Download survey polygons to cross-reference your data | /coverage/v2/surveyresources/boundaries.{fileFormat} |
| Visualize total Nearmap coverage on a map | /coverage/v2/aggregate/boundaries.{fileFormat} |
| Get photo timestamps for imagery at a point | /coverage/v2/point/{x},{y}/timestamp.{format} |
Endpoints
The Coverage API is organized into three groups: Coverage (survey metadata by location), Coverage Boundaries (survey polygons as GeoJSON or GeoPackage), and Photo Timestamp (per-tile photo timing within a survey).
Coverage
These endpoints return survey metadata - capture dates, resolution, resource types, and location, for a specified area of interest.
By point
GET https://api.nearmap.com/coverage/v2/point/{coord}Returns surveys available at a longitude/latitude coordinate. Use this to check whether Nearmap coverage exists at a geocoded address or a specific location.
By polygon
GET https://api.nearmap.com/coverage/v2/poly/{polygon}Returns surveys that intersect a polygon area of interest. Suitable for interactive web applications where the user is viewing a map region.
By area of interest
POST https://api.nearmap.com/coverage/v2/aoiEquivalent to the polygon endpoint, but accepts the geometry in the request body. Use this when your polygon is too large for a query string parameter.
By tile coordinate
GET https://api.nearmap.com/coverage/v2/coord/{z}/{x}/{y}Returns surveys for a Web Mercator tile coordinate (z/x/y). Equivalent to querying /poly with the extent of that tile. Provided for legacy compatibility — use /poly or /point for new integrations.
Query parameters
Pagination
| Parameter | Description |
|---|---|
limit | Maximum number of surveys to return. Defaults to 20. |
offset | Zero-based index of the first survey to return. Used for paginating through results. |
Date filtering
| Parameter | Format | Description |
|---|---|---|
since | YYYY-MM-DD | Return only surveys captured on or after this date. |
until | YYYY-MM-DD | Return only surveys captured on or before this date. |
Tag filtering
Tags are metadata attributes on surveys captured after notable events. Use include and exclude to filter on them.
| Parameter | Description |
|---|---|
include | Only include surveys that match this tag type or type:name pair. |
exclude | Exclude surveys that match this tag type or type:name pair. |
Tags follow the format type:name. The disaster type is the most commonly used. Supported tag names include: hurricane, cyclone, typhoon, tornado, tsunami, flood, blizzard, earthquake, hail, avalanche, landslide, fire, volcano, drought, wind, storm, inundation, meteor, and misc.
Example — return surveys tagged as hurricane disasters:
GET https://api.nearmap.com/coverage/v2/point/-78.294,33.922?apikey={YOUR_API_KEY}&include=disaster:hurricane&fields=id,captureDate,tagsField selection
| Parameter | Description |
|---|---|
fields | Comma-separated list of response fields to include. Reduces response size when you only need specific metadata. |
Output format (boundaries endpoints only)
boundaries endpoints only)| Parameter | Description |
|---|---|
fileFormat | geojson or gpkg (GeoPackage). Specified as a path parameter in the URL. |
Response fields
Coverage responses return a surveys array, ordered from most recent to least recent, with the following fields per survey:
| Field | Description |
|---|---|
id | Unique survey identifier. Use this as the surveyId in the Tile API. |
captureDate | The survey date, expressed in the local time zone of the survey location. |
firstPhotoTime | UTC timestamp of the first photo taken in the survey. |
lastPhotoTime | UTC timestamp of the last photo taken in the survey. |
onlineTime | UTC timestamp when the survey became publicly available. |
pixelSize | Ground Sample Distance (GSD) in meters — the spatial resolution of the imagery. |
timezone | Universal time zone abbreviation for the survey location (e.g. AEST, EST). |
utcOffset | Offset in seconds between UTC and the survey's local time zone. |
location | Object containing country, region, and state for the survey. |
resources.tiles | Array of tile resources for the survey, each with an id, scale (max zoom level), and type (content type). |
limit | The limit applied to this response, as specified in the request. |
offset | The offset applied to this response, as specified in the request. |
total | Total number of surveys available for the query (before pagination). |
The resources.tiles[].type field uses the same content type values as the Tile API: Vert, North, South, East, West.
The resources.tiles[].scale value is the maximum zoom level for that tile set. Tile requests beyond this zoom level require client-side upscaling.
Examples
Coverage for a point (Australia)
GET https://api.nearmap.com/coverage/v2/point/138.59707796614592,-34.91729448760797?apikey={YOUR_API_KEY}&limit=2Coverage for a tile coordinate
GET https://api.nearmap.com/coverage/v2/coord/16/57999/39561?apikey={YOUR_API_KEY}&limit=2Survey boundaries for a polygon
GET https://api.nearmap.com/coverage/v2/surveyresources/boundaries.geojson?polygon=138.597,-34.917,138.617,-34.917,138.617,-34.927,138.597,-34.927,138.597,-34.917&apikey={YOUR_API_KEY}Aggregated coverage boundaries (entire Nearmap footprint)
GET https://api.nearmap.com/coverage/v2/aggregate/boundaries.geojson?apikey={YOUR_API_KEY}Photo timestamp for a point
GET https://api.nearmap.com/coverage/v2/point/151.207,-33.865/timestamp.json?until=2024-02-25&apikey={YOUR_API_KEY}Using Coverage with the Tile API
The Coverage and Tile APIs are designed to be used together. A typical workflow:
- Call a Coverage endpoint with your area of interest to retrieve available surveys.
- Inspect the response to select the survey you want (by date, resolution, or tag).
- Use the survey's
idas thesurveyIdin the Tile API's survey-specific endpoint to request tiles for that exact capture.
This pattern is essential when you need to pin your application to a specific survey. For example, to show imagery from before and after an event.
Related
- Coverage Metadata Fields - full reference for all response fields
- Filter Surveys - date and tag filtering in detail
- Requesting Resource Types - how to request specific content types
- Endpoint Examples - full request/response examples
- Tile API - retrieve imagery using survey IDs from Coverage
- Authentication - API key setup
- Troubleshooting the Coverage API