Geo Data API

Turn place names and postal codes into coordinates, find nearby towns, and look up time zones and country facts.

The API.SH Geo Data API geocodes at place level: search towns and cities by name in any language and get coordinates, region, county, population, elevation and time zone, or go the other way and list the places nearest a point. It also looks up postal codes in about 120 countries, returns the time zone and local time of any point or place, measures the distance and bearing between two places, and lists every country with codes, currency, calling code and languages. Data comes from GeoNames.

Get a free API key Try it in the playground

9 endpoints
from $1 / 1,000 calls
1,000 free credits / month
failed calls free

City and place search

GET https://api.api.sh/geo/v1/cities

{ "success": true }

1 credit · $1 per 1,000 calls

What you can build with the Geo Data API

Place-name geocoding

Turn a city or town name typed in any language into coordinates, region, county and country, filtered by country, population or place type.

/cities /city

Reverse geocoding to the nearest town

Give a latitude and longitude and get the towns and cities within a radius, nearest first, or the nearest large city with min_population.

/nearby

Postal code lookup and validation

Resolve a postal code to its place, region, county and coordinates, with full codes for the UK, Canada and the Netherlands and prefix matches for partial codes.

/postal-code /postal-code-countries

Time zones and local time

Get the IANA time zone, UTC offset, DST status and current local time for coordinates, a place name or a postal code, for scheduling across regions.

/timezone

Country reference data and distances

Fill country pickers with ISO codes, currency, calling code, postal code format and neighbors, and compute great-circle distance and bearing between two places.

/countries /country /distance

Geo Data data you get

Field names from real responses. Numbers come parsed, URLs absolute, dates in ISO 8601.

Geo Data API endpoints and prices

Every Geo Data endpoint costs 1 credit per call: credits are $1 per 1,000 on a monthly plan, $2 pay-as-you-go. Pricing

Search and discovery1

City and place search

/geo/v1/cities

$1 · $2 PAYG

1 credit

Posts and media2

Postal code lookup /geo/v1/postal-code	$1 · $2 PAYG 1 credit
Countries with postal code data /geo/v1/postal-code-countries	$1 · $2 PAYG 1 credit

Products, listings and places3

Place by GeoNames id /geo/v1/city	$1 · $2 PAYG 1 credit
Distance between two places /geo/v1/distance	$1 · $2 PAYG 1 credit
Places near a point (reverse geocoding) /geo/v1/nearby	$1 · $2 PAYG 1 credit

More data3

Countries list /geo/v1/countries	$1 · $2 PAYG 1 credit
Country details /geo/v1/country	$1 · $2 PAYG 1 credit
Time zone and local time /geo/v1/timezone	$1 · $2 PAYG 1 credit

Call the Geo Data API

City and place search: GET https://api.api.sh/geo/v1/cities

curl "https://api.api.sh/geo/v1/cities?q=springfield" \
  -H "x-api-key: $APISH_KEY"

import os, requests

res = requests.get(
    "https://api.api.sh/geo/v1/cities",
    params={"q": "springfield"},
    headers={"x-api-key": os.environ["APISH_KEY"]},
    timeout=120,
)
res.raise_for_status()
data = res.json()

const url = new URL("https://api.api.sh/geo/v1/cities");
url.searchParams.set("q", "springfield");

const res = await fetch(url, { headers: { "x-api-key": process.env.APISH_KEY } });
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const data = await res.json();

# Google Sheets (API.SH add-on)
=APISH("/geo/v1/cities", "q", "springfield")

# Zapier, Make, n8n (verified node): pick the API.SH app,
# choose "Geo Data" and "City and place search".

# AI agents (Claude, ChatGPT, Cursor): add the
# API.SH MCP server https://api.sh/mcp

Create a free accountConfirm your email and get 1,000 free credits every month. No card needed.
Create an API keyOne key works for all 483 platforms.
Send the requestJSON back in one call. Add output=csv or output=ndjson for files.

Why API.SH for Geo Data data

Public data only: no Geo Data login, cookies or account needed
One key and one response shape for Geo Data and 482 other platforms
Built and maintained by API.SH, not third-party publishers
Pay per call; errors on our side cost nothing
Live status for every endpoint

API.SH vs the official Geo Data API

This API is built on GeoNames (CC BY 4.0), which also offers its own free web services with an account. For street-level address geocoding (house numbers), the Google, Mapbox or US Census geocoders are the right tools: API.SH geocodes towns, cities and postal codes, not individual addresses.

Google's Geocoding API needs a billing account and Mapbox, Geoapify and Geocodio meter by request; free options such as Nominatim and Open-Meteo's place search have usage limits. API.SH suits place, postal code and time zone lookups with the same key and JSON shape you use for every other API.SH dataset.

Geo Data API questions

What geo data can I get?+

Place search by name (/geo/v1/cities), one place by GeoNames id (/geo/v1/city), places near a point (/geo/v1/nearby), postal code lookup (/geo/v1/postal-code) and its country list (/geo/v1/postal-code-countries), time zone and local time (/geo/v1/timezone), distance between places (/geo/v1/distance), and country lists and details (/geo/v1/countries, /geo/v1/country).

How much does the Geo Data API cost?+

Every Geo Data endpoint costs 1 credit per call. On a monthly plan 1,000 credits cost $1 (Starter is $50/month for 50,000 credits). Pay-as-you-go is $2 per 1,000 credits, with top-ups from $15 that never expire.

Is there a free geocoding API?+

Yes. Every account gets 1,000 free credits every month. That is 1,000 calls to /geo/v1/cities at 1 credit each. Free geocoders also exist, such as Nominatim, Open-Meteo's place search and the US Census geocoder, each with its own limits and coverage.

Can it geocode street addresses?+

No. It geocodes towns and cities (1,000+ people) and postal codes. For house-number accuracy use a street-address geocoder.

Does it do reverse geocoding?+

Yes, to place level: /geo/v1/nearby returns the towns and cities around a latitude and longitude, nearest first, with distance, region, county and time zone.

Where does the data come from?+

GeoNames, under CC BY 4.0. Place names, populations, postal codes and time zones all come from its datasets.

Do I need keys for the underlying sources?+

No. One API.SH key covers every endpoint here and the rest of API.SH.

How do I get started?+

1. Sign up at api.sh. 2. Copy your API key. 3. Call /geo/v1/cities with q set to a city name. Request examples and every parameter are in the docs at https://api.sh/docs. You can also use the JS or Python SDK, Google Sheets, Zapier, Make, n8n or the MCP server at https://api.sh/mcp.