This guide describes the DSM and True Ortho API. This product makes DSM and True Ortho content available for rapid access via API.
Overview
The DSM and True Ortho API provides access to a subset of Nearmap 3D content, namely the Digital Surface Model and the True Ortho. Additionally, users of the API can access Nearmap's vertical content. This API is designed to work with smaller areas, such as typical residential and small commercial properties. For such small areas, this API provides low latency access, typically completed in under a second.
Before you start
The DSM and True Ortho API requires a special subscription. Contact your Nearmap Account Manager for more information.
Before you start using your DSM and True Ortho API key, if there are multiple subscriptions on your Nearmap account, you need to ensure that you are allocated the correct license.
Your Nearmap administrator needs to do this for you by following the steps in this article: Manage Subscriptions.
How to use the API
The DSM and True Ortho API uses the new Staticmap API. The new Staticmap API has a path prefix of /staticmap/v2/. The v2 designation is to distinguish it from the existing legacy staticmap end point (Image API).
The sequence of calling the APIs is important and is as follows:
1. Coverage API Call
- This API provides the details on the available coverage for the requested area.
- The area is given bounding box, defined by a point and a distance from the point.
- This is separate from the existing Coverage APIs
- The Coverage call creates a transaction token that should be used to retrieve the image.
API URL Format
https://api.nearmap.com/staticmap/v2/coverage.json?point={x},{y}&radius={radiusMetres}&apikey={YOUR_API_KEY}
Read more about the API URL format.
Find out about how to obtain your API key here: Work with API Keys.
Parameters
Required | Name | Type | Description |
|
|---|
|
| point | string | The point for which the surveys are retrieved. The point is the longitude and latitude of the location on which to centre the image, in the format LONG,LAT. For example, -74.044831,40.689669 Note: ◾️ LONG comes before LAT ◾️ There should be no spaces between the LONG, the comma "," and the LAT |
|
|
| radius | integer | Distance from the point in metres. Used in conjunction with point to define a bounding box (not a circle). Radius range between 1-100. |
|
|
| overlap | string | Whether or not to return metadata for imagery that only partially intersects the requested area. Default is to return all, such that surveys that only partially intersect the AOI will still be returned. If full is specified, then only surveys completely within the given AOI are included. Options include: ◾️ full ◾️ all |
|
|
| since | 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 | string | The last day from which to retrieve the surveys (inclusive). The two possible formats are: ◾️ For 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. |
|
|
| resources | string | Comma separated list of resource types indicating the survey resources to return in the response. This can be any or all of: ◾️ DetailDsm ◾️ TrueOrtho ◾️ Vert Example: DetailDsm,TrueOrtho,Vert |
|
|
| filter | string | Filters surveys returned based on the value of this parameter: ◾️ allTypes - Returns the most recent surveys that contain all content types specified in the resources parameter. This is the default value. ◾️ anyTypes - Returns the most recent surveys that contain at least one of the content types specified in the resources parameter. |
|
|
| fields | string | Comma separated list of field names that will appear in the response. The id field will always be among the returned fields, even if it is not specified. If this parameter is not present, then all fields are returned. This can be any or all of: ◾️ id ◾️ captureDate ◾️ firstPhotoTime ◾️ lastPhotoTime ◾️ pixelSizes Example: id,captureDate,firstPhotoTime,lastPhotoTime,pixelSizes Note: the fields values are case sensitive. |
|
|
| limit | integer | Limit the number of surveys in the result. Default is 20, Maximum is 1000. |
|
|
| offset | 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', the first survey to be displayed will be the 4th most recent survey. |
|
Example
https://api.nearmap.com/staticmap/v2/coverage.json?point=144.967761,-37.821139&radius=50&resources=Vert,DetailDsm,TrueOrtho&since=24M&filter=allTypes&apikey={YOUR_API_KEY}
Response
{
"surveys": [
{
"captureDate": "2021-10-27",
"firstPhotoTime": "2021-10-26T22:02:08Z",
"id": "96a07752-41b1-11ec-b551-0303fe0a0115",
"lastPhotoTime": "2021-11-29T22:01:51Z",
"pixelSizes": {
"DetailDsm": 0.15,
"TrueOrtho": 0.055,
"Vert": 0.055
}
}
],
"limit": 20,
"offset": 0,
"total": 1,
"transactionToken": "{YOUR_TRANSACTION_JWT_HERE}"
}
2. Read the Survey ID and Transaction Token from the coverage response
The transaction token encodes the user credentials and restricts the image to be returned for the same area as the one requested by the coverage request.
IMPORTANT: Keep your Transaction Token in a safe place. Persist your token if you want to reuse it and download multiple images.
3. Image API Call
- This API returns raster content based on the requested location, content type and output format.
- Construct any number of image type requests for the same area as coverage using the Survey ID and Transaction Token.
- Access to DSM, True Ortho, and Vertical imagery
- Image returns using Web Mercator projection
- Able to be used in bulk.
- Support images of up to 5,000 x 5,000 pixels
- The same request with different content types returns an image of the same area.
API URL Format
https://api.nearmap.com/staticmap/v2/surveys/{surveyId}/{imageType}.{format}?point={x},{y}&radius={radiusMetres}&size={imageSize}&transactionToken={TRANSACTION_TOKEN_FROM_COVERAGE_RESPONSE}
Read more about the API URL format.
Parameters
Required | Name | Path / Query | Type | Description |
|---|
|
| surveyID | path | string | Identifier of the survey to retrieve content for, as obtained from the coverage response. This will correspond to a specific date |
|
| type | path | string | Type of raster content to return. This corresponds to the requested types in the coverage end point. It can be one of: ◾️ DetailDsm ◾️ TrueOrtho ◾️ Vert |
|
| format | path | string | File format of the resulting raster image. It can be one of: ◾️ tif ◾️ jpg ◾️ png ◾️ jgw ◾️ pgw ◾️ tfw |
|
| point | query | string | The point for which the surveys are retrieved. The point is the longitude and latitude of the location on which to centre the image, in the format LONG,LAT. For example: -74.044831,40.689669 Note: ◾️ LONG comes before LAT ◾️ There should be no spaces between the LONG, the comma "," and the LAT |
|
| radius | query | integer | Distance from the point in metres. Used in conjunction with point to define a bounding box (not a circle). Radius range between 1-100. |
|
| size | query | string | Size of the resultant image in pixels. It is the responsibility of the caller to maintain the aspect ratio of the requested image. The format is '{width}x{height}', however only equal width and height values are currently supported. Maximum image size is "5000x5000". |
|
| transactionToken | query | string | Transaction token to use in an image request. This token is returned in the staticmap coverage response and contains the authentication information for the request. Multiple image requests made using the same transaction token do not incur additional usage costs within 30 days since the coverage call was made. |
More about filtering
By adding a filter, you can restrict the surveys that are returned. By retaining the default value of allTypes for the filter parameter, you will retrieve the the most recent survey that contains the requested DSM/ True Ortho imagery as well as Vertical imagery.
Setting this parameter to anyTypes returns the most recent survey with Vertical imagery or the next available survey that has the requested DSM/ True Ortho imagery.
Example
To be added
Example
https://api.nearmap.com/staticmap/v2/surveys/dc26410e-6331-11ea-9feb-eb1617c46d8e/TrueOrtho.tif?point=151.0904291%2C-33.724291&radius=100&size=5000x5000&transactionToken={TRANSACTION_TOKEN}
Response
Image requested
Validity and Usage
The coverage response provides a Transaction Token. This token is valid 30 days form the coverage call.
Once you've successfully requested the first image, this is counted against your monthly transaction allowance. You can subsequently make multiple calls to retrieve DSM/TrueOrtho/Vertical imagery within the original AOI without being charged, until the Transaction Token expires.
Service Limits
As you use the API, you should be aware of the following limits:
| Value | Notes |
|---|
| Maximum Image Width/Height | 5000 px | Returned images may be at most 5000 px on either side |
|---|
| Maximum radius | 100 m | A maximum radius of 100 m implies a maximum 200x200 m |
|---|
| Maximum rate limit | As per response headers | The API is rate limited and the rate limit is reported via API headers, see the Rate Limiting section for more information. |
|---|
| Maximum transaction validity | 30 days | Transactions expire 30 days after the transaction token is issued |
|---|
| Available content types | |
|
|---|
Datum and Projection Information
DSM and True Ortho content is delivered using the following specifications:
| DSM | True Ortho |
|---|
Projection | EPSG:3857 (Web Mercator) |
|---|
Horizontal Datum | WGS84 (ITRF2014 realisation) |
|---|
Epoch | date of the imagery.
E.g. epoch of imagery captured on June 30 2017 is 2017.492 |
|---|
| Vertical Datum | AU: AHD (AusGeoid09)
US: EGM2008
Canada: CGVD2013 |
N/A |
|---|
API Documentation
Click here to access the interactive documentation for the API, which allows you to test the API live and inspect the requests and responses.
