API Reference

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 de-duplicated, 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.

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.

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 1sq km 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}