Documentation

Backend Data API

Bearer-authenticated GET endpoints to list countries and subdivisions from your server (same private API key as validation)

Use these endpoints when your backend needs the same country and subdivision lists that power the widget. Authentication uses your private API key exactly like the Backend Validation API. Geolocation-based preselection is not applied on this surface.

Data API features

Bearer private API key (same credential family as validation)
Multi-language names via Accept-Language and related headers
Same core fields you use in forms (country/subdivision codes + names), returned for server-side use

API Endpoints

GET listings for countries and subdivisions using your private Bearer token.

Countries listing

Returns a JSON array of country objects. Response includes X-Selected-Language.

Requirements for API to Work:

This example uses the following configuration:

Required

Authentication

Include your private API key as a Bearer token: Authorization: Bearer YOUR_PRIVATE_KEY. Base URL: https://api.countriesdb.com.

REQUIRED

All

Optional headers

Accept-Language

Preferred language for ICU display names.

OPTIONAL

All

X-Forced-Language

Force a specific language (overrides browser preferences).

OPTIONAL

All

X-Default-Language

Fallback language when the preferred language cannot be resolved.

OPTIONAL

All

Optional query parameters

Query parameters

country_name_source controls how the name field is generated: default (ICU display name, translated) or iso (ISO short name, English-only).

OPTIONAL

All

Response fields returned:

The API returns the following fields in each item:

iso_alpha_2

String. Country code (ISO 3166-1 alpha-2).

All

name

String. Display name in the selected language.

All

iso_alpha_3

String. Country code (ISO 3166-1 alpha-3).

All

iso_numeric

String. Country code (ISO 3166-1 numeric, zero-padded to 3 digits).

All

details

Object or null. When present: { independent: boolean, status: string }.

All

updated_at

String. Last update timestamp (ISO 8601).

All

is_subdivision_of

Object or null. When present: { parent_country_code: string, subdivision_code: string }.

All

Example

Query parameters

All optional for GET /api/data/countries:

Optional

country_name_sourcedefault (default) or iso for ISO short country names.

Bash · cURL

curl -s "https://api.countriesdb.com/api/data/countries" \
  -H "Authorization: Bearer $COUNTRIESDB_PRIVATE_KEY" \
  -H "Accept: application/json" \
  -H "Accept-Language: en"

Response

Success response

HTTP/1.1 200 OK
X-Selected-Language: en
Content-Type: application/json

[
  {
    "iso_alpha_2": "US",
    "name": "United States",
    "iso_alpha_3": "USA",
    "iso_numeric": "840",
    "details": {
      "independent": true,
      "status": "officially-assigned"
    },
    "updated_at": "2026-01-01T00:00:00.000000Z",
    "is_subdivision_of": null
    // ... more countries
  }
]

Subdivisions listing

Returns a JSON array of subdivision objects for the given ISO 3166-1 alpha-2 country code. Empty array when the subscription plan does not include subdivision access.

Requirements for API to Work:

This example uses the following configuration:

Required

Path parameter

{country} - two-letter country code (e.g. US).

REQUIRED

All

Optional headers

Accept-Language

Preferred language for official subdivision names and type names when available.

OPTIONAL

All

X-Forced-Language

Force a specific language (overrides browser preferences).

OPTIONAL

All

X-Default-Language

Fallback language when the preferred language cannot be resolved.

OPTIONAL

All

Optional query parameters

prefer_official

When extended translations are available, prefer_official=1 switches to official ISO subdivisions. See widget option docs.

OPTIONAL

All

prefer_local_variant

Prefer local variant names when available. Applies to official ISO subdivisions and is ignored when extended translations are active. See widget option docs.

OPTIONAL

All

subdivision_romanization_preference

Comma-separated preference list (e.g. un,bgn,default). Applies to official ISO subdivisions and is ignored when extended translations are active. See widget option docs.

OPTIONAL

All

Response fields returned:

The API returns the following fields in each item:

code

String. Subdivision code (ISO 3166-2).

All

name

String. Subdivision display name in the selected language.

All

type

String or null. Subdivision type name (e.g. "State"). Null when extended translations are active (type names are only returned for official ISO subdivisions).

All

updated_at

String. Last update timestamp (ISO 8601).

All

related_country_code

String or null. Present for redirect entries that point to another country.

All

related_subdivision_code

String or null. Present for redirect entries that point to another subdivision code.

All

is_subdivision_of

Object or null. When present: { parent_country_code: string, subdivision_code: string }.

All

Example

Bash · cURL

curl -s "https://api.countriesdb.com/api/data/countries/US/subdivisions?prefer_official=1" \
  -H "Authorization: Bearer $COUNTRIESDB_PRIVATE_KEY" \
  -H "Accept: application/json" \
  -H "Accept-Language: en"

Response

Success response

HTTP/1.1 200 OK
X-Selected-Language: en

[
  {
    "code": "US-CA",
    "name": "California",
    "type": "State",
    "updated_at": "2026-01-01T00:00:00.000000Z",
    "related_country_code": null,
    "related_subdivision_code": null,
    "is_subdivision_of": null
    // ... more subdivisions
  }
]