---
title: "Survey resources that intersect within an area of interest (polygon or multipolygon)"
method: POST
path: "/aoi"
tags: ["coverage"]
---

# Survey resources that intersect within an area of interest (polygon or multipolygon)

`POST /aoi`

## Request

- Base URL: `https://api.nearmap.com/coverage/v2`
- URL: `https://api.nearmap.com/coverage/v2/aoi`
- Auth: one of:
  - API key in query parameter `apikey`
  - API key in header `Authorization`

Return all survey resources that intersect with the given aoi specified in POST body.

## Query parameters

- `limit` integer
- `offset` integer
- `sort` string
- `fields` string

## Request body

- object
  - `until` string, required: Last day from which to retrieve the surveys (inclusive). Must be of the form "YYYY-MM-DD".
  - `since` string, required: First day from which to retrieve the surveys (inclusive). Must be of the form "YYYY-MM-DD".
  - `resources` string, required: Comma separated list of resource types to include in the response in the form of "resourceClass:type" where ":type" is optional and represents all types of a resource class if not present. If not specified then all types are returned.
  - `mode` string, required: Overlap mode, can be "all" or "full", default is "all". "all" means input polygon intersect with content's polygon, "full" means input polygon within content's polygon.
  - `aoi` object, required: Polygon or multipolygon describing the area of interest for the query
  - `include` string, required: Specify tags survey resource should include, return survey resource that match AT LEAST ONE of exposed tag \ Comma separated tag query strings. Tag structure is TagType:TagName \ Single tag query can be TagType only, match same tag type with any tag value. \ Supported tag types are present in the coverage response
  - `exclude` string, required: Specify tags survey resource should exclude, return survey resource does NOT match any exposed tag\ Comma separated tag query strings. Tag structure is TagType:TagName \ Single tag query can be TagType only, match same tag type with any tag value. \ Supported tag types are present in the coverage response

## Response `200`

Survey resources matching criteria

- Result
  - `surveys` Survey[]
    - `id` string: Unique id of survey
    - `captureDate` string: Date that survey was captured on, in the format "YYYY-MM-DD"
    - `firstPhotoTime` string: Date and time in UTC of the first photo taken in the survey
    - `lastPhotoTime` string: Date and time in UTC of the last photo taken in the survey
    - `onlineTime` string: Date and time in UTC when the survey became available online
    - `pixelSize` integer: Ground sample distance in meters
    - `timezone` string: Universal timezone abbreviation of the location of the survey
    - `utcOffset` integer: Difference in minutes between UTC and the local timezone
    - `location` Location
      - `country` string: Country code of the survey
      - `region` string: City or a locale in which the survey is situated
      - `state` string: State containing the survey
    - `tags` object: Additional metadata about the survey such as post catastrophe events.
    - `resources` object: Dictionary keyed on resource class name with value an array of resources
  - `limit` integer: the limit of the total number of surveys returned, as specified in the request
  - `offset` integer: the offset of the first survey to be displayed, as specified in the request
  - `total` integer: the total number of surveys available for this request

## Other responses

- `400`: On bad input parameter or if polygon is invalid.

---

[API](https://skmtc.dev/nearmap/apis/coverage.md) - [All operations](https://skmtc.dev/nearmap/apis/coverage/llms.txt) - [OpenAPI document](https://skmtc.dev/nearmap/apis/coverage/revisions/82449937f4df?raw)