# Airports



The full airport directory, searchable by name or code, or by nearest to a point.



## Airport Directory

Every airport with an IATA code or a scheduled service — 8,900 of them, with codes, coordinates, elevation, and city.

- Method: `GET`
- Path: `/v1/airports`

**Parameters**

| Name | Type | | Description |
|---|---|---|---|
| `q` | string | optional | Name, city, IATA, or ICAO. An exact code match is returned first. |
| `country` | string | optional | ISO 3166-1 alpha-2, e.g. `ID`. One of `q` or `country` is required. |
| `size` | string | optional | `large`, `medium`, or `small`. |
| `scheduled` | boolean | optional | Only airports an airline actually schedules a service to. |
| `limit` | integer | optional | 1 to 100. |

**Example request**

```bash
curl https://api.diraz.ae/v1/airports \
  -H "Authorization: Bearer drz_live_…"
```

**Example response**

```json
{
  "data": {
    "total_indexed": 8931,
    "airports": [
      {
        "icao": "WIII",
        "iata": "CGK",
        "name": "Soekarno-Hatta International Airport",
        "size": "large",
        "country": "ID",
        "region": "ID-BT",
        "city": "Jakarta",
        "lat": -6.12557,
        "lon": 106.65589,
        "elevation_ft": 34,
        "scheduled": true
      }
    ]
  },
  "meta": {
    "request_id": "req_7Q2fK4mZ"
  }
}
```

## Nearest Airport

The closest airports to any coordinates, ordered by great-circle distance, with a radius you set.

- Method: `GET`
- Path: `/v1/airports/nearest`

**Parameters**

| Name | Type | | Description |
|---|---|---|---|
| `lat` | number | required | Latitude. |
| `lon` | number | required | Longitude. |
| `radius_km` | number | optional | Beyond this nothing is returned, rather than something absurd. |
| `scheduled` | boolean | optional | Only airports with a scheduled service. |
| `limit` | integer | optional | 1 to 50. |

**Example request**

```bash
curl https://api.diraz.ae/v1/airports/nearest \
  -H "Authorization: Bearer drz_live_…"
```

**Example response**

```json
{
  "data": {
    "airports": [
      {
        "icao": "WIHH",
        "iata": "HLP",
        "name": "Halim Perdanakusuma International Airport",
        "size": "medium",
        "country": "ID",
        "region": "ID-JK",
        "city": "Jakarta",
        "lat": -6.26661,
        "lon": 106.891,
        "elevation_ft": 84,
        "scheduled": true,
        "distance_km": 8.4
      }
    ]
  },
  "meta": {
    "request_id": "req_7Q2fK4mZ"
  }
}
```

## UAE Airports

The UAE slice of the airport directory — DXB, AUH, and every field with an IATA code or a scheduled service.

- Method: `GET`
- Path: `/v1/airports/uae`

**Parameters**

| Name | Type | | Description |
|---|---|---|---|
| `q` | string | optional | Name, city, IATA, or ICAO. An exact code match is returned first. |
| `size` | string | optional | `large`, `medium`, or `small`. |
| `scheduled` | boolean | optional | Only airports an airline actually schedules a service to. |
| `limit` | integer | optional | 1 to 100. |

**Example request**

```bash
curl https://api.diraz.ae/v1/airports/uae \
  -H "Authorization: Bearer drz_live_…"
```

**Example response**

```json
{
  "data": {
    "total_indexed": 8931,
    "airports": [
      {
        "icao": "OMDB",
        "iata": "DXB",
        "name": "Dubai International Airport",
        "size": "large",
        "country": "AE",
        "region": "AE-DU",
        "city": "Dubai",
        "lat": 25.2528,
        "lon": 55.3644,
        "elevation_ft": 62,
        "scheduled": true
      }
    ]
  },
  "meta": {
    "request_id": "req_7Q2fK4mZ"
  }
}
```