GETAPI key

Place search (autocomplete)

GETapi.navo24.com/v1/geo/search

Forward geocoding and type-ahead over 5.9 million places in 568 languages. Matches names, alternate names and codes (UN/LOCODE, IATA, ICAO, UIC, ESR). Cities rank by size, so the first hit for a city name is the city the user means. The example is "Odesa".

Query parameters

qstringrequired

Free text or a code. Two characters minimum.

kindsstring

Comma-separated place kinds: city, port, airport, rail, logistics, region, country. Omit for all kinds.

ccstring

ISO 3166-1 alpha-2 country filter.

limitinteger

Results, 1 to 50. Default 10.

langstring

Preferred language for names, ISO 639-1.

Response schema

18 fields

Derived from the example response, nested as the JSON is.

dataobject[]

The payload. Everything an endpoint returns sits under this key.

data[]object

idnumber

Stable identifier for the record. On the tracking endpoints this is the container UUID, except on a portfolio summary row, where it is the container number.

kindstring

carrier_event when a carrier filed it, trackingmcp_inference when we derived the step from surrounding events.

namestring

Human-readable name.

country_codestring

ISO 3166-1 alpha-2 country code.

countrystring

Country name.

statestring

Why the field stands where it does: resolved, contract_required, not_published, not_applicable or awaiting_carrier.

latnumber

Latitude.

lngnumber

Longitude.

populationnumber

timezonestring

IANA time zone of the place. Null when we could not resolve the port.

locodestring

UN/LOCODE of the place.

iatastring

IATA code.

geonameidnumber

wikidatastring

featurestring

matched_namestring

took_msnumber

Errors

A failure carries { "ok": false, "error": { "code", "message", "severity" } }. Branch on the code, and log the message.

missing_key401

No Authorization: Bearer *** or X-API-Key header.

invalid_key401

The key was not recognised.

invalid_request400

q is missing or shorter than two characters.

rate_limited429

More than 120 requests in one minute from one IP.

curl 'https://api.navo24.com/v1/geo/search?q=Odesa&kinds=city%2Cport&cc=UA&limit=2&lang=en' \
  -H "Authorization: Bearer tmcp_YOUR_API_KEY"

const res = await fetch("https://api.navo24.com/v1/geo/search?q=Odesa&kinds=city%2Cport&cc=UA&limit=2&lang=en", {
  headers: {
    "Authorization": "Bearer tmcp_YOUR_API_KEY"
  }
});
const data = await res.json();

import requests

res = requests.get(
    "https://api.navo24.com/v1/geo/search?q=Odesa&kinds=city%2Cport&cc=UA&limit=2&lang=en",
    headers={"Authorization": "Bearer tmcp_YOUR_API_KEY"},
)
data = res.json()

Response

{
  "data": [
    {
      "id": 698740,
      "kind": "city",
      "name": "Odesa",
      "country_code": "UA",
      "country": "Ukraine",
      "state": "Odesa",
      "lat": 46.48572,
      "lng": 30.74383,
      "population": 1010537,
      "timezone": "Europe/Kyiv",
      "locode": "UAODS",
      "iata": "ODS",
      "geonameid": 698740,
      "wikidata": "Q1874",
      "feature": "PPLA",
      "matched_name": "Odesa"
    },
    {
      "id": 11361452,
      "kind": "port",
      "name": "Odesa",
      "country_code": "UA",
      "country": "Ukraine",
      "state": "Odesa",
      "lat": 46.48333,
      "lng": 30.73333,
      "timezone": "Europe/Kyiv",
      "geonameid": 11361452,
      "feature": "PRT",
      "matched_name": "Odesa"
    }
  ],
  "took_ms": 21.4
}