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.
Why AI Feature API?
The AI Feature API allows programmatic access to Nearmap AI for Gen 3 content and beyond. You can use the AI Feature API for:
- Distributed AOIs: If you have a number of small areas of interest that are distributed broadly rather than clustered in a contiguous region. For example, assessment of property parcels for an insurance carrier.
- Large data sets: If your AOI crosses multiple regions, it is best to use the date query in the AI Feature API. This allows you to extract the latest result available for each property regardless of the survey regions to which you require access.
- Regular updates: For customers who continuously update their data set in a transactional way, the API can be used to automated this rather than relying on a user to frequently export via MapBrowser.
- Real-time access: Customer-facing applications that require real-time retrieval of Nearmap AI content are well suited to API access. Because all our AI content is pre-processed, the time taken to retrieve the results is typically faster than on-the-fly AI processing systems.
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.
Accessing the API
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.
Getting Started Guide
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 as a Swagger Spec. 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.
This API endpoint of the AI Feature API takes the Query AOI as a polygon, and returns the results contained within it.
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:
- Individual feature retrieval from a small Query AOI: Requesting a very small Query AOI at a location where a building or other object is expected. The API returns any features that intersect with your AOI, so a small Query AOI including a building will return the entire building.
- Assembling a map of a larger area from tiled Query AOIs: Because each feature has a unique ID, features intersecting the boundary of your Query AOIs can be successfully deduplicated, and a full seamless map assembled. The most efficient way to do this is to create a set of tiled Query AOIs that are at the larger end of our performance limits. Note that this approach may consume a large number of credits per query (but the total number of credits will be equivalent to the number consumed on the same AOI with a MapBrowser export).
- Real-time retrieval of an end user's Query AOI: Some of our customers have online tools where their end-user can dynamically define an AOI. This AOI can be used as a Query AOI, and the results will be returned quickly to provide a seamless real-time experience.
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 by the Swagger Spec here.
The simplest sample query to get you started is:
This will return the latest available Nearmap AI data from the provided polygon.
A slightly more complex query would be:
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:
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.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
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. If higher rates are required (such as large enterprise bulk requests using cloud infrastructure), please talk to your account manager.
Can I query other attributes in the AI glossary with AI Feature API? —
No. With AI Feature API you can query any of the data attributes in the AI Packs that you are subscribed to. There are additional AI Layers listed in the glossary which are not included in AI Packs, and are not available behind the AI Feature API.
Check out all available AI Packs here: AI Packs
Note that you can use the same credits for exporting AI data from MapBrowser as you do returning them using the AI Feature API.