Countries API Reference

List countries

GET/v1/countries

Quota cost: 1 unit Try it

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 Go Python TypeScript Ruby PHP

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

// 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()

# 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

// 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;

# 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

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

{
  "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

400 validation_error

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "population_min",
        "issue": "must be a valid integer"
      }
    ],
    "request_id": "req_abc123"
  }
}

401 authentication_required

{
  "error": {
    "code": "authentication_required",
    "message": "API key required. Get one at /signup",
    "request_id": "req_abc123"
  }
}

401 authentication_failed

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API key",
    "request_id": "req_abc123"
  }
}

429 rate_limit_exceeded

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again later.",
    "request_id": "req_abc123"
  }
}

429 quota_exceeded

{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly quota exhausted. You've used 2,000,000 of 2,000,000 requests for the current period, which resets on March 1, 2026. Upgrade for a higher limit.",
    "request_id": "req_abc123",
    "quota": {
      "limit": 2000000,
      "used": 2000000,
      "resets_at": "2026-03-01T00:00:00Z",
      "upgrade_url": "https://geosearch.dev/dashboard/billing"
    }
  }
}

Get country by ISO code

GET/v1/countries/{code}

Quota cost: 1 unit Try it

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 Go Python TypeScript Ruby PHP

curl -H "X-API-Key: YOUR_KEY" https://geosearch.dev/v1/countries/US

// 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()

# 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

// 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;

# 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

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

{
  "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

401 authentication_required

{
  "error": {
    "code": "authentication_required",
    "message": "API key required. Get one at /signup",
    "request_id": "req_abc123"
  }
}

401 authentication_failed

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API key",
    "request_id": "req_abc123"
  }
}

404 not_found

{
  "error": {
    "code": "not_found",
    "message": "The requested resource was not found",
    "request_id": "req_abc123"
  }
}

429 rate_limit_exceeded

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again later.",
    "request_id": "req_abc123"
  }
}

429 quota_exceeded

{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly quota exhausted. You've used 2,000,000 of 2,000,000 requests for the current period, which resets on March 1, 2026. Upgrade for a higher limit.",
    "request_id": "req_abc123",
    "quota": {
      "limit": 2000000,
      "used": 2000000,
      "resets_at": "2026-03-01T00:00:00Z",
      "upgrade_url": "https://geosearch.dev/dashboard/billing"
    }
  }
}

List regions in a country

GET/v1/countries/{code}/regions

Quota cost: 1 unit Try it

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 Go Python TypeScript Ruby PHP

curl -H "X-API-Key: YOUR_KEY" https://geosearch.dev/v1/countries/US/regions

// 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()

# 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

// 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;

# 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

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

{
  "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

401 authentication_required

{
  "error": {
    "code": "authentication_required",
    "message": "API key required. Get one at /signup",
    "request_id": "req_abc123"
  }
}

401 authentication_failed

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API key",
    "request_id": "req_abc123"
  }
}

429 rate_limit_exceeded

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again later.",
    "request_id": "req_abc123"
  }
}

429 quota_exceeded

{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly quota exhausted. You've used 2,000,000 of 2,000,000 requests for the current period, which resets on March 1, 2026. Upgrade for a higher limit.",
    "request_id": "req_abc123",
    "quota": {
      "limit": 2000000,
      "used": 2000000,
      "resets_at": "2026-03-01T00:00:00Z",
      "upgrade_url": "https://geosearch.dev/dashboard/billing"
    }
  }
}

List neighboring countries

GET/v1/countries/{code}/neighbors

Quota cost: 1 unit Try it

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 Go Python TypeScript Ruby PHP

curl -H "X-API-Key: YOUR_KEY" \
  "https://geosearch.dev/v1/countries/DE/neighbors"

// 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()

# 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

// 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;

# 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

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

{
  "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

401 authentication_required

{
  "error": {
    "code": "authentication_required",
    "message": "API key required. Get one at /signup",
    "request_id": "req_abc123"
  }
}

401 authentication_failed

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API key",
    "request_id": "req_abc123"
  }
}

404 not_found

{
  "error": {
    "code": "not_found",
    "message": "The requested resource was not found",
    "request_id": "req_abc123"
  }
}

429 rate_limit_exceeded

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again later.",
    "request_id": "req_abc123"
  }
}

429 quota_exceeded

{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly quota exhausted. You've used 2,000,000 of 2,000,000 requests for the current period, which resets on March 1, 2026. Upgrade for a higher limit.",
    "request_id": "req_abc123",
    "quota": {
      "limit": 2000000,
      "used": 2000000,
      "resets_at": "2026-03-01T00:00:00Z",
      "upgrade_url": "https://geosearch.dev/dashboard/billing"
    }
  }
}