# World Cities API
> Search a database of 33,000+ cities worldwide (population 15,000+) from GeoNames. Find cities by name, country and minimum population, look up a city by id, or find all cities near a coordinate (radius search). Each city includes coordinates, region, population, timezone and elevation — ideal for autocompletes, location pickers, store locators and geo dashboards.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/cities-api/..."
```

## Pricing
- **Free** (Free) — 5,000 calls/Mo, 3 req/s
- **Starter** ($7/Mo) — 150,000 calls/Mo, 12 req/s
- **Pro** ($19/Mo) — 1,250,000 calls/Mo, 40 req/s
- **Mega** ($52/Mo) — 8,000,000 calls/Mo, 120 req/s

## Endpoints

### Cities

#### `GET /v1/city` — A single city by GeoNames id

**Parameters:**
- `id` (query, required, string) — GeoNames id Example: `2950159`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/cities-api/v1/city?id=2950159"
```

**Response:**
```json
{
    "data": {
        "id": 2950159,
        "name": "Berlin",
        "ascii": "Berlin",
        "admin1": "16",
        "country": "DE",
        "latitude": 52.52437,
        "timezone": "Europe/Berlin",
        "longitude": 13.41053,
        "population": 3426354,
        "elevation_m": 74,
        "country_name": "Germany"
    },
    "meta": {
        "timestamp": "2026-05-30T23:56:39.891Z",
        "request_id": "71c5bd5a-cebc-42f8-8e94-599102c13cf2"
    },
    "status": "ok",
    "message": "City retrieved",
    "success": true
}
```

#### `GET /v1/nearby` — Cities near a coordinate (radius search)

**Parameters:**
- `lat` (query, required, string) — Latitude (-90..90) Example: `48.8566`
- `lon` (query, required, string) — Longitude (-180..180) Example: `2.3522`
- `radius_km` (query, optional, string) — Search radius in km (1-2000, default 100) Example: `50`
- `min_population` (query, optional, string) — Minimum population filter Example: `0`
- `limit` (query, optional, string) — Max results (1-100, default 20) Example: `20`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/cities-api/v1/nearby?lat=48.8566&lon=2.3522&radius_km=50&min_population=0&limit=20"
```

**Response:**
```json
{
    "data": {
        "count": 20,
        "center": {
            "lat": 48.8566,
            "lon": 2.3522
        },
        "results": [
            {
                "id": 3013131,
                "name": "Paris 04 Hôtel-de-Ville",
                "ascii": "Paris 04 Hotel-de-Ville",
                "admin1": "11",
                "country": "FR",
                "latitude": 48.8601,
                "timezone": "Europe/Paris",
                "longitude": 2.3507,
                "population": 27332,
                "distance_km": 0.4,
                "elevation_m": null,
                "country_name": "France"
            },
            {
                "id": 2988507,
                "name": "Paris",
                "ascii": "Paris",
                "admin1": "11",
                "country": "FR",
                "latitude": 48.85341,
                "timezone": "Europe/Paris",
                "longitude": 2.3488,
                "population": 2138551,
                "distance_km": 0.43,
                "elevation_m": null,
                "country_name": "France"
            },
            {
                "id": 6269531,
                "name": "Paris 01 Louvre",
                "ascii": "Paris 01 Louvre",
                "admin1": "11",
                "country": "FR",
                "latitude": 48.8592,
                "timezone": "Europe/Paris",
                "longitude": 2.3417,
                "population": 15114,
                "distance_km": 0.82,
     
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/search` — Search cities by name, country and population

**Parameters:**
- `q` (query, optional, string) — City name (substring match) Example: `berlin`
- `country` (query, optional, string) — Filter by ISO-2 country code Example: `DE`
- `min_population` (query, optional, string) — Minimum population Example: `100000`
- `limit` (query, optional, string) — Results per page (1-100, default 20) Example: `20`
- `offset` (query, optional, string) — Pagination offset Example: `0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/cities-api/v1/search?q=berlin&country=DE&min_population=100000&limit=20&offset=0"
```

**Response:**
```json
{
    "data": {
        "count": 1,
        "limit": 20,
        "total": 1,
        "offset": 0,
        "filters": {
            "q": "berlin",
            "country": "DE",
            "min_population": 100000
        },
        "results": [
            {
                "id": 2950159,
                "name": "Berlin",
                "ascii": "Berlin",
                "admin1": "16",
                "country": "DE",
                "latitude": 52.52437,
                "timezone": "Europe/Berlin",
                "longitude": 13.41053,
                "population": 3426354,
                "elevation_m": 74,
                "country_name": "Germany"
            }
        ]
    },
    "meta": {
        "timestamp": "2026-05-30T23:56:40.051Z",
        "request_id": "338e1c46-04ab-4127-9791-6d9630439f55"
    },
    "status": "ok",
    "message": "Search completed",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Dataset totals & largest cities

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/cities-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "total": 33744,
        "fields": [
            "id",
            "name",
            "ascii",
            "country",
            "country_name",
            "admin1",
            "latitude",
            "longitude",
            "population",
            "timezone",
            "elevation_m"
        ],
        "source": "GeoNames (cities with population ≥ 15,000)",
        "largest": [
            {
                "name": "Shanghai",
                "country": "CN",
                "population": 24874500
            },
            {
                "name": "Beijing",
                "country": "CN",
                "population": 18960744
            },
            {
                "name": "Shenzhen",
                "country": "CN",
                "population": 17494398
            },
            {
                "name": "Guangzhou",
                "country": "CN",
                "population": 16096724
            },
            {
                "name": "Kinshasa",
                "country": "CD",
                "population": 16000000
            }
        ],
        "countries": 244
    },
    "meta": {
        "timestamp": "2026-05-30T23:56:40.126Z",
        "request_id": "8104c41e-acc4-478f-bb55-2f036f521847"
    },
    "status": "ok",
    "message": "Meta retrieved",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/cities-api
OpenAPI spec: https://www.oanor.com/api/cities-api/openapi.json