# Countries API — GeoSearch

> The GeoSearch Countries 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/countries

Country data and regions within countries

## List countries

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

Returns a paginated list of countries with optional filtering and sorting.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| lang | string | optional | ISO 639-1 language code for localized names (e.g., de, fr, ja) |
| continent | string | optional | Filter by continent code (AF, AN, AS, EU, NA, OC, SA) |
| iso_code | string | optional | Filter by ISO alpha-2 codes (comma-separated) |
| 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 and direction. Allowed: name, population, area_sq_km. Prefix with - for descending. |

### Code samples

#### curl

```bash
curl -H "X-API-Key: YOUR_KEY" \
  "https://geosearch.dev/v1/countries?continent=EU&limit=10"
```

#### 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"}})
countries, _, err := client.CountriesAPI.ListCountries(ctx).Continent("EU").Limit(10).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:
    countries = geosearch.CountriesApi(client).list_countries(continent="EU", limit=10).data
```

#### TypeScript

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

const api = new CountriesApi(new Configuration({ apiKey: "YOUR_KEY" }));
const countries = (await api.listCountries({ continent: "EU", limit: 10 })).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" }
countries = GeoSearch::CountriesApi.new.list_countries(continent: "EU", limit: 10).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");
$countries = (new GeoSearch\Api\CountriesApi(null, $cfg))->listCountries(null, "EU");
// lang, continent shown — the remaining 7 parameters are positional and optional
```

### Response

```json
{
  "data": [
    {
      "id": 1,
      "iso_code": "US",
      "iso3_code": "USA",
      "name": "United States",
      "capital": "Washington",
      "population": 331002651,
      "continent_code": "NA",
      "flag_emoji": "🇺🇸"
    }
  ],
  "meta": {
    "next_cursor": "eyJpZCI6MjV9",
    "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 country by ISO code

`GET /v1/countries/{code}` · Quota cost: 1 unit

Returns a single country by its ISO alpha-2 code.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| code | string | required | ISO alpha-2 country code |
| 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/countries/US
```

#### 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"}})
country, _, err := client.CountriesAPI.GetCountry(ctx, "US").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:
    country = geosearch.CountriesApi(client).get_country("US").data
```

#### TypeScript

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

const api = new CountriesApi(new Configuration({ apiKey: "YOUR_KEY" }));
const country = (await api.getCountry({ code: "US" })).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" }
country = GeoSearch::CountriesApi.new.get_country("US").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");
$country = (new GeoSearch\Api\CountriesApi(null, $cfg))->getCountry("US")->getData();
```

### Response

```json
{
  "data": {
    "id": 1,
    "geoname_id": 6252001,
    "iso_code": "US",
    "iso3_code": "USA",
    "iso_numeric": 840,
    "fips_code": "US",
    "name": "United States",
    "capital": "Washington",
    "area_sq_km": 9833520,
    "population": 331002651,
    "continent_code": "NA",
    "tld": ".us",
    "currency_code": "USD",
    "currency_name": "Dollar",
    "phone": "1",
    "postal_code_format": "#####-####",
    "postal_code_regex": "^\\d{5}(-\\d{4})?$",
    "languages": [
      "en-US",
      "es-US"
    ],
    "neighbours": [
      "CA",
      "MX"
    ],
    "latitude": 39.76,
    "longitude": -98.5,
    "flag_emoji": "🇺🇸",
    "geometry": {
      "type": "MultiPolygon",
      "coordinates": [
        [
          [
            [
              -124.7,
              48.4
            ],
            [
              -124.6,
              48.4
            ],
            [
              -124.6,
              48.3
            ],
            [
              -124.7,
              48.4
            ]
          ]
        ]
      ]
    }
  }
}
```

### 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 |

## List regions in a country

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

Returns a paginated list of regions (administrative divisions) within a country.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| code | string | required | ISO alpha-2 country code |
| 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/countries/US/regions
```

#### 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.CountriesAPI.ListCountryRegions(ctx, "US").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.CountriesApi(client).list_country_regions("US").data
```

#### TypeScript

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

const api = new CountriesApi(new Configuration({ apiKey: "YOUR_KEY" }));
const regions = (await api.listCountryRegions({ code: "US" })).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::CountriesApi.new.list_country_regions("US").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\CountriesApi(null, $cfg))->listCountryRegions("US")->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
              ]
            ]
          ]
        ]
      }
    }
  ],
  "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 |
| 429 | rate_limit_exceeded | Per-second throttle exceeded |
| 429 | quota_exceeded | Monthly quota exhausted |

## List neighboring countries

`GET /v1/countries/{code}/neighbors` · Quota cost: 1 unit

Returns countries that share a border with the specified country.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| code | string | required | ISO alpha-2 country code |
| 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/countries/DE/neighbors"
```

#### 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"}})
neighbors, _, err := client.CountriesAPI.CountryNeighbors(ctx, "DE").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:
    neighbors = geosearch.CountriesApi(client).country_neighbors("DE").data
```

#### TypeScript

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

const api = new CountriesApi(new Configuration({ apiKey: "YOUR_KEY" }));
const neighbors = (await api.countryNeighbors({ code: "DE" })).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" }
neighbors = GeoSearch::CountriesApi.new.country_neighbors("DE").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");
$neighbors = (new GeoSearch\Api\CountriesApi(null, $cfg))->countryNeighbors("DE")->getData();
```

### Response

```json
{
  "data": [
    {
      "id": 1,
      "geoname_id": 6252001,
      "iso_code": "US",
      "iso3_code": "USA",
      "iso_numeric": 840,
      "fips_code": "US",
      "name": "United States",
      "capital": "Washington",
      "area_sq_km": 9833520,
      "population": 331002651,
      "continent_code": "NA",
      "tld": ".us",
      "currency_code": "USD",
      "currency_name": "Dollar",
      "phone": "1",
      "postal_code_format": "#####-####",
      "postal_code_regex": "^\\d{5}(-\\d{4})?$",
      "languages": [
        "en-US",
        "es-US"
      ],
      "neighbours": [
        "CA",
        "MX"
      ],
      "latitude": 39.76,
      "longitude": -98.5,
      "flag_emoji": "🇺🇸",
      "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 |
|--------|------|------|
| 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 |