The Locations API provides airport suggestions for autocomplete and structured flight search inputs. It allows you to convert user-entered text such as airport names, cities, or IATA codes into normalized airport objects. This endpoint is typically used to power:

Origin and destination autocomplete fields
Airport and city lookup workflows
Flight search preparation
Timezone-aware scheduling and display

Autocomplete

Convert user input into structured airport suggestions.

Structured Data

Retrieve IATA codes, geo coordinates, and timezone metadata.

Flight Search Ready

Use returned airport identifiers for offers and order creation.

Endpoint

GET https://sandbox.travelbase.ai/v1/air/locations

Returns airport suggestions matching a search query.

Query parameters

Parameter	Type	Required	Constraints	Description
`query`	string	Yes	Minimum length: 2	Airport name, city name, or IATA code.
`limit`	integer	No	Range: 1–15 (default: 10)	Maximum number of results returned.

For optimal performance and user experience, debounce autocomplete requests by 200–350ms and only query when the user has entered at least 2 characters.

Example request

cURL
HTTP
JAVASCRIPT

curl -X GET "https://sandbox.travelbase.ai/v1/air/locations?query=jfk&limit=10" \
-H "x-api-key: tb_live_xxxxxxx"

GET /v1/air/locations?query=jfk&limit=10 HTTP/1.1
Host: sandbox.travelbase.ai
x-api-key: tb_live_xxxxxxx

const response = await fetch(
"https://sandbox.travelbase.ai/v1/air/locations?query=jfk&limit=10",
{
    headers: {
    "x-api-key": process.env.TRAVELBASE_API_KEY
}
}
);

const result = await response.json();
console.log(result.data);

Example response

{
    "success": true,
    "message": "Locations fetched successfully.",
    "data": {
        "data": [
            {
                "airports": null,
                "city_name": "Araraquara",
                "iata_city_code": "AQA",
                "iata_country_code": "BR",
                "icao_code": "SBAQ",
                "iata_code": "AQA",
                "latitude": -21.805839,
                "longitude": -48.139741,
                "city": null,
                "time_zone": "America/Sao_Paulo",
                "type": "airport",
                "name": "Araraquara Airport",
                "id": "arp_aqa_br"
            }
        ]
    }
}

Response schema

Root object

Field	Type	Description
`data`	array<Location>	List of airport suggestions matching the query.

Location object

Each object in data[] represents a single airport.

Field	Type	Description
`id`	string	Stable internal identifier for the airport.
`type`	string	Location type. Currently always `airport`.
`iata_code`	string	Airport IATA code (example: `JFK`).
`name`	string	Full airport name.
`city_name`	string	City where the airport is located.
`iata_city_code`	string	IATA metropolitan city code (example: `NYC`).
`iata_country_code`	string	IATA country code (example: `US`).
`latitude`	number	Airport latitude coordinate in decimal degrees.
`longitude`	number	Airport longitude coordinate in decimal degrees.
`time_zone`	string	IANA timezone identifier (example: `America/New_York`).

Example display format

Recommended display format for autocomplete suggestions:

New York (NYC) — John F. Kennedy International Airport (JFK)

This format clearly communicates:

City
Airport name
Airport code

Recommended integration flow

1. User enters text

Capture user input in the origin or destination field.

2. Query Locations API

Call /v1/air/locations with the user’s search query.

3. Display suggestions

Render returned airports in an autocomplete dropdown.

4. Store selected airport

Store the selected airport’s id and iata_code for downstream use.

Best practices

Use airport ID internally

Always store and reference the id field as the primary identifier. IATA codes may overlap or change, but the id remains stable.

Debounce requests

Avoid sending a request on every keystroke. Use a debounce interval of 200–350ms to improve performance and reduce API load.

Limit results

Use the limit parameter to control payload size and improve response time. Example:

GET https://sandbox.travelbase.ai/v1/air/locations?query=lag&limit=5

Handle empty responses

If no matching airports are found, the API returns:

{
  "success": true,
  "message": "Locations retrieved successfully.",
  "data": []
}

Display a helpful UI message such as: No airports found. Try a different search term.

Timezone handling

The time_zone field is returned using the standard IANA timezone database format. Example values:

America/New_York
Europe/London
Africa/Lagos

Use the returned timezone instead of inferring timezone from the client device. This ensures correct time calculations for global flight operations.

Location

Search

Orders

Financial

Platform

Locations

Autocomplete

Structured Data

Flight Search Ready

Endpoint

Query parameters

Example request

Example response

Response schema

Root object

Location object

Example display format

Recommended integration flow

1. User enters text

2. Query Locations API

3. Display suggestions

4. Store selected airport

Best practices

Use airport ID internally

Debounce requests

Limit results

Handle empty responses

Timezone handling

Location

Search

Orders

Financial

Platform

Autocomplete

Structured Data

Flight Search Ready

​Endpoint

​Query parameters

​Example request

​Example response

​Response schema

​Root object

​Location object

​Example display format

​Recommended integration flow

1. User enters text

2. Query Locations API

3. Display suggestions

4. Store selected airport

​Best practices

​Use airport ID internally

​Debounce requests

​Limit results

​Handle empty responses

​Timezone handling

Endpoint

Query parameters

Example request

Example response

Response schema

Root object

Location object

Example display format

Recommended integration flow

Best practices

Use airport ID internally

Debounce requests

Limit results

Handle empty responses

Timezone handling