Airports Database & Flight Duration Calculator

# Implement the SharpAPI "Airports Database & Flight Duration Calculator" endpoint

You are adding an integration with SharpAPI's Airports Database & Flight Duration Calculator API to this codebase. This brief is an alternative to the official SharpAPI SDKs (PHP/Laravel, JavaScript/Node, Python, Flutter, .NET): it describes everything needed to call the API directly over HTTP. If the project already uses a SharpAPI SDK, use the SDK instead.

## What it does

Discover an extensive, advanced database of nearly 30,000 airports and calculate precise flight durations with the Airports Database & Flight Duration API. Seamlessly accesses detailed airport information and journey times using flexible filters and comprehensive endpoints. **Key Features:** - **Extensive Airport Database:** Access information on almost 30,000 airports worldwide, including ICAO, IATA, LID codes, airport names, city names, subdivisions, countries, time zones, elevations, and geographical coordinates. - **Advanced Filtering:** Efficiently browse and filter airport data using ICAO codes, IATA codes, LID codes, city names, and airport names to find exactly what you need. - **Flight Duration Calculations:** Utilize the Flight Length endpoint to calculate the total journey duration between any two airports. Provide parameters such as departure and arrival airport codes, dates, and times to get accurate travel times. - **Detailed Responses:** Get comprehensive data in JSON format, including detailed airport information and human-readable flight duration summaries. > **FlightDuration.Online** was built using this SharpAPI endpoint as an example of its capabilities. > > 👉 **Try it live:** [https://flightduration.online/](https://flightduration.online/) >

## Authentication and base URL

- Base URL: `https://sharpapi.com/api/v1`
- Send `Authorization: Bearer <API key>`, `Accept: application/json` and a `User-Agent` that names your app on every request.
- Read the API key from configuration or an environment variable (for example `SHARPAPI_API_KEY`). Never hard-code or commit it. The key is in the SharpAPI dashboard: https://sharpapi.com/dashboard

## Endpoints

### `GET https://sharpapi.com/api/v1/airports`
Airports List
- query parameter `per_page`, string, e.g. `""`
- query parameter `country`, string, e.g. `""`
- query parameter `timezone`, string, e.g. `""`
- query parameter `name`, string, e.g. `""`
- query parameter `city`, string, e.g. `""`
- query parameter `iata_assigned`, string, e.g. `""`
- query parameter `icao_assigned`, string, e.g. `""`
- query parameter `lid_assigned`, string, e.g. `""`

### `GET https://sharpapi.com/api/v1/airports/{uuid}`
Airport Details (by UUID)
- path parameter `uuid` (required), string, e.g. `"1ef26425-ec74-6a2c-ae57-2e42679870c4"`

### `GET https://sharpapi.com/api/v1/airports/iata/{iata}`
Airport Details (by IATA)
- path parameter `iata` (required), string, e.g. `"SIN"`

### `GET https://sharpapi.com/api/v1/airports/icao/{icao}`
Airport Details (by ICAO)
- path parameter `icao` (required), string, e.g. `"ZBTJ"`

### `GET https://sharpapi.com/api/v1/airports/lid/{lid}`
Airport Details (by LID)
- path parameter `lid` (required), string, e.g. `"00AL"`

### `GET https://sharpapi.com/api/v1/airports/flight_duration/{departureCodeType}/{departureCode}/{departureDate}/{departureTime}/{arrivalCodeType}/{arrivalCode}/{arrivalDate}/{arrivalTime}`
Flight Duration
- path parameter `departureCodeType` (required), string, e.g. `"IATA"`
- path parameter `departureCode` (required), string, e.g. `"SIN"`
- path parameter `departureDate` (required), string, e.g. `"2024-06-27"`
- path parameter `departureTime` (required), string, e.g. `"01:40"`
- path parameter `arrivalCodeType` (required), string, e.g. `"IATA"`
- path parameter `arrivalCode` (required), string, e.g. `"DXB"`
- path parameter `arrivalDate` (required), string, e.g. `"2024-06-27"`
- path parameter `arrivalTime` (required), string, e.g. `"12:10"`

## Example response

```json
{
    "data": [
        {
            "id": "1ef266de-5a6c-67d6-86a1-06bb2780ed98",
            "icao": "00AA",
            "iata": "",
            "lid": "00AA",
            "name": "Aero B Ranch Airport",
            "city": "Leoti",
            "subdivision": "Kansas",
            "country": "US",
            "timezone": "America/Chicago",
            "elevation": 3435,
            "latitude": 38.7,
            "longitude": -101.47
        },
        {
            "id": "1ef266de-5a8e-6f02-ba5c-06bb2780ed98",
            "icao": "00AK",
            "iata": "",
            "lid": "00AK",
            "name": "Lowell Field",
            "city": "Anchor Point",
            "subdivision": "Alaska",
            "country": "US",
            "timezone": "America/Anchorage",
            "elevation": 252,
            "latitude": 59.95,
            "longitude": -151.69
        },
        {
            "id": "1ef266de-5a93-63ae-b408-06bb2780ed98",
            "icao": "00AL",
            "iata": "",
            "lid": "00AL",
            "name": "Epps Airpark",
            "city": "Harvest",
            "subdivision": "Alabama",
            "country": "US",
            "timezone": "America/Chicago",
            "elevation": 820,
            "latitude": 34.86,
            "longitude": -86.77
        }
    ],
    "links": {
        "first": "https://sharpapi.com/api/v1/airports?page=1",
        "last": "https://sharpapi.com/api/v1/airports?page=1128",
        "prev": null,
        "next": "https://sharpapi.com/api/v1/airports?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1128,
        "links": [
            {
                "url": null,
                "label": "&laquo; Previous",
                "active": false
            },
            {
                "url": "https://sharpapi.com/api/v1/airports?page=1",
                "label": "1",
                "active": true
            },
            {
                "url": "https://sharpapi.com/api/v1/airports?page=2",
                "label": "2",
                "active": false
            }
        ],
        "path": "https://sharpapi.com/api/v1/airports",
        "per_page": 25,
        "to": 25,
        "total": 28186
    }
}
```

## Errors to handle

- `401` 401 Unathorized: "Unauthorized"
- `404` 404 Not found: "Resource Not Found"
- `422` 422Unprocessable Content: "Parameters validation error"
- `500` 500 Server Error: "Server Error"
- `429`: rate limited. Wait the `Retry-After` seconds and retry, at most 3 times.
- `402`: the word quota is used up. Do not retry; tell the user to add credits or upgrade.
- `5xx`: retry later with backoff.

## Implementation rules
- Wrap the calls in one small client or service with a typed method for this endpoint, and map the result to a typed object or DTO.
- Track `X-RateLimit-Limit` and `X-RateLimit-Remaining`. When the remaining count drops to 3 or below, slow down.
- `GET https://sharpapi.com/api/v1/ping` checks connectivity and `GET https://sharpapi.com/api/v1/quota` returns the remaining words: use them for a health check.
- Write tests with the HTTP layer mocked: success, `422` validation error, `429` retry, and a missing API key.
- Full API reference: https://sharpapi.com/documentation