The AI Feature API allows you to retrieve a small Area of Interest (AOI) from our " Open World " style vector map that exists for our Gen3+ AI content. You can use your Nearmap AI export credits to extract a single building at a specific location to the AOI enclosed by a property, or even a small neighbourhood. All you need to provide is a polygon for your Query AOI, an optional date range, and your Nearmap API Key. |
The AI Feature API allows programmatic access to Nearmap AI for Gen 3 content and beyond. You can use the AI Feature API for:
Illustration of defining a Query AOI (outlined in red) on our vector map, and returning some of the features and attributes. The data necessary to visualise the shapes and metadata within the Query AOI is all included in a single API payload.
If you already have access to the relevant AI Packs, and an appropriate number of Nearmap AI export credits, all you need to do is ask your account manager to add the "AI Feature API" product to your subscription. This leverages the shared Nearmap AI credit balance and AI Pack configuration - just think of it as an additional way to access the data to which you have already subscribed.
If you do not yet have Nearmap AI, learn how to get started in this article: Access AI Content . Note that each user must be enabled separately by your Nearmap account administrator to use the AI Feature API, and each API user will also need AI Export. Permissions. Find out more here: Manage a User's 3D or AI Export Permissions
To use any of our Nearmap APIs, you need an API key. Learn how to get an API key here: API Key Authentication.
The Getting Started Guide is a Jupyter Notebook containing python code and informal documentation to help you get up and running as quickly as possible. It explores a range of common tasks, and provides a useful base of algorithms and 3rd party packages that may help software developers who do not have a geospatial background to get started quickly with simple tasks such as calculating areas and distances between objects.
The formal API Specification has been made available here. This is the best place to go for precise details on permitted query parameters, available endpoints, response formats and error codes once you have access to the API.
Here, we provide a quick overview of each endpoint in the AI Feature API. An endpoint is a particular base URL which allows you to perform a certain type of query, and receive the relevant response.
features.jsonhttps://api.nearmap.com/ai/features/v4/features.json |
This API endpoint of the AI Feature API takes the Query AOI as a polygon, and returns the results contained within it.
Usage patterns
The most common usage pattern is to retrieve a property boundary as the Query AOI, either from a locally stored database of property boundaries, or daisy-chained with a 3rd party API (where a latitude/longitude or address is used to retrieve a parcel boundary, and that parcel boundary is then used with the features.json endpoint). A variety of these parcel data sets and APIs is available in each of the coverage areas in which we operate.
Other uses include:
This endpoint provides the most flexibility and precision to ensure there is no ambiguity around what is being returned.
What happens to features intersected by the AOI polygon?
In general, all feature polygons (and their associated attribute metadata) that intersect with the query polygon are returned in full, without being truncated. This allows you to deal with potential parcel boundary errors as you see fit, by excluding or including whole buildings, for example, or cutting them at the location of your choice. The only exception to this rule is the potentially unbounded features in the Vegetation and Surfaces packs, which are cropped to the Query AOI. This is to prevent a single query from inadvertently returning an entire ocean or forest in a single payload.
The data structure is designed to be approximately the REST API equivalent of what can be exported from MapBrowser – the spreadsheet file of parcel "roll-ups", and the rich geospatial file of the feature polygons. The features.json endpoint seeks to return the fullest, richest set of data possible, and as a result, is not designed to plug instantly into any particular software package or platform. The necessary information is, however, included in each payload, such that a variety of wrappers could be constructed to perform more specific tasks.
The data structure is best described here.
The simplest sample query to get you started is:
https://api.nearmap.com/ai/features/v4/features.json?polygon={lon1,lat1,lon2,lat2,...}&apikey={your_nearmap_api_key} |
This will return the latest available Nearmap AI data from the provided polygon.
A slightly more complex query would be:
https://api.nearmap.com/ai/features/v4/features.json?polygon={lon1,lat1,lon2,lat2,...}&since=2020-01-01&until=2020-12-31&packs=building&apikey={your_nearmap_api_key} |
This will return the latest result within the date window (the year 2020), and strip the response payload back to the data enabled by "AI Pack: Building Footprints" only (even if you have other AI Packs attached to your subscription).
You can also use a survey ID directly from our coverage API to select the survey, rather than a date range:
https://api.nearmap.com/ai/features/v4/features.json?polygon={lon1,lat1,lon2,lat2,...}&surveyResourceId={survey_resource_id_from_coverage}&apikey={your_nearmap_api_key} |
classes.jsonhttps://api.nearmap.com/ai/features/v4/classes.json?apikey={your_nearmap_api_key} |
The classes.json endpoint is used to retrieve information about all the Feature Classes you have access to with your AI Packs. All the features (polygons) returned by the features.json endpoint have both an individual uuid for unique identification, and a feature class, which also has a uuid. The feature class (such as "Building") allows you to code specific patterns of behaviour in your application when features of that specific type are returned – whether to control z order and styling for visualisation purposes, or to inspect and use the metadata as part of your workflow.
Note that human-readable descriptions of Feature Classes should NOT be used in application code, as we reserve the right to adjusts them. The uuid of each feature class is immutable, and will always be associated with that semantic definition. It can therefore be mapped to your preferred description for exposure in your application or used internally for mapping the right application behaviour.
packs.jsonhttps://api.nearmap.com/ai/features/v4/packs.json?apikey={your_nearmap_api_key} |
The packs.json endpoint is used to show which packs are available on the user's subscription and provides a richer and more complex data structure than the more simple classes.json endpoint.
coverage.jsonhttps://api.nearmap.com/ai/features/v4/coverage.json?point={lon},{lat}apikey={your_nearmap_api_key} |
The coverage.json endpoint is used to find what surveys (dates and survey resource IDs) have had AI data processed. The response not only provides the surveys that have AI data, but the precise version of the data (systemVersion), and which feature and attribute class IDs are available on it.
The current limits imposed on the API for general customers are Query AOIs up to 1km2 and a limit of 20 requests per second. These may be adjusted over time. The 1km2 limit is designed to permit any reasonable individual property parcel to be requested (e.g. an airport or golf course). The easiest way to deal with larger or multipolygon areas is to break into multiple API requests.
The limit of 20 requests per second equates to about 1.7 million requests per 24-hour period. This is roughly what is achievable with a single desktop machine maxing out CPU usage with multiple parallel requests on a fast internet connection. For large enterprise bulk requests, higher rates may be required. If you require a rate higher than 20 requests per second, please talk to your account manager.