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.

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:

Datum and Projection Information

DSM and True Ortho content is delivered using the following specifications:

Interactive API Documentation

Below section provides interactive documentation for the API, allowing you to test the API live and inspect the requests and responses. 

FAQs

• Page:
  What does "Error: invalid aoi claim: requested AOI is not within allowed AOI in transaction token" mean? —

  When using the DSM and True Ortho 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 True Ortho API

• Page:
  Can I request the DSM and True Ortho 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.

• Page:
  How can I control the resolution of the DSM and True Ortho 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

• Page:
  What if the radius and size I specify in DSM and True Ortho means an image of much higher resolution than is possible? —

  In this case, the image returned is the highest resolution Nearmap imagery. 

• Page:
  Is the radius I specify in DSM and True Ortho 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.

• Page:
  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 True Ortho API

• Page:
  How many DSM and True Ortho 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, True Ortho, Vertical) and of any vintage.

• Page:
  How can I check my monthly DSM and True Ortho usage? —

  Yes. If you are a Nearmap Administrator, you can see your monthly allowance and your usage in MyAccount. As an administrator you can, view your account data usage.