# Country Subdivisions API
> Look up the administrative subdivisions of any country — 5,300+ states, provinces, regions and districts across 229 countries, with ISO 3166-2 codes. Search by name, country or type, fetch all subdivisions of a country (perfect for address-form dropdowns), or resolve an ISO 3166-2 code like US-CA to its name, type and coordinates. Bundled, fast and always available.

## 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/regions-api/..."
```

## Pricing
- **Free** (Free) — 2,000 calls/Mo, 2 req/s
- **Starter** ($5/Mo) — 40,000 calls/Mo, 8 req/s
- **Pro** ($15/Mo) — 300,000 calls/Mo, 20 req/s
- **Mega** ($42/Mo) — 2,500,000 calls/Mo, 40 req/s

## Endpoints

### Subdivisions

#### `GET /v1/by-country` — All subdivisions of one country

**Parameters:**
- `country` (query, required, string) — ISO-2 country code Example: `US`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/regions-api/v1/by-country?country=US"
```

**Response:**
```json
{
    "data": {
        "count": 60,
        "country": "US",
        "country_name": "United States",
        "subdivisions": [
            {
                "id": 1456,
                "code": "AL",
                "name": "Alabama",
                "type": "state",
                "latitude": 33.25888,
                "iso3166_2": "US-AL",
                "longitude": -86.82953,
                "country_code": "US",
                "country_name": "United States"
            },
            {
                "id": 1400,
                "code": "AK",
                "name": "Alaska",
                "type": "state",
                "latitude": 64.44596,
                "iso3166_2": "US-AK",
                "longitude": -149.68091,
                "country_code": "US",
                "country_name": "United States"
            },
            {
                "id": 1424,
                "code": "AS",
                "name": "American Samoa",
                "type": "outlying area",
                "latitude": -14.29712,
                "iso3166_2": "US-AS",
                "longitude": -170.71315,
                "country_code": "US",
                "country_name": "United States"
            },
            {
                "id": 1434,
                "code": "AZ",
                "name": "Arizona",
                "type": "state",
                "latitude": 34.39534,
                "iso3166_2": "US-AZ",
                "longitude": -111.76327,
                "country_c
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/search` — Search subdivisions by name, country and type

**Parameters:**
- `q` (query, optional, string) — Subdivision name (substring) Example: `bavaria`
- `country` (query, optional, string) — Filter by ISO-2 country code Example: `DE`
- `type` (query, optional, string) — Type, e.g. state, province, region, district
- `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/regions-api/v1/search?q=bavaria&country=DE&limit=20&offset=0"
```

**Response:**
```json
{
    "data": {
        "count": 1,
        "limit": 20,
        "total": 1,
        "offset": 0,
        "filters": {
            "q": "bavaria",
            "type": null,
            "country": "DE"
        },
        "results": [
            {
                "id": 3009,
                "code": "BY",
                "name": "Bavaria",
                "type": "land",
                "latitude": 48.94676,
                "iso3166_2": "DE-BY",
                "longitude": 11.40387,
                "country_code": "DE",
                "country_name": "Germany"
            }
        ]
    },
    "meta": {
        "timestamp": "2026-05-31T01:20:52.377Z",
        "request_id": "565276fc-c96c-4ea7-9084-21b0d4a90c0a"
    },
    "status": "ok",
    "message": "Search completed",
    "success": true
}
```

#### `GET /v1/subdivision` — A single subdivision by ISO 3166-2 code or id

**Parameters:**
- `code` (query, optional, string) — ISO 3166-2 code, e.g. US-CA Example: `US-CA`
- `id` (query, optional, string) — Dataset id (alternative to code)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/regions-api/v1/subdivision?code=US-CA"
```

**Response:**
```json
{
    "data": {
        "id": 1416,
        "code": "CA",
        "name": "California",
        "type": "state",
        "latitude": 36.70146,
        "iso3166_2": "US-CA",
        "longitude": -118.756,
        "country_code": "US",
        "country_name": "United States"
    },
    "meta": {
        "timestamp": "2026-05-31T01:20:52.450Z",
        "request_id": "18ce2759-2fdf-4e32-a013-c64c9cf1d29c"
    },
    "status": "ok",
    "message": "Subdivision retrieved",
    "success": true
}
```

### Countries

#### `GET /v1/countries` — Countries with subdivision counts

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

**Response:**
```json
{
    "data": {
        "count": 229,
        "countries": [
            {
                "country_code": "GB",
                "country_name": "United Kingdom",
                "subdivisions": 221
            },
            {
                "country_code": "SI",
                "country_name": "Slovenia",
                "subdivisions": 212
            },
            {
                "country_code": "UG",
                "country_name": "Uganda",
                "subdivisions": 139
            },
            {
                "country_code": "IT",
                "country_name": "Italy",
                "subdivisions": 126
            },
            {
                "country_code": "FR",
                "country_name": "France",
                "subdivisions": 124
            },
            {
                "country_code": "PH",
                "country_name": "Philippines",
                "subdivisions": 99
            },
            {
                "country_code": "EE",
                "country_name": "Estonia",
                "subdivisions": 94
            },
            {
                "country_code": "CZ",
                "country_name": "Czech Republic",
                "subdivisions": 90
            },
            {
                "country_code": "MA",
                "country_name": "Morocco",
                "subdivisions": 87
            },
            {
                "country_code": "RU",
                "country_name": "Russia",
                "sub
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Totals, types & source

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

**Response:**
```json
{
    "data": {
        "total": 5308,
        "types": [
            "administered area",
            "administration",
            "administrative atoll",
            "administrative precinct",
            "administrative region",
            "administrative territory",
            "arctic region",
            "area",
            "atoll",
            "autonomous city",
            "autonomous community",
            "autonomous district",
            "autonomous municipality",
            "autonomous province",
            "autonomous region",
            "autonomous republic",
            "autonomous sector",
            "autonomous territorial unit",
            "borough",
            "canton",
            "capital city",
            "capital district",
            "capital territory",
            "chain",
            "city",
            "city municipality",
            "city with county rights",
            "commune",
            "council area",
            "country",
            "county",
            "decentralized regional entity",
            "department",
            "dependency",
            "district",
            "district municipality",
            "districts under republic administration",
            "division",
            "economic prefecture",
            "emirate",
            "entity",
            "european collectivity",
            "federal capital territory",
            "federal dependency",
            "federal district",
            "federal territor
…(truncated, see openapi.json for full schema)
```


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