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.json
https://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 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.
NOTE: 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.
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 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.
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 multi-polygon 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.
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).
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.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: 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.
coverage.json
https://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.
