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 TrueOrtho API requires a special subscription. Contact your Nearmap Account Manager for more information.
Before you start using your DSM and TrueOrtho 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: Change a Nearmap Licence.
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: Managing API Keys
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.
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}.
Read more about the API URL format.
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 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. | |
Vertical Datum | AU: AHD (AusGeoid09) US: EGM2008 Canada: CGVD2013 | N/A |
Interactive API Documentation
Below section provides an interactive documentation for the API, allowing you to test the API live and inspect the requests and responses.
FAQs
-
I want to retrieve imagery for an area larger than 100 metres. Can I do this with the DSM API? —
To do this, you will need to make multiple coverage calls (i.e. with a Transaction Token for each), make the image calls and stitch together the images.
Find out more here: DSM and TrueOrtho API
-
What does "Error: invalid aoi claim: requested AOI is not within allowed AOI in transaction token" mean? —
When using the DSM and TrueOrtho API, your coverage radius is smaller than your image call radius. Ensure your coverage radius is as large as you require.
Find out more here: DSM and TrueOrtho API
-
Can I request the DSM and TrueOrtho image and have the API return an image using the best possible resolution? —
The physical and pixel size of the image are deliberately explicit to give you control over the image that will be returned. This is further complicated by the fact that True Ortho and DSM are of different native resolutions (0.055 m versus 0.15 m).
Request the imagery by inspecting the coverage response and then calculating the pixel size based on the metadata.
-
How can I control the resolution of the DSM and TrueOrtho image retrieved? —
The image resolution is determined by the image length (2 x radius) and the size in pixels. This allows us to maintain the location as the centre point of the image. Refer to the examples below as an illustration of how radius and size values determine image resolution.
radius: 10 m
length: 20 m
size: 100x100 px
pixel size: 5 m -
What if the radius and size I specify in DSM and TrueOrtho means an image of much higher resolution than is possible? —
In this case, the image returned is the highest resolution Nearmap imagery.
-
Is the radius I specify in DSM and TrueOrtho a true radius ? —
The radius is not a radial dimension with location as centre point. The radius defines a square bounding box with location as the centre. Note also that the units are real world and not Web Mercator metres.
-
How can I check my monthly DSM and TrueOrtho usage? —
Yes. If you are a Nearmap Administrator, in the Self Service Portal you can see your monthly allowance and your usage, expressed as number of transactions. Learn how to View Account Data Usage.
-
How many DSM and TrueOrtho image requests can I make with one Transaction Token? —
For the 30 day life of your Transaction Token, you can make any number of image requests on any or all three content types (DSM, TrueOrtho, Vertical) and of any vintage.