---
title: "Search for flight positions"
method: GET
path: "/flights/search/positions"
tags: ["flights"]
---

# Search for flight positions

`GET /flights/search/positions`

## Request

- Base URL: `https://aeroapi.flightaware.com/aeroapi`
- URL: `https://aeroapi.flightaware.com/aeroapi/flights/search/positions`
- Auth: API key in header `x-apikey`
- TypeScript: <https://skmtc.dev/flightaware/apis/aeroapi/docs/flights/search/positions/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns flight positions based on geospatial search parameters.  This
allows you to locate flights that have ever flown within a specific a
latitude/longitude box, groundspeed, and altitude. It takes search
terms in a single string comprising of {operator key value} elements
and returns an array of flight structures. Each search term must be
enclosed in curly braces. Multiple search terms can be combined in an
implicit boolean "and" by separating the terms with at least one space.
This function only searches flight data representing approximately the
last 24 hours.

The supported operators include (note that operators take different numbers of arguments):

* false - results must have the specified boolean key set to a value of false. Example: {false preferred}
* true - results must have the specified boolean key set to a value of true. Example: {true preferred}
* null - results must have the specified key set to a null value. Example: {null waypoints}
* notnull - results must have the specified key not set to a null value. Example: {notnull aircraftType}
* = - results must have a key that exactly matches the specified value. Example: {= fp C172}
* != - results must have a key that must not match the specified value. Example: {!= prefix H}
* < - results must have a key that is lexicographically less-than a specified value. Example: {< arrivalTime 1276811040}
* \> - results must have a key that is lexicographically greater-than a specified value. Example: {> speed 500}
* <= - results must have a key that is lexicographically less-than-or-equal-to a specified value. Example: {<= alt 8000}
* \>= - results must have a key that is lexicographically greater-than-or-equal-to a specified value.
* match - results must have a key that matches against a case-insensitive wildcard pattern. Example: {match ident AAL*}
* notmatch - results must have a key that does not match against a case-insensitive wildcard pattern. Example: {notmatch aircraftType B76*}
* range - results must have a key that is numerically between the two specified values. Example: {range alt 8000 20000}
* in - results must have a key that exactly matches one of the specified values. Example: {in orig {KLAX KBUR KSNA KLGB}}

The supported key names include (note that not all of these key names are returned in the result structure, and some have slightly different names):

* alt - Altitude, measured in hundreds of feet or Flight Level.
* altChange - a one-character code indicating the change in altitude.
* cid - a three-character cid code
* clock - UNIX epoch timestamp seconds since 1970
* fp - unique identifier assigned by FlightAware for this flight, aka fa_flight_id.
* gs - ground speed, measured in kts.
* lat - latitude of the reported position.
* lon - longitude of the reported position
* updateType - source of the last reported position (P=projected, O=oceanic, Z=radar, A=ADS-B, M=multilateration, D=datalink, X=surface and near surface (ADS-B and ASDE-X), S=space-based)

## Query parameters

- `query` string
- `unique_flights` boolean
- `max_pages` integer
- `cursor` string

## Response `200`

OK

- object
  - `links` object, nullable, required: Object containing links to related resources.
    - `next` string, uri-reference, required: A link to the next set of records in a collection.
  - `num_pages` integer, required: Number of pages returned
  - `positions` object[], required
    - `fa_flight_id` string, nullable, required: Unique identifier assigned by FlightAware to the flight with this position. This field is only populated by the `/flights/search/positions` (in other cases, the user will have already specified the fa_flight_id).
    - `altitude` integer, required: Aircraft altitude in hundreds of feet
    - `altitude_change` 'C' | 'D' | '-', required: C when the aircraft is climbing, D when descending, and - when the altitude is being maintained.
    - `groundspeed` integer, required: Most recent groundspeed (knots)
    - `heading` integer, nullable, required: Aircraft heading in degrees (0-360)
    - `latitude` number, required: Most recent latitude position
    - `longitude` number, required: Most recent longitude position
    - `timestamp` string, date-time, required: Time that position was received
    - `update_type` 'P' | 'O' | 'Z' | 'A' | 'M' | 'D' | 'X' | 'S' | 'null', nullable, required: P=projected, O=oceanic, Z=radar, A=ADS-B, M=multilateration, D=datalink, X=surface and near surface (ADS-B and ASDE-X), S=space-based

## Other responses

- `400`: Incorrect parameter(s). Expected: pages > 0.

---

[API](https://skmtc.dev/flightaware/apis/aeroapi.md) - [All operations](https://skmtc.dev/flightaware/apis/aeroapi/llms.txt) - [OpenAPI document](https://skmtc.dev/flightaware/apis/aeroapi/revisions/3023e7a0c54c?raw)