# Search airports

> Airport and city autocomplete for the origin and destination of a search: send what the user has typed (an IATA code, a city or an airport name) and use the ap of the chosen record as origin or destination.

Endpoint: `GET /flights/airports`

Source: https://fx-port.com/docs/api/search-airports

`GET /api/v1/flights/airports`

No API key is needed to call this endpoint.

No key is needed. The endpoint is built for a debounced typeahead: wait about 300 ms after the last keystroke and cancel the request that is in flight. The answer is a flat array with no `environment` key, and it can be kept for a minute by a browser and five minutes by a CDN (`Cache-Control: public, max-age=60, s-maxage=300`). A city code such as `PAR` (`isMetroOnly: true`) is valid as an origin or a destination and stands for every airport of the city.

The lookups of one IP address are limited: a `429` carries `Retry-After`. When the lookup service is down the endpoint can answer `200` with up to 10 airports from a local list instead of an error.

## Request

### Query parameters

- `query` (string, required): What the user typed: an IATA code (`ALG`), a city (`Paris`) or an airport name. 1 to 64 characters once cleaned: control characters are removed and runs of spaces become one.
- `locale` (string, optional): The language of the names, `ll` or `ll-RR` (`en`, `fr`, `ar`, `es-AR`, `zh-CN` ...). Case and `_` or `-` are normalised (`FR` is `fr`); anything else is read as `en`. A well-formed locale the lookup does not know is not rejected: the names come back in English. Default `en`.

### Example request

```bash
curl 'https://api.fx-port.com/api/v1/flights/airports?query=ALG&locale=en'
```

## Response

### 200: A flat **array** of airports and cities, best match first. A real record has about 40 keys: only the ones listed in the schema are meant for your use.

```json
[
  {
    "id": "ALG",
    "displayname": "Houari Boumediene, Algiers, Algeria, (ALG)",
    "loctype": "ap",
    "cid": 3,
    "rid": 480,
    "ctid": 10465,
    "lat": 36.6985,
    "lng": 3.20672,
    "cc": "DZ",
    "country": "Algeria",
    "rc": "AL",
    "cityname": "Algiers, Algeria",
    "timezone": "Africa/Algiers",
    "utc": "+01:00",
    "airportname": "Houari Boumediene",
    "ap": "ALG",
    "apicode": "ALG",
    "box_maxX": 3.26672,
    "box_maxY": 36.7335,
    "box_minX": 3.1467199999999997,
    "box_minY": 36.663500000000006,
    "cityonly": "Algiers",
    "destination_images": {
      "image_jpeg": "https://content.r9cdn.net/rimg/dimg/a2/04/dd9815df-city-10465-164dc51f899.jpg?width=128&height=128&xhint=2298&yhint=1960&outputtype=JPEG&crop=true",
      "image_webp": "https://content.r9cdn.net/rimg/dimg/a2/04/dd9815df-city-10465-164dc51f899.jpg?width=128&height=128&xhint=2298&yhint=1960&outputtype=WEBP&crop=true"
    },
    "displayType": {
      "type": "airport",
      "displayName": "Airport"
    },
    "entityKey": "place:Houari_Boumediene_Airport",
    "indexId": "176626",
    "isMetroOnly": false,
    "kayakId": "ALG",
    "kayakType": "ap",
    "locationname": "Algiers, Algeria",
    "name": "Houari Boumediene",
    "objectID": "P189646",
    "placeID": "176626",
    "ptid": "AALG",
    "region": "Algiers",
    "searchFormPrimary": "ALG",
    "searchFormSecondary": "Algiers, Algeria",
    "secondary": "Algiers, Algeria",
    "shortdisplayname": "Algiers, Algeria (ALG)",
    "smartyDisplay": "Houari Boumediene, Algiers, Algeria, (ALG)"
  },
  {
    "id": "AHO",
    "displayname": "Alghero-Fertilia, Alghero, Sardinia, Italy, (AHO)",
    "loctype": "ap",
    "cid": 118,
    "rid": 1673,
    "ctid": 32049,
    "lat": 40.63213,
    "lng": 8.29077,
    "cc": "IT",
    "country": "Italy",
    "rc": "SA",
    "cityname": "Alghero, Sardinia, Italy",
    "timezone": "Europe/Rome",
    "utc": "+02:00",
    "airportname": "Alghero-Fertilia",
    "ap": "AHO",
    "apicode": "AHO",
    "box_maxX": 8.35077,
    "box_maxY": 40.66712999999999,
    "box_minX": 8.23077,
    "box_minY": 40.59713,
    "cityonly": "Alghero",
    "destination_images": {
      "image_jpeg": "https://content.r9cdn.net/rimg/dimg/ee/86/623980ff-city-32049-1700cc8a82e.jpg?width=128&height=128&xhint=2050&yhint=1293&outputtype=JPEG&crop=true",
      "image_webp": "https://content.r9cdn.net/rimg/dimg/ee/86/623980ff-city-32049-1700cc8a82e.jpg?width=128&height=128&xhint=2050&yhint=1293&outputtype=WEBP&crop=true"
    },
    "displayType": {
      "type": "airport",
      "displayName": "Airport"
    },
    "entityKey": "place:Fertilia_Airport",
    "indexId": "177457",
    "isMetroOnly": false,
    "kayakId": "AHO",
    "kayakType": "ap",
    "locationname": "Alghero, Sardinia, Italy",
    "name": "Alghero-Fertilia",
    "objectID": "P233628",
    "placeID": "177457",
    "ptid": "AAHO",
    "region": "Sardinia",
    "searchFormPrimary": "AHO",
    "searchFormSecondary": "Alghero, Sardinia, Italy",
    "secondary": "Alghero, Sardinia, Italy",
    "shortdisplayname": "Alghero, Sardinia, Italy (AHO)",
    "smartyDisplay": "Alghero-Fertilia, Alghero, Sardinia, Italy, (AHO)",
    "subregion": "Sassari"
  }
]
```

## Errors

| Status | Code | Example message |
| --- | --- | --- |
| 422 | `invalid_query` | query must be 1-64 characters. |

See [Errors](https://fx-port.com/docs/errors.md) for every code and how to react.

## Related guides

- [Search airports](https://fx-port.com/docs/flights/airports.md)