Content API
The Content API returns the Nearmap imagery and AI content that is available for a location, and gives you the links and the token to download it. You can search by street address or by parcel.
Before you start:
- Confirm that your subscription includes Property Intelligence.
- Create an API key: in MyAccount, open Integrations → API Keys, choose an API application, and select CREATE KEY. If no application is available, ask your organization's Nearmap administrator to create one. See Create an API Key.
- Choose a location in the United States or Australia that your subscription covers.
- Run the commands below in Bash with curl installed.
Nearmap imagery of other countries, such as Canada and New Zealand, is available through other Nearmap APIs, such as the Tile API, with a Location Intelligence subscription.
This quick start guide takes you from getting an API key to a downloaded image in two requests - search and download. It provides a step by step walkthrough for the two requests from choosing an endpoint to downloading content.
If you're a Property API user, it is recommended that you review the "Migrating from the Property API" section at the end of this article.
1. Searching for a property
Read your API key into an environment variable so the commands below can use it. Paste the key at the prompt and press Enter; your input is hidden:
read -r -s -p "Nearmap API key: " NEARMAP_API_KEY
printf '\n'
export NEARMAP_API_KEYKeep your API key private. Do not commit it to source control or include it in shared logs.
Then search. This example asks for vertical imagery of an address in Sydney:
curl --fail --show-error -X POST "https://api.nearmap.com/content/v1/search/address" \
-H "Authorization: Apikey $NEARMAP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"resources": [ { "namespace": "raster", "type": "vert" } ],
"address": { "address": "6-8 Bulletin Pl, Sydney NSW 2000", "country": "AU" }
}'If your subscription covers the United States rather than Australia, replace the example address with a covered US address and set country to US.
The request body has two parts:
| Field | What it is |
|---|---|
resources | The content you want. Here, vertical imagery (raster, vert). See Build the search request below for the other types. |
address | The street address and its country, US or AU. The address is only looked up in that country. |
A successful search returns 200 with a JSON body. It lists the property it found, a transactionToken for that property and the content that is available, each item with download links.
Searching for a property you haven’t unlocked yet uses one Property Credit, and searching for it again later is free.
If the request fails, curl exits with a nonzero status and reports the HTTP error. Use the Errors section below to choose your next step. For the complete error list, see Content API Error Codes. If no property or content matches, the API returns 404; check the address and country before searching again.
2. Downloading the content
The step 1 response contains everything you need. The following code snippet is trimmed to the parts you use:
{
"properties": [
{ "transactionToken": "eyJhbGciOiJkaXICJjdHkiOiJKV1..." }
],
"resources": [
{
"type": "vert",
"attributes": {
"surveyId": "4917c780-facc-11e8-b671-33ff07a8dfbe",
"firstObservationTime": "2023-05-01T10:30:00Z"
},
"links": {
"staticmap": "https://api.nearmap.com/staticmap/v3/surveys/4917c780-facc-11e8-b671-33ff07a8dfbe/Vert.{format}?x={tileX}&y={tileY}&tileSize=4096x4096"
}
}
]
}The token above is shortened for readability and cannot authorize a download. Copy the complete transactionToken from your own search response, without the surrounding JSON quotes. If the response has no resources, there is no content to download from that response; check your location and requested content types before continuing.
Each resource comes from one survey: one aerial capture of the area on one date. A property captured several times has one resource per survey, so pick the one with the capture date you want (firstObservationTime). Its staticmap link is already built for that survey; you only fill in the placeholders in curly brackets:
| Part of the link | What it is | What you do |
|---|---|---|
surveys/4917c780-… | The survey the imagery comes from, the same ID as surveyId | Nothing, it's already filled in |
Vert | The content type, here vertical imagery | Nothing |
{format} | The image format | Replace with jpg (or png, tif) |
{tileX} | The tile's column, counting from the west | Replace with 0 |
{tileY} | The tile's row, counting from the north | Replace with 0 |
tileSize=4096x4096 | The tile size in pixels | Leave it as it is |
Then, request the completed link with the token in the Authorization header. Run the following commands in the same Bash session. At the first prompt, paste your resource's staticmap link after replacing {format} with jpg, {tileX} with 0, and {tileY} with 0. At the second prompt, paste the complete token from your search response:
read -r -p "Completed staticmap URL: " NEARMAP_STATICMAP_URL
read -r -s -p "Complete transactionToken: " NEARMAP_TRANSACTION_TOKEN
printf '\n'
curl --fail --show-error --output tile.jpg \
"$NEARMAP_STATICMAP_URL" \
-H "Authorization: Transaction $NEARMAP_TRANSACTION_TOKEN"On success, curl exits with status 0 and saves the image to tile.jpg. On an HTTP error, curl exits with a nonzero status; do not treat an existing tile.jpg from a previous request as a successful download. Check the status using the Errors section below.
You get tile.jpg: the north-west tile of the property, up to 4096 x 4096 pixels. Larger properties have more tiles; see the "Static map tiles" section below. A 401 usually means the token has expired (tokens last 1 hour): run the search again.
The example above used one endpoint, one content type and one tile. The four steps below go through the same two requests in full. After them come the rules that apply to every request.
Step by step searching and downloading
Choosing an endpoint
Choose one of the two search endpoints below based on what you already know about the location. Both use POST requests with the base URL https://api.nearmap.com/content/v1.
| Endpoint | Use it when | You send | You get |
|---|---|---|---|
/search/address | You know the street address. | The address and its country (US or AU) | The one property at that address. |
/search/parcels | You have coordinates and want the single land parcel at that spot. | A GeoJSON Point | The parcel that contains the point. If the point matches more than one parcel you get MULTIPLE_PARCELS_FOUND. |
Each endpoint has its own guide with the fields it takes, an example and common variations: Search by Address and Search by Parcel.
GeoJSON coordinates are always longitude first, then latitude: [151.209, -33.862] is Sydney. Swapping them is the most common cause of INVALID_POINT and INVALID_GEOMETRY errors.
For request and response schemas, see the API reference for address searches and parcel searches.
Build the search request
Whichever endpoint you choose, the request body works the same way: it specifies the content you want and narrows the results. Every search names the content you want in a resources array. Each entry has a namespace and a type:
namespace | type | What you get | Download link |
|---|---|---|---|
raster | vert | Vertical imagery (top-down aerial photos) | staticmap, tiles |
raster | trueortho | True Ortho imagery | staticmap, tiles |
raster | detaildsm | Digital Surface Model: elevation including buildings and trees | staticmap (tif only) |
raster | detaildtm | Digital Terrain Model: bare-ground elevation | staticmap (tif only) |
raster | panorama | Panorama (oblique) imagery | See the Content API search reference. |
ai | vector_prediction | AI features as shapes (for example roofs, pools) | aifeatures |
ai | raster_prediction | AI layers as map tiles | tiles |
An entry can also carry selectors to narrow the results, for example by survey ID, capture date or release status. See the Content API search reference for the supported selectors.
Optional fields that apply to the whole search:
| Field | What it does | Default |
|---|---|---|
since, until | Only surveys captured in this date range. YYYY-MM-DD or relative: 10D, 5M, 1Y. Content is available from the last 2 years; an earlier since is treated as 2 years ago. | The last 2 years |
overlap | partial returns content that covers part of your area; full only content that covers all of it. | partial |
limit | Results per page, up to 300. | 20 |
cursor | Fetch the next page. Copy it from the previous response unchanged. |
Read the response
Every endpoint returns the same shape of response. It tells you what was found and how to get it.
| Field | What it is |
|---|---|
properties[] | What the search matched. Each item has an id, a type (parcel for a land parcel, aoi for a searched area), an address, a point and its own transactionToken. |
resources[] | attributes holds the capture times, the surveyId and the tile grid size (scale); links holds the download links. |
cursor | Present when there are more results. Send it back in your next search to get the next page. |
Download the content
To get the content itself, use a link from resources[] together with the token from properties[]. Each resource's links object contains one or more of these:
| Link | How to use it |
|---|---|
aifeatures | Complete. Call it as is. |
tiles | Standard web map tiles: fill in {z}/{x}/{y} and {format} as you would for any slippy map. |
staticmap | An image of the property area, split into tiles for larger properties. Fill in {format} (jpg, png or tif; DSM and DTM are tif only), {tileX} and {tileY}. Keep tileSize as it is. |
Every download request needs the header Authorization: Transaction <transactionToken>.
A token in the URL (?transactionToken=) is rejected with 401.
Static map tiles
A large property doesn't fit in one image, so staticmap splits the area into a grid of 4096 x 4096 pixel tiles. {tileX} and {tileY} choose one tile:
{tileX}is the column, from0toscale.widthInTiles - 1, counting west to east{tileY}is the row, from0toscale.heightInTiles - 1, counting north to south
So x=0&y=0 is the north-west corner. A property with widthInTiles: 4 and heightInTiles: 4 has 16 tiles. Tiles on the east and south edges can be smaller than 4096 pixels.
Rules for every request
These apply whichever endpoint you use.
Transaction tokens
The token from a search is your permission to download. Three rules apply to it:
- Validity: 1 hour from the search. After that, run the same search again for a new token. Searching again for a property you already unlocked costs nothing.
- Scope: A token works only with the download links returned by a Content API search.
- Size: About 2,800 characters, all sent in one header. Most tools accept that. If downloads fail with
431 Request Header Fields Too Largeor400 Bad Requestbut work from curl, a proxy or library in your setup limits header size: raise its limit to at least 8 KB.
Property credits
You pay for searches, with Property Credits. Downloading the content you find is free.
- Unlocking a property uses one Property Credit.
- Searching again for an address or parcel you already unlocked is free for the rest of your subscription period.
- If an address can’t be matched to a parcel, the search treats the address as a point and covers a square extending 30 meters in each direction (60 × 60 m). Every property inside that square uses a credit, so one address can use more than one credit.
- Retrying a request that failed doesn’t charge you twice.
- Property Intelligence usage counts only against Property Credits, not against a Daily API Rate Allowance.
Errors
When a request fails, the status code tells you what to do next: fix the request, search again or retry. This section covers the common cases. For the complete list, see Content API Error Codes.
Check the HTTP status and Content-Type before parsing the body. API errors return JSON with a human-readable error; gateway errors and the 429 and 503 responses described below can return plain text. Every 400 and the ALLOWANCE_EXCEEDED 403 also carry a code; 404s have only the message.
Search errors
| Status | Code | What it means | What to do |
|---|---|---|---|
400 | REQUEST_PARSE_FAILURE | The body isn't valid JSON for this endpoint, a required field is missing, or a value in it (such as the address or an AI content type) couldn't be processed. | Check it against the API reference. |
400 | INVALID_ADDRESS | The address is blank or only spaces. | Send the street address. |
400 | INVALID_RESOURCE, INVALID_SELECTOR | A content type or selector isn't supported. | Use the values in the "Build the search request" section above. |
400 | INVALID_POINT, INVALID_GEOMETRY, INVALID_RADIUS | The location isn't valid. | Check longitude/latitude order and the radius (a whole number from 1 to 100, both included). |
400 | INVALID_COUNTRY | The address country isn't US or AU, or is a point, parcel or area not in US or AU. | Search only in the United States or Australia. |
400 | INVALID_DATE, INVALID_DATE_RANGE | since or until is invalid. | Use YYYY-MM-DD or a relative value such as 10D, 5M, or 1Y. Check that since is not later than until. |
400 | INVALID_LIMIT, INVALID_OVERLAP, INVALID_CURSOR | A paging or filter value is invalid. | Use a positive integer no greater than 300 for limit, partial or full for overlap, and send the cursor back exactly as received. |
400 | MULTIPLE_PARCELS_FOUND | The address, or the point sent to /search/parcels, matched more than one parcel. | Make the address more specific, or move the point inside the parcel you want. |
401 | The API key is missing or invalid. | Send the key as Authorization: Apikey <key>. | |
403 | API_NOT_ENTITLED, SUBSCRIPTION_NOT_SUPPORTED | Your subscription, or its type, doesn’t include the Content API. | Contact your account manager. |
403 | AI_NOT_ENTITLED | You asked for AI content and your subscription doesn’t include AI. | Remove the ai entries, or check with your account manager about AI access. |
403 | AREA_NOT_AUTHORIZED | The location is outside the areas your subscription covers. | Check the location is inside your subscription’s area. |
403 | ALLOWANCE_EXCEEDED | Your Property Credits are used up. | Contact your account manager. |
404 | No property or no content was found for the search. | For address searches, check country matches the country the address is in. | |
429 | Too many requests: you used your 3,000 searches for this hour. The body is plain text. | Wait until the time in X-RateLimit-Reset. See Rate limits below. | |
500 | SYSTEM_ERROR | Something went wrong on our side. | Retry a few times with exponential backoff. If the same request keeps failing, contact support with the request ID. |
503 | The service is busy: too many requests are being handled at once. The body is plain text (Service rate limit exceeded). | Retry with exponential backoff, and send fewer requests in parallel. |
Timeouts: Most searches return in well under a second, but allow at least 60 seconds before your client gives up.
Contacting support: Include the X-Hyperweb-Requestid header, request time and time zone, URL, HTTP method, request body, HTTP status, response body, and response time. Include X-Amz-Cf-Id if present. Remove API keys and transaction tokens before sharing details. See Capturing Information for Failed API Requests for the full checklist.
Rate limits
Separately from what you pay, the number of search requests you can send is limited: up to 3,000 requests per hour. For how rate limits work across Nearmap APIs, see API Rate Limits. The following are specific to the Content API:
- The limit is per user, not per API key: all your keys share one allowance.
- Requests to the old
/property/resources/v1URLs count toward the same limit. - The
429body is plain text (Rate limit exceeded), not JSON, so check the status before parsing the body. - The hour starts with your first request; it’s a fixed hour, not a rolling one. If you use the whole limit early, further searches are refused until the hour resets, so spread large batches out.
- Separately, the service limits how many requests it handles at the same time. If you send many requests in parallel, some can return
503with the plain-text bodyService rate limit exceeded. Retry those with exponential backoff and lower your parallelism.
Every response tells you where you stand:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Your hourly limit (3,000). |
X-RateLimit-Remaining | Requests left this hour. |
X-RateLimit-Reset | When the limit resets, as a Unix timestamp in seconds. |
There’s no Retry-After header: wait until the time in X-RateLimit-Reset. Retries count toward the limit, so cap how often your client retries a failing request. If a response has no rate-limit headers, don’t assume there’s no limit.
Migrating from the Property API
The Content API is the Property API with a new name and URL. The old /property/resources/v1 endpoints are deprecated and will be switched off; the date will be announced ahead of time. Move your integration now. Only the URL changes:
| Old POST endpoint | New POST endpoint |
|---|---|
/property/resources/v1/properties/address | /content/v1/search/address |
/property/resources/v1/properties/parcels | /content/v1/search/parcels |
Request bodies, responses, authentication and tokens are the same on both.
Updated about 21 hours ago
