The AI Feature API allows you to clip out a small area of interest from our " Open World " style vector map that exists for our Gen3+ AI content. You can spend Nearmap AI export credits to pull a single building at a requested location, to the Area of Interest (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.

Use Cases

The AI Feature API allows programmatic access to Nearmap AI for Gen 3 content and beyond. The ideal use cases are:

  • Distributed AOIs: If you have a number of small areas of interest (such as property parcels) that are distributed broadly (such as an insurance carrier) rather than clustered in a contiguous region (such as a local government authority).
  • 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 pull e.g. the latest result available for each property, without worrying about which survey regions you require access to.
  • Regular updates: While some customers prefer to do a single download per year, others gain value from continuously updating the data set in a transactional way. This is most convenient when automated via an API, 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 at typically an order of magnitude faster than on-the-fly AI processing systems.

Illustration of clipping a Query AOI (outlined in red) out of 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.

Getting Started

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.

API Specification

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.

features.json

https://api.nearmap.com/ai/features/v4/features.json


This API endpoint is the core workhorse of the AI Feature API, taking a Query AOI as a polygon, and returning 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 lat/lon 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 falling on a building will return the whole building.
  • Assembling a map from tiled Query AOIs: Performing tiled requests to assemble a map of a larger area. 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 tiled set of Query AOIs that are at the larger end of our performance limits. Note that this approach may spend a large number of credits per query (but the total number of credits will be equivalent to what would have been spent 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 sufficiently 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.

An on-the-fly-summary of each Query AOI is also performed to produce the equivalent of the property rollups (such as binary presence of objects).

Data Structure

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 roll-ups are created on the fly to match the exact parcel query provided. 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 <Link to swagger spec>.

Sample Queries

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).

classes.json

https://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.json

https://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.

Limits

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.

Swagger Spec

https://app.swaggerhub.com/apis/nearmap/ai-feature-api




FAQs