v1.0

Welcome to LocalityAPI

The world's location data in one clean API. Access cities, towns, villages, streets, POIs, postal codes, timezones and administrative regions across 249 countries.

32.5M+ Places

Cities, towns, villages, streets and POIs worldwide.

528M+ Addresses

Verified government addresses across 10+ countries.

249 Countries

Complete global coverage including territories.

<20ms Cached

Lightning-fast responses optimized for real-time use.

99.9% Uptime

Enterprise-grade reliability.

96% Cheaper

Massive price advantage versus Google's APIs.

Base URL

All API requests should be made to the following base URL:

plaintext

https://api.localityapi.com/v1

Authentication

All requests require an API key passed as X-API-Key header:

bash

curl "https://api.localityapi.com/v1/search?q=Dubai" -H "X-API-Key: lapi_your_key"

Quick Example

Here's a quick example searching for Dubai:

Request

bash

curl "https://api.localityapi.com/v1/search?q=Dubai&country=AE" -H "X-API-Key: lapi_your_key"

Response

json

{
  "results": [
    {
      "id": 292223,
      "name": "Dubai",
      "country": "AE",
      "admin1": "Dubai",
      "lat": 25.07725,
      "lng": 55.30927,
      "timezone": "Asia/Dubai",
      "population": 3790000,
      "type": "city"
    }
  ],
  "count": 1,
  "query_ms": 12
}

19 Endpoints

Jump straight to the full documentation for any endpoint:

GETSearch/v1/searchGETAutocomplete/v1/autocompleteGETCities/v1/citiesGETNearby/v1/nearbyGETAddress Search/v1/addressGETPostal Lookup/v1/postalGETReverse Geocoding/v1/reverseGETAddress Validator/v1/validateGETIP Geolocation/v1/ipGETTimezone/v1/timezoneGETSunrise & Sunset/v1/sunGETDistance/v1/distanceGETStreets/v1/streetsGETCountries List/v1/countriesGETCountry Details/v1/country/{code}GETAll Countries/v1/countries/allGETAdmin Regions/v1/adminGETPoints of Interest/v1/poisPOSTBatch API/v1/batch

Address Data Coverage

Our address database covers 528M+ verified government addresses across 10+ countries including US (231M), Brazil (65M), Mexico (35M), Australia (28M), France (25M), Canada (18M), Spain (15M), Japan (13M), Netherlands (9M), Belgium (8M) and more. Coverage is expanding regularly.

API Reference

Full documentation for all 19 endpoints. Every request requires the X-API-Key header.

Search

Search for cities, towns and villages by name with fuzzy matching. Supports country filtering and population sorting.

GEThttps://api.localityapi.com/v1/search

Parameters

Parameter	Type	Required	Description
`q`	string	Required	Search query (place name).
`country`	string	Optional	Filter by ISO 3166-1 alpha-2 country code.
`limit`	integer	Optional	Max results to return (1-100).(Default: `10`)
`min_population`	integer	Optional	Only return places above this population.

Example Request

bash

curl "https://api.localityapi.com/v1/search?q=Dubai&country=AE" \
  -H "X-API-Key: lapi_your_key"

Example Response

json

{
  "results": [
    {
      "id": 292223,
      "name": "Dubai",
      "country": "AE",
      "admin1": "Dubai",
      "lat": 25.07725,
      "lng": 55.30927,
      "timezone": "Asia/Dubai",
      "population": 3790000,
      "type": "city"
    }
  ],
  "count": 1,
  "query_ms": 12
}

Autocomplete

Fast typeahead suggestions optimized for real-time input. Returns lightweight results in under 20ms, ideal for search-as-you-type widgets.

GEThttps://api.localityapi.com/v1/autocomplete

Parameters

Parameter	Type	Required	Description
`q`	string	Required	Partial query string (min 2 characters).
`country`	string	Optional	Filter by ISO alpha-2 country code.
`limit`	integer	Optional	Max suggestions to return (1-20).(Default: `5`)

Example Request

bash

curl "https://api.localityapi.com/v1/autocomplete?q=San+Fr" \
  -H "X-API-Key: lapi_your_key"

Example Response

json

{
  "results": [
    {
      "id": 5391959,
      "name": "San Francisco",
      "admin1": "California",
      "country": "US",
      "label": "San Francisco, California, US"
    },
    {
      "id": 3493146,
      "name": "San Fernando",
      "admin1": "Buenos Aires",
      "country": "AR",
      "label": "San Fernando, Buenos Aires, AR"
    }
  ],
  "count": 2,
  "query_ms": 6
}

Cities

Filter and list cities by country, administrative region, population range and type. Useful for building drop-downs and browsing datasets.

GEThttps://api.localityapi.com/v1/cities

Parameters

Parameter	Type	Required	Description
`country`	string	Required	ISO alpha-2 country code.
`admin1`	string	Optional	Filter by first-level admin region name.
`min_population`	integer	Optional	Minimum population.
`max_population`	integer	Optional	Maximum population.
`limit`	integer	Optional	Max results (1-100).(Default: `25`)

Example Request

bash

curl "https://api.localityapi.com/v1/cities?country=JP&min_population=1000000" \
  -H "X-API-Key: lapi_your_key"

Example Response

json

{
  "results": [
    {
      "id": 1850147,
      "name": "Tokyo",
      "country": "JP",
      "admin1": "Tokyo",
      "lat": 35.6895,
      "lng": 139.69171,
      "population": 8336599,
      "type": "city"
    }
  ],
  "count": 1,
  "query_ms": 9
}

Nearby

Find all cities within a given radius of a coordinate using a spatial query. Results are sorted by distance from the origin point.

GEThttps://api.localityapi.com/v1/nearby

Parameters

Parameter	Type	Required	Description
`lat`	number	Required	Latitude of the origin point.
`lng`	number	Required	Longitude of the origin point.
`radius`	number	Optional	Search radius in kilometers (max 500).(Default: `50`)
`limit`	integer	Optional	Max results (1-100).(Default: `10`)

Example Request

bash

curl "https://api.localityapi.com/v1/nearby?lat=40.7128&lng=-74.0060&radius=25" \
  -H "X-API-Key: lapi_your_key"

Example Response

json

{
  "results": [
    {
      "id": 5128581,
      "name": "New York",
      "country": "US",
      "admin1": "New York",
      "lat": 40.71427,
      "lng": -74.00597,
      "population": 8175133,
      "distance_km": 0.2
    }
  ],
  "count": 1,
  "query_ms": 11
}

Address Search

Search 528M+ verified government addresses by street and city. Returns full address details with coordinates across 10+ countries.

GEThttps://api.localityapi.com/v1/address

Parameters

Parameter	Type	Required	Description
`q`	string	Required	Address query (street and number).
`city`	string	Optional	Filter by city name.
`country`	string	Optional	ISO alpha-2 country code.
`limit`	integer	Optional	Max results (1-50).(Default: `10`)

Example Request

bash

curl "https://api.localityapi.com/v1/address?q=1600+Amphitheatre+Parkway&city=Mountain+View" \
  -H "X-API-Key: lapi_your_key"

Example Response

json

{
  "results": [
    {
      "id": "us-ca-9381726",
      "number": "1600",
      "street": "Amphitheatre Parkway",
      "city": "Mountain View",
      "admin1": "California",
      "postal_code": "94043",
      "country": "US",
      "lat": 37.42206,
      "lng": -122.08409
    }
  ],
  "count": 1,
  "query_ms": 14
}

Postal Lookup

Resolve any postal or ZIP code to its location, coordinates and administrative region.

GEThttps://api.localityapi.com/v1/postal

Parameters

Parameter	Type	Required	Description
`code`	string	Required	Postal or ZIP code to look up.
`country`	string	Required	ISO alpha-2 country code.

Example Request

bash

curl "https://api.localityapi.com/v1/postal?code=94043&country=US" \
  -H "X-API-Key: lapi_your_key"

Example Response

json

{
  "results": [
    {
      "postal_code": "94043",
      "place": "Mountain View",
      "admin1": "California",
      "admin2": "Santa Clara",
      "country": "US",
      "lat": 37.4192,
      "lng": -122.0574
    }
  ],
  "count": 1,
  "query_ms": 7
}

Reverse Geocoding

Convert latitude/longitude coordinates to the nearest city, administrative region and country.

GEThttps://api.localityapi.com/v1/reverse

Parameters

Parameter	Type	Required	Description
`lat`	number	Required	Latitude.
`lng`	number	Required	Longitude.

Example Request

bash

curl "https://api.localityapi.com/v1/reverse?lat=48.8584&lng=2.2945" \
  -H "X-API-Key: lapi_your_key"

Example Response

json

{
  "results": [
    {
      "id": 2988507,
      "name": "Paris",
      "country": "FR",
      "admin1": "Île-de-France",
      "lat": 48.85341,
      "lng": 2.3488,
      "distance_km": 0.6
    }
  ],
  "count": 1,
  "query_ms": 8
}

Address Validator

Validate a city, postal code and country combination. Returns whether the combination exists and the normalized canonical values.

GEThttps://api.localityapi.com/v1/validate

Parameters

Parameter	Type	Required	Description
`city`	string	Required	City name to validate.
`postal_code`	string	Optional	Postal code to validate against the city.
`country`	string	Required	ISO alpha-2 country code.

Example Request

bash

curl "https://api.localityapi.com/v1/validate?city=Berlin&postal_code=10115&country=DE" \
  -H "X-API-Key: lapi_your_key"

Example Response

json

{
  "valid": true,
  "normalized": {
    "city": "Berlin",
    "postal_code": "10115",
    "admin1": "Berlin",
    "country": "DE"
  },
  "query_ms": 5
}

IP Geolocation

Look up the location, timezone, currency and ISP information for any IP address. Omit the ip parameter to detect the caller's IP automatically.

GEThttps://api.localityapi.com/v1/ip

Parameters

Parameter	Type	Required	Description
`ip`	string	Optional	IP address to look up. Defaults to the request IP.

Example Request

bash

curl "https://api.localityapi.com/v1/ip?ip=8.8.8.8" \
  -H "X-API-Key: lapi_your_key"

Example Response

json

{
  "ip": "8.8.8.8",
  "city": "Mountain View",
  "admin1": "California",
  "country": "US",
  "lat": 37.386,
  "lng": -122.0838,
  "timezone": "America/Los_Angeles",
  "currency": "USD",
  "isp": "Google LLC",
  "query_ms": 10
}

Timezone

Get the current time, UTC offset and daylight saving status for any coordinate or city.

GEThttps://api.localityapi.com/v1/timezone

Parameters

Parameter	Type	Required	Description
`lat`	number	Required	Latitude.
`lng`	number	Required	Longitude.

Example Request

bash

curl "https://api.localityapi.com/v1/timezone?lat=35.6895&lng=139.6917" \
  -H "X-API-Key: lapi_your_key"

Example Response

json

{
  "timezone": "Asia/Tokyo",
  "utc_offset": "+09:00",
  "is_dst": false,
  "local_time": "2026-06-07T21:42:11+09:00",
  "query_ms": 4
}

Sunrise & Sunset

Get sunrise, sunset, dawn, dusk and solar noon times for any location and date.

GEThttps://api.localityapi.com/v1/sun

Parameters

Parameter	Type	Required	Description
`lat`	number	Required	Latitude.
`lng`	number	Required	Longitude.
`date`	string	Optional	Date in YYYY-MM-DD format. Defaults to today.

Example Request

bash

curl "https://api.localityapi.com/v1/sun?lat=51.5074&lng=-0.1278&date=2026-06-21" \
  -H "X-API-Key: lapi_your_key"

Example Response

json

{
  "date": "2026-06-21",
  "sunrise": "04:43:00",
  "sunset": "21:21:00",
  "dawn": "03:57:00",
  "dusk": "22:07:00",
  "solar_noon": "13:02:00",
  "day_length": "16:38:00",
  "query_ms": 3
}

Distance

Calculate the great-circle distance between two coordinates. Returns the distance in kilometers and miles.

GEThttps://api.localityapi.com/v1/distance

Parameters

Parameter	Type	Required	Description
`from_lat`	number	Required	Origin latitude.
`from_lng`	number	Required	Origin longitude.
`to_lat`	number	Required	Destination latitude.
`to_lng`	number	Required	Destination longitude.

Example Request

bash

curl "https://api.localityapi.com/v1/distance?from_lat=40.7128&from_lng=-74.0060&to_lat=34.0522&to_lng=-118.2437" \
  -H "X-API-Key: lapi_your_key"

Example Response

json

{
  "distance_km": 3935.75,
  "distance_mi": 2445.56,
  "bearing": 273.6,
  "query_ms": 2
}

Streets

Search across 52M+ named streets worldwide. Filter by city and country to narrow results.

GEThttps://api.localityapi.com/v1/streets

Parameters

Parameter	Type	Required	Description
`q`	string	Required	Street name query.
`city`	string	Optional	Filter by city name.
`country`	string	Optional	ISO alpha-2 country code.
`limit`	integer	Optional	Max results (1-50).(Default: `10`)

Example Request

bash

curl "https://api.localityapi.com/v1/streets?q=Baker+Street&city=London" \
  -H "X-API-Key: lapi_your_key"

Example Response

json

{
  "results": [
    {
      "id": "gb-lon-44821",
      "name": "Baker Street",
      "city": "London",
      "admin1": "England",
      "country": "GB",
      "lat": 51.5207,
      "lng": -0.1571
    }
  ],
  "count": 1,
  "query_ms": 13
}

Countries List

List all countries with their ISO codes and basic metadata. Lightweight call for populating selectors.

GEThttps://api.localityapi.com/v1/countries

Parameters

Parameter	Type	Required	Description
`limit`	integer	Optional	Max results (1-249).(Default: `50`)

Example Request

bash

curl "https://api.localityapi.com/v1/countries" \
  -H "X-API-Key: lapi_your_key"

Example Response

json

{
  "results": [
    { "iso2": "US", "iso3": "USA", "name": "United States" },
    { "iso2": "GB", "iso3": "GBR", "name": "United Kingdom" },
    { "iso2": "JP", "iso3": "JPN", "name": "Japan" }
  ],
  "count": 3,
  "query_ms": 4
}

Country Details

Get full metadata for a single country including currency, languages, calling code, capital and flag.

GEThttps://api.localityapi.com/v1/country/{code}

Parameters

Parameter	Type	Required	Description
`code`	string	Required	ISO alpha-2 country code (path parameter).

Example Request

bash

curl "https://api.localityapi.com/v1/country/FR" \
  -H "X-API-Key: lapi_your_key"

Example Response

json

{
  "iso2": "FR",
  "iso3": "FRA",
  "name": "France",
  "capital": "Paris",
  "currency": "EUR",
  "currency_symbol": "€",
  "phone_code": "+33",
  "languages": ["fr"],
  "flag": "🇫🇷",
  "is_eu": true,
  "population": 67391582,
  "query_ms": 3
}

All Countries

Retrieve all 249 countries with full metadata in a single call. Ideal for caching the full dataset client-side.

GEThttps://api.localityapi.com/v1/countries/all

This endpoint takes no parameters.

Example Request

bash

curl "https://api.localityapi.com/v1/countries/all" \
  -H "X-API-Key: lapi_your_key"

Example Response

json

{
  "results": [
    {
      "iso2": "AD",
      "iso3": "AND",
      "name": "Andorra",
      "capital": "Andorra la Vella",
      "currency": "EUR",
      "phone_code": "+376",
      "is_eu": false
    }
  ],
  "count": 249,
  "query_ms": 18
}

Admin Regions

List administrative divisions such as states, provinces and districts for a given country.

GEThttps://api.localityapi.com/v1/admin

Parameters

Parameter	Type	Required	Description
`country`	string	Required	ISO alpha-2 country code.
`level`	integer	Optional	Admin level (1 = states/provinces, 2 = counties/districts).(Default: `1`)

Example Request

bash

curl "https://api.localityapi.com/v1/admin?country=US&level=1" \
  -H "X-API-Key: lapi_your_key"

Example Response

json

{
  "results": [
    { "name": "California", "code": "US-CA", "country": "US", "level": 1 },
    { "name": "Texas", "code": "US-TX", "country": "US", "level": 1 }
  ],
  "count": 2,
  "query_ms": 6
}

Points of Interest

Search for points of interest such as restaurants, hotels, hospitals and schools near a coordinate, filtered by category.

GEThttps://api.localityapi.com/v1/pois

Parameters

Parameter	Type	Required	Description
`lat`	number	Required	Latitude of the search center.
`lng`	number	Required	Longitude of the search center.
`category`	string	Optional	POI category (e.g. restaurant, hotel, hospital).
`radius`	number	Optional	Search radius in kilometers (max 50).(Default: `5`)
`limit`	integer	Optional	Max results (1-100).(Default: `20`)

Example Request

bash

curl "https://api.localityapi.com/v1/pois?lat=48.8584&lng=2.2945&category=restaurant" \
  -H "X-API-Key: lapi_your_key"

Example Response

json

{
  "results": [
    {
      "id": "poi-fr-77213",
      "name": "Le Jules Verne",
      "category": "restaurant",
      "lat": 48.8578,
      "lng": 2.2945,
      "distance_km": 0.1
    }
  ],
  "count": 1,
  "query_ms": 12
}

Batch API

Execute up to 100 requests in a single call. Send an array of operations and receive a matching array of results.

POSThttps://api.localityapi.com/v1/batch

Parameters

Parameter	Type	Required	Description
`requests`	array	Required	Array of request objects (max 100), each with an endpoint and params.

Example Request

bash

curl -X POST "https://api.localityapi.com/v1/batch" \
  -H "X-API-Key: lapi_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      { "endpoint": "/search", "params": { "q": "Dubai" } },
      { "endpoint": "/timezone", "params": { "lat": 35.68, "lng": 139.69 } }
    ]
  }'

Example Response

json

{
  "results": [
    { "status": 200, "body": { "results": [{ "name": "Dubai" }], "count": 1 } },
    { "status": 200, "body": { "timezone": "Asia/Tokyo", "utc_offset": "+09:00" } }
  ],
  "count": 2,
  "query_ms": 21
}

Next Steps

Set up authentication →Follow the quick start guide →Explore the API reference →