City and place search
Towns and cities (1,000+ people) whose name in any language starts with the query, exact names first, then by population: GeoNames id, name, ASCII name, the alternate name that matched, coordinates, country, region (admin1) and county (admin2), population, elevation, time zone and place type (capital, administrative seat, populated place...). Filter by country, region, type, GeoNames feature code and population range, and sort by relevance, population or name. Pass next_page back as page; null on the last page. Data: GeoNames (CC BY 4.0).
Every response includes credits_used: the credits this call cost.
Parameters
| name | type | description |
|---|---|---|
qrequired | string | Name or its beginning (3+ characters for prefix search), any language: paris, münchen, 東京. Example: springfield |
country | string | ISO country code or English name. Example: US |
region | string | Region (admin1) code or name, e.g. IL or Illinois. Also accepted as admin1. |
type | any | capital | admin | any (default), capital (national capitals) or admin (capitals and administrative seats). |
min_population | integer | Only places with at least this many people. |
max_population | integer | Only places with at most this many people. |
feature_code | string | GeoNames place codes, comma-separated, e.g. PPLC (capital), PPLA (region seat), PPLA2, PPL (populated place), PPLX (section of a city). |
sort | relevance | population | name | Order: relevance (default: exact names first, then by population), population (largest first) or name (A-Z). |
limit | integer | Results per page (default 10, max 100). |
page | integer | Page (default 1). |
Every endpoint also takes fresh, raw, fields (see lean responses and caching).
Example
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(); Response
A JSON object with the fields described above, plus raw (the source's own data), cached, fetched_at and credits_used. Errors return {"success": false, "error": "…"} with the HTTP status (see errors). A lookup that ran but found nothing (404) costs the price above; refused calls and errors on our side are free (what's charged).