Airpult API

Geocoding

Search for locations by name or look up location details by ID.

Overview

The Geocoding API lets you search for locations worldwide and retrieve location details. It supports fuzzy matching, localized results, and direct ID lookups.

Search for locations by name with optional fuzzy matching.

GET /geocoding/lookup?q={query}

Parameters

Parameter Required Default Description
q Yes — Search query (minimum 2 characters)
language No en Language code for localized results (e.g. de, it, fr)
field No name Search scope. name searches location names only. all searches name, administrative region, and country.
country No — ISO 3166-1 alpha-2 country code to filter results (e.g. AT, CH, US)
limit No 10 Maximum number of results (max 50)

Example Request

GET /geocoding/lookup?q=Zurich&language=en&limit=5

Example Response

{
  "results": [
    {
      "id": "3704415940",
      "name": "Zürich",
      "lat": 47.36667,
      "lon": 8.55,
      "country_code": "CH",
      "country_name": "Switzerland",
      "admin1_name": "Kanton Zürich",
      "timezone": "Europe/Zurich",
      "population": 341730,
      "feature_code": "PPLA"
    }
  ],
  "count": 1
}

Lookup by ID

Retrieve a specific location by its unique ID.

GET /geocoding/lookup?id={location_id}

Parameters

Parameter Required Description
id Yes The location’s unique public ID

Example Request

GET /geocoding/lookup?id=3704415940

Example Response

{
  "id": "3704415940",
  "name": "Zürich",
  "lat": 47.36667,
  "lon": 8.55,
  "country_code": "CH",
  "country_name": "Switzerland",
  "admin1_name": "Kanton Zürich",
  "admin2_name": "Bezirk Zürich",
  "timezone": "Europe/Zurich",
  "population": 341730,
  "elevation": null,
  "feature_code": "PPLA"
}

Response Fields

Field Type Description
id string Unique location identifier
name string Location name (localized when language parameter is set)
lat float Latitude
lon float Longitude
country_code string ISO 3166-1 alpha-2 country code
country_name string Country name
admin1_name string First-level administrative division (e.g. state, canton)
admin2_name string Second-level administrative division (e.g. district, county)
timezone string IANA timezone identifier
population integer Population (may be null)
elevation integer Elevation in meters (may be null)
feature_code string Feature code indicating location type (e.g. PPL for city, PPLA for capital, AIRP for airport)

List Countries

Retrieve a list of all countries.

GET /geocoding/countries

Results are sorted alphabetically by name. Returned in English only.

Example Response

{
  "results": [
    {
      "code": "CH",
      "name": "Switzerland",
      "flag": "🇨🇭",
      "population": 8700000,
      "continent": "EU"
    }
  ],
  "count": 1
}

Country Details

Retrieve details for a single country by its ISO 3166-1 alpha-2 code.

GET /geocoding/countries/{code}

Parameters

Parameter Required Description
code Yes ISO 3166-1 alpha-2 country code (case-insensitive, e.g. CH, at)

Example Request

GET /geocoding/countries/CH

Example Response

{
  "code": "CH",
  "name": "Switzerland",
  "flag": "🇨🇭",
  "population": 8700000,
  "continent": "EU",
  "timezone": "Europe/Zurich",
  "capital": "Bern"
}

Country Response Fields

Field Type Description
code string ISO 3166-1 alpha-2 country code
name string Country name (English)
flag string Flag emoji derived from the ISO code
population integer Country population (may be null)
continent string Continent code (may be null)
timezone string Primary IANA timezone (detail endpoint only, may be null)
capital string Capital city name (detail endpoint only, may be null)

Errors

Status Description
400 Missing required parameter (id or q)
404 Location or country not found
503 Geocoding data not yet loaded

Confirm