# Regions API — GeoSearch

> The GeoSearch Regions API: 4 endpoints with parameters, quota costs, response bodies and code samples in six languages.

Base URL: https://geosearch.dev · Auth: X-API-Key header on every request.
HTML version: https://geosearch.dev/docs/api/regions

Administrative regions/states/provinces

## List regions

`GET /v1/regions` · Quota cost: 1 unit

Returns a paginated list of regions with optional filtering by country, level, and population.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| lang | string | optional | ISO 639-1 language code for localized names (e.g., de, fr, ja) |
| country | string | optional | Filter by ISO alpha-2 country code |
| level | integer | optional | Filter by administrative level |
| population_min | integer | optional | Minimum population filter |
| population_max | integer | optional | Maximum population filter |
| cursor | string | optional | Pagination cursor from a previous response |
| limit | integer | optional | Number of results per page (1-100, default 25) |
| fields | string | optional | Comma-separated list of fields to include in the response |
| sort | string | optional | Sort field. Allowed: name, population. |

### Code samples

#### curl

```bash
curl -H "X-API-Key: YOUR_KEY" \
  "https://geosearch.dev/v1/regions?country=US&sort=-population"
```

#### Go

```go
// go get github.com/geosearch-dev/geosearch-go
client := geosearch.NewAPIClient(geosearch.NewConfiguration())
ctx := context.WithValue(context.Background(), geosearch.ContextAPIKeys,
    map[string]geosearch.APIKey{"apiKeyAuth": {Key: "YOUR_KEY"}})
regions, _, err := client.RegionsAPI.ListRegions(ctx).Country("US").Sort("-population").Execute()
```

#### Python

```python
# pip install git+https://github.com/geosearch-dev/geosearch-python.git
import geosearch

cfg = geosearch.Configuration(api_key={"apiKeyAuth": "YOUR_KEY"})
with geosearch.ApiClient(cfg) as client:
    regions = geosearch.RegionsApi(client).list_regions(country="US", sort="-population").data
```

#### TypeScript

```typescript
// npm install github:geosearch-dev/geosearch-typescript
import { Configuration, RegionsApi } from "@geosearch/client";

const api = new RegionsApi(new Configuration({ apiKey: "YOUR_KEY" }));
const regions = (await api.listRegions({ country: "US", sort: "-population" })).data;
```

#### Ruby

```ruby
# gem 'geosearch', git: 'https://github.com/geosearch-dev/geosearch-ruby.git'
require "geosearch"

GeoSearch.configure { |c| c.api_key["X-API-Key"] = "YOUR_KEY" }
regions = GeoSearch::RegionsApi.new.list_regions(country: "US", sort: "-population").data
```

#### PHP

```php
// composer config repositories.geosearch vcs https://github.com/geosearch-dev/geosearch-php.git
// composer require geosearch-dev/geosearch-php
$cfg = GeoSearch\Configuration::getDefaultConfiguration()
    ->setApiKey("X-API-Key", "YOUR_KEY");
$regions = (new GeoSearch\Api\RegionsApi(null, $cfg))->listRegions(null, "US");
// lang, country shown — the remaining 7 parameters are positional and optional
```

### Response

```json
{
  "data": [
    {
      "id": 5332921,
      "geoname_id": 5332921,
      "country_code": "US",
      "admin_code": "CA",
      "name": "California",
      "ascii_name": "California",
      "level": 1,
      "parent_geoname_id": 6252001,
      "population": 39538223,
      "latitude": 36.778,
      "longitude": -119.418,
      "country": {
        "iso_code": "US",
        "name": "United States"
      },
      "geometry": {
        "type": "MultiPolygon",
        "coordinates": [
          [
            [
              [
                -124.7,
                48.4
              ],
              [
                -124.6,
                48.4
              ],
              [
                -124.6,
                48.3
              ],
              [
                -124.7,
                48.4
              ]
            ]
          ]
        ]
      }
    }
  ],
  "meta": {
    "next_cursor": "eyJpZCI6MjV9",
    "prev_cursor": "eyJpZCI6MX0",
    "has_next": true,
    "has_prev": false,
    "count": 25
  }
}
```

### Errors

| Status | Code | When |
|--------|------|------|
| 400 | validation_error | Invalid request parameters |
| 401 | authentication_required | No API key was supplied |
| 401 | authentication_failed | The supplied API key is not valid |
| 429 | rate_limit_exceeded | Per-second throttle exceeded |
| 429 | quota_exceeded | Monthly quota exhausted |

## Get region by ID

`GET /v1/regions/{id}` · Quota cost: 1 unit

Returns a single region by its numeric ID.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| id | integer | required | Region ID |
| lang | string | optional | ISO 639-1 language code for localized names (e.g., de, fr, ja) |
| fields | string | optional | Comma-separated list of fields to include in the response |

### Code samples

#### curl

```bash
curl -H "X-API-Key: YOUR_KEY" https://geosearch.dev/v1/regions/5332921
```

#### Go

```go
// go get github.com/geosearch-dev/geosearch-go
client := geosearch.NewAPIClient(geosearch.NewConfiguration())
ctx := context.WithValue(context.Background(), geosearch.ContextAPIKeys,
    map[string]geosearch.APIKey{"apiKeyAuth": {Key: "YOUR_KEY"}})
region, _, err := client.RegionsAPI.GetRegion(ctx, 5332921).Execute()
```

#### Python

```python
# pip install git+https://github.com/geosearch-dev/geosearch-python.git
import geosearch

cfg = geosearch.Configuration(api_key={"apiKeyAuth": "YOUR_KEY"})
with geosearch.ApiClient(cfg) as client:
    region = geosearch.RegionsApi(client).get_region(5332921).data
```

#### TypeScript

```typescript
// npm install github:geosearch-dev/geosearch-typescript
import { Configuration, RegionsApi } from "@geosearch/client";

const api = new RegionsApi(new Configuration({ apiKey: "YOUR_KEY" }));
const region = (await api.getRegion({ id: 5332921 })).data;
```

#### Ruby

```ruby
# gem 'geosearch', git: 'https://github.com/geosearch-dev/geosearch-ruby.git'
require "geosearch"

GeoSearch.configure { |c| c.api_key["X-API-Key"] = "YOUR_KEY" }
region = GeoSearch::RegionsApi.new.get_region(5332921).data
```

#### PHP

```php
// composer config repositories.geosearch vcs https://github.com/geosearch-dev/geosearch-php.git
// composer require geosearch-dev/geosearch-php
$cfg = GeoSearch\Configuration::getDefaultConfiguration()
    ->setApiKey("X-API-Key", "YOUR_KEY");
$region = (new GeoSearch\Api\RegionsApi(null, $cfg))->getRegion(5332921)->getData();
```

### Response

```json
{
  "data": {
    "id": 5332921,
    "geoname_id": 5332921,
    "country_code": "US",
    "admin_code": "CA",
    "name": "California",
    "ascii_name": "California",
    "level": 1,
    "parent_geoname_id": 6252001,
    "population": 39538223,
    "latitude": 36.778,
    "longitude": -119.418,
    "country": {
      "iso_code": "US",
      "name": "United States"
    },
    "geometry": {
      "type": "MultiPolygon",
      "coordinates": [
        [
          [
            [
              -124.7,
              48.4
            ],
            [
              -124.6,
              48.4
            ],
            [
              -124.6,
              48.3
            ],
            [
              -124.7,
              48.4
            ]
          ]
        ]
      ]
    }
  }
}
```

### Errors

| Status | Code | When |
|--------|------|------|
| 400 | validation_error | Invalid request parameters |
| 401 | authentication_required | No API key was supplied |
| 401 | authentication_failed | The supplied API key is not valid |
| 404 | not_found | Resource not found |
| 429 | rate_limit_exceeded | Per-second throttle exceeded |
| 429 | quota_exceeded | Monthly quota exhausted |

## List cities in a region

`GET /v1/regions/{id}/cities` · Quota cost: 1 unit

Returns a paginated list of cities within a specific region.

THIS ENDPOINT AND `/v1/cities?within=` ANSWER DIFFERENT QUESTIONS AND WILL SOMETIMES RETURN DIFFERENT CITIES FOR THE SAME REGION. That is intended, not a bug. This endpoint answers the ADMINISTRATIVE question — which cities are assigned to this region by GeoNames' own admin codes — while `?within=` answers the GEOMETRIC one, which cities fall inside the region's polygon. The two disagree wherever an enclave, an exclave or a blank admin code puts a city's assignment at odds with its location.

Use this endpoint when you want the official assignment; use `/v1/cities?within=` when you want what is physically inside the boundary. This one is charged at the standard 1 unit; `?within=` costs 2.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| id | integer | required | Region ID |
| lang | string | optional | ISO 639-1 language code for localized names (e.g., de, fr, ja) |
| cursor | string | optional | Pagination cursor from a previous response |
| limit | integer | optional | Number of results per page (1-100, default 25) |
| fields | string | optional | Comma-separated list of fields to include in the response |
| sort | string | optional | Sort field. Allowed: name, population. |

### Code samples

#### curl

```bash
curl -H "X-API-Key: YOUR_KEY" https://geosearch.dev/v1/regions/5332921/cities
```

#### Go

```go
// go get github.com/geosearch-dev/geosearch-go
client := geosearch.NewAPIClient(geosearch.NewConfiguration())
ctx := context.WithValue(context.Background(), geosearch.ContextAPIKeys,
    map[string]geosearch.APIKey{"apiKeyAuth": {Key: "YOUR_KEY"}})
cities, _, err := client.RegionsAPI.ListRegionCities(ctx, 5332921).Execute()
```

#### Python

```python
# pip install git+https://github.com/geosearch-dev/geosearch-python.git
import geosearch

cfg = geosearch.Configuration(api_key={"apiKeyAuth": "YOUR_KEY"})
with geosearch.ApiClient(cfg) as client:
    cities = geosearch.RegionsApi(client).list_region_cities(5332921).data
```

#### TypeScript

```typescript
// npm install github:geosearch-dev/geosearch-typescript
import { Configuration, RegionsApi } from "@geosearch/client";

const api = new RegionsApi(new Configuration({ apiKey: "YOUR_KEY" }));
const cities = (await api.listRegionCities({ id: 5332921 })).data;
```

#### Ruby

```ruby
# gem 'geosearch', git: 'https://github.com/geosearch-dev/geosearch-ruby.git'
require "geosearch"

GeoSearch.configure { |c| c.api_key["X-API-Key"] = "YOUR_KEY" }
cities = GeoSearch::RegionsApi.new.list_region_cities(5332921).data
```

#### PHP

```php
// composer config repositories.geosearch vcs https://github.com/geosearch-dev/geosearch-php.git
// composer require geosearch-dev/geosearch-php
$cfg = GeoSearch\Configuration::getDefaultConfiguration()
    ->setApiKey("X-API-Key", "YOUR_KEY");
$cities = (new GeoSearch\Api\RegionsApi(null, $cfg))->listRegionCities(5332921)->getData();
```

### Response

```json
{
  "data": [
    {
      "id": 5391959,
      "geoname_id": 5391959,
      "name": "San Francisco",
      "ascii_name": "San Francisco",
      "country_code": "US",
      "admin1_code": "CA",
      "admin2_code": "075",
      "population": 873965,
      "elevation": 16,
      "timezone": "America/Los_Angeles",
      "latitude": 37.77493,
      "longitude": -122.41942,
      "country": {
        "iso_code": "US",
        "name": "United States"
      },
      "region": {
        "id": 5332921,
        "name": "California",
        "admin_code": "CA"
      }
    }
  ],
  "meta": {
    "next_cursor": "eyJpZCI6MjV9",
    "prev_cursor": "eyJpZCI6MX0",
    "has_next": true,
    "has_prev": false,
    "count": 25
  }
}
```

### Errors

| Status | Code | When |
|--------|------|------|
| 400 | validation_error | Invalid request parameters |
| 401 | authentication_required | No API key was supplied |
| 401 | authentication_failed | The supplied API key is not valid |
| 429 | rate_limit_exceeded | Per-second throttle exceeded |
| 429 | quota_exceeded | Monthly quota exhausted |

## List child cities of a region

`GET /v1/regions/{id}/children` · Quota cost: 1 unit

Returns all cities that are direct children of the specified region in the administrative hierarchy.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| id | integer | required | Region ID |
| lang | string | optional | ISO 639-1 language code for localized names (e.g., de, fr, ja) |
| fields | string | optional | Comma-separated list of fields to include in the response |

### Code samples

#### curl

```bash
curl -H "X-API-Key: YOUR_KEY" \
  "https://geosearch.dev/v1/regions/5332921/children"
```

#### Go

```go
// go get github.com/geosearch-dev/geosearch-go
client := geosearch.NewAPIClient(geosearch.NewConfiguration())
ctx := context.WithValue(context.Background(), geosearch.ContextAPIKeys,
    map[string]geosearch.APIKey{"apiKeyAuth": {Key: "YOUR_KEY"}})
children, _, err := client.RegionsAPI.RegionChildren(ctx, 5332921).Execute()
```

#### Python

```python
# pip install git+https://github.com/geosearch-dev/geosearch-python.git
import geosearch

cfg = geosearch.Configuration(api_key={"apiKeyAuth": "YOUR_KEY"})
with geosearch.ApiClient(cfg) as client:
    children = geosearch.RegionsApi(client).region_children(5332921).data
```

#### TypeScript

```typescript
// npm install github:geosearch-dev/geosearch-typescript
import { Configuration, RegionsApi } from "@geosearch/client";

const api = new RegionsApi(new Configuration({ apiKey: "YOUR_KEY" }));
const children = (await api.regionChildren({ id: 5332921 })).data;
```

#### Ruby

```ruby
# gem 'geosearch', git: 'https://github.com/geosearch-dev/geosearch-ruby.git'
require "geosearch"

GeoSearch.configure { |c| c.api_key["X-API-Key"] = "YOUR_KEY" }
children = GeoSearch::RegionsApi.new.region_children(5332921).data
```

#### PHP

```php
// composer config repositories.geosearch vcs https://github.com/geosearch-dev/geosearch-php.git
// composer require geosearch-dev/geosearch-php
$cfg = GeoSearch\Configuration::getDefaultConfiguration()
    ->setApiKey("X-API-Key", "YOUR_KEY");
$children = (new GeoSearch\Api\RegionsApi(null, $cfg))->regionChildren(5332921)->getData();
```

### Response

```json
{
  "data": [
    {
      "id": 5391959,
      "geoname_id": 5391959,
      "name": "San Francisco",
      "ascii_name": "San Francisco",
      "country_code": "US",
      "admin1_code": "CA",
      "admin2_code": "075",
      "population": 873965,
      "elevation": 16,
      "timezone": "America/Los_Angeles",
      "latitude": 37.77493,
      "longitude": -122.41942,
      "country": {
        "iso_code": "US",
        "name": "United States"
      },
      "region": {
        "id": 5332921,
        "name": "California",
        "admin_code": "CA"
      }
    }
  ],
  "meta": {
    "next_cursor": "eyJpZCI6MjV9",
    "prev_cursor": "eyJpZCI6MX0",
    "has_next": true,
    "has_prev": false,
    "count": 25
  }
}
```

### Errors

| Status | Code | When |
|--------|------|------|
| 401 | authentication_required | No API key was supplied |
| 401 | authentication_failed | The supplied API key is not valid |
| 404 | not_found | Resource not found |
| 429 | rate_limit_exceeded | Per-second throttle exceeded |
| 429 | quota_exceeded | Monthly quota exhausted |