Country API

Country names, currency, languages, and timezones.

Look up a country by ISO2, ISO3, or its name. us, usa, and united states are the same record, and accents are optional (cote divoire works). Response country is always ISO2. Core gives country identity, continent, currency, calling code, flag, languages and timezones. Paid deep adds the country profile, statistics and regional conventions.

Lookup

GET

api.parseapi.com/country/{code}

Country identity, currency, languages and timezones

Explore

Parameters 3

codestring · path · required: ISO 3166-1 alpha-2 or alpha-3, or a country name (germany)
langstring · query · optional: Display language as one BCP 47 tag, such as fr or zh-Hant. Changes supported display labels only; IDs, codes, native names, facts, parsing and deep access stay unchanged. Omit for the original response. Unsupported regions use the supported language base; unsupported languages or scripts use English. Missing labels retain their source value. Accept-Language is not read automatically. Available on the current API contract; frozen 1.0.0 is unchanged.
deepboolean · query · optional: Country profiles, physical geography, statistics, regional conventions, tax references and alternate identifiers. Included on paid plans.

SDK quickstart

import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.country("us");
console.log(result);

Run on your server with a secret key. Calling from a browser or app?

Example response

{
  "country": "US",
  "name": "United States",
  "name_local": null,
  "continent": "NA",
  "currency": "USD",
  "currency_name": "United States Dollar",
  "currency_symbol": "$",
  "calling_code": "+1",
  "emoji": "🇺🇸",
  "languages": [
    "en"
  ],
  "timezones": [
    "America/Adak",
    "America/Anchorage",
    "America/Boise",
    "America/Chicago",
    // ... 25 more
  ]
}

Response fields

country: ISO2 country code
name: Common name
name_local: Local-language name, null when absent or identical to name
continent: Continent code (NA, EU, AF, AS, OC, SA, AN)
currency: ISO currency code
currency_name: Currency name
currency_symbol: Currency symbol
calling_code: International calling code with plus (+1, +44)
emoji: Flag emoji
languages: ISO 639 language codes. Expand each at /language/{code}
timezones: IANA timezone ids used in the country. The US lists 29

States in a country

Every state or region in that country. Built for address forms and shipping rules.

GET

api.parseapi.com/country/{code}/states

States and regions in a country

Explore

Parameters 2

codestring · path · required: ISO country code
langstring · query · optional: Display language as one BCP 47 tag, such as fr or zh-Hant. Changes supported display labels only; IDs, codes, native names, facts, parsing and deep access stay unchanged. Omit for the original response. Unsupported regions use the supported language base; unsupported languages or scripts use English. Missing labels retain their source value. Accept-Language is not read automatically. Available on the current API contract; frozen 1.0.0 is unchanged.

SDK quickstart

import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.country.states("us");
console.log(result);

Run on your server with a secret key. Calling from a browser or app?

Example response

{
  "country": "US",
  "states": [
    {
      "state": "AL",
      "name": "Alabama",
      "type": "state"
    },
    {
      "state": "AK",
      "name": "Alaska",
      "type": "state"
    },
    {
      "state": "NC",
      "name": "North Carolina",
      "type": "state"
    },
    // ... 57 more
  ]
}

Response fields

country: ISO2 country code
states: Every state or province in the country
states[].state: State or province code
states[].name: State or province name
states[].type: State, province, etc.

Deep

?deep=true Country profiles, physical geography, statistics, regional conventions, tax references and alternate identifiers. Included on paid plans.

Deep examples run with your own key. Check this API’s included units and pricing before running.

SDK quickstart

import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.country("us", { deep: true });
console.log(result);

Run on your server with a secret key. Calling from a browser or app?

Example response

{
  "country": "US",
  "name": "United States",
  "name_local": null,
  "continent": "NA",
  "currency": "USD",
  "currency_name": "United States Dollar",
  "currency_symbol": "$",
  "calling_code": "+1",
  "emoji": "🇺🇸",
  "languages": [
    "en"
  ],
  "timezones": [
    "America/Adak",
    "America/Anchorage",
    "America/Boise",
    "America/Chicago",
    // ... 25 more
  ],
  "deep": {
    "iso3": "USA",
    "numeric": 840,
    "full_name": "United States of America",
    "demonym": "American",
    "capital": "Washington, D.C.",
    "capital_lat": 38.89,
    "capital_lon": -77.05,
    "region": "Americas",
    "subregion": "Northern America",
    "population": 340110988,
    "population_period": null,
    "area": 9629091,
    "land_area": null,
    "water_area": null,
    "coastline": 19924,
    "elevation": 760,
    "lowest_point": {
      "name": "Death Valley",
      "elevation": -86
    },
    "highest_point": {
      "name": "Mount McKinley",
      "elevation": 6190
    },
    "tld": ".us",
    "borders": [
      "CA",
      "MX"
    ],
    "blocs": [
      "G7",
      "NATO",
      "OECD"
    ],
    "week_start": "sunday",
    "units": "imperial",
    "driving_side": "right",
    "plugs": [
      "A",
      "B"
    ],
    "voltage": 120,
    "frequency": 60,
    "emergency": {
      "police": "911",
      "ambulance": "911",
      "fire": "911"
    },
    "postal_format": "#####",
    "postal_regex": "^(?:(\\d{5})(?:[ \\-](\\d{4}))?)$",
    "tax": null,
    "tax_rate": null,
    "tax_id_format": null,
    "tax_id_regex": null,
    "ioc": "USA",
    "fifa": "USA",
    "plate": "USA"
  }
}

Geographic measurements are archived reference values. Land and water area use km², coastline uses kilometers, and mean elevation uses meters above sea level. lowest_point and highest_point each carry a name and elevation. Unknown values are null; zero and negative elevations keep their meaning. Land and water area are null when their published total differs from area.

Deep fields

deep.iso3: Three-letter country code
deep.numeric: UN numeric code
deep.full_name: Official long name
deep.demonym: Demonym
deep.capital: Capital city
deep.capital_lat: Capital latitude (null when there is no capital)
deep.capital_lon: Capital longitude (null when there is no capital)
deep.region: UN region
deep.subregion: UN subregion
deep.population: Population estimate
deep.population_period: Observation year or multi-year period for this population estimate (YYYY or YYYY-YYYY). Null when the record has no verified period or population. Never the import date.
deep.area: Total area in km²
deep.land_area: Published land area in km². Null when unavailable or its published total differs from area
deep.water_area: Published water area in km². Null when unavailable or its published total differs from area
deep.coastline: Published coastline length in kilometers. Zero is known zero; null is unavailable
deep.elevation: Mean elevation in meters above sea level. Null when unavailable
deep.lowest_point: Lowest geographic point, or null when unavailable or ambiguous
deep.lowest_point.name: Published place name. Null when unnamed
deep.lowest_point.elevation: Meters above sea level. Negative values are below sea level
deep.highest_point: Highest geographic point, or null when unavailable or ambiguous
deep.highest_point.name: Published place name. Null when unnamed
deep.highest_point.elevation: Meters above sea level
deep.tld: Top-level domain
deep.borders: Neighboring country ISO2 codes
deep.blocs: Bloc memberships (EU, EEA, SCHENGEN, EUROZONE, SEPA, NATO, and more). Expand each at /bloc/{code}
deep.week_start: First day of the week (monday, sunday, saturday)
deep.units: Measurement system (metric or imperial)
deep.driving_side: left or right
deep.plugs: Power plug types, IEC letters (A through O)
deep.voltage: Residential mains voltage. Null when no single standard exists
deep.frequency: Mains frequency in Hz. Null when the grid is split (Japan runs both 50 and 60)
deep.emergency: Emergency numbers: police, ambulance, fire. Null when not confirmed
deep.postal_format: Postal code mask, # is a digit and A is a letter. Null when the country has no postal codes
deep.postal_regex: Anchored regex matching valid postal codes
deep.tax: National levy name (VAT, GST). Null when unavailable or no national levy applies, like the US
deep.tax_rate: Standard national reference rate in percent: 19 means 19%. Do not add it to a state or ZIP reference
deep.tax_id_format: Tax id example format, 9 is a digit (DE999999999)
deep.tax_id_regex: Anchored tax ID format regex. A match does not establish registration
deep.ioc: Olympic committee code (GER, NED, SUI)
deep.fifa: FIFA code. Null for GB, the home nations are the members
deep.plate: International vehicle plate code (D, UK, CH)

Display language

Pass lang with a language tag such as fr, pt-BR, or zh-Hant. Country name and currency_name; deep.region and deep.subregion when requested. All 250 country records have names in each of the 41 choices. State names use separately sourced translations when available.

Omitting lang preserves the original response. Codes, IDs, numeric facts and native-name fields stay unchanged. Missing translations keep their existing source value; unknown values stay null. A preserved name_local may equal the translated name.

Send a chosen browser preference explicitly, for example { lang: navigator.language } in your JavaScript SDK options. The API does not read Accept-Language automatically. Unsupported regions fall back to their supported base language; unsupported languages or scripts use English. Empty, invalid or repeated tags return 400.

Content-Language identifies languages used in translated display fields and known English fallbacks. This option follows the current API contract. Requests selecting frozen 1.0.0 retain that contract. Select API 2.0.0 to use display language.

GET /country/DE?lang=fr

name: "Allemagne"
name_local: "Deutschland"
country: "DE"

For a country dropdown, request /country?lang=fr, use each returned name as its label and country as its submitted value. These selected fields illustrate the display change.

41 display language choices

Language tag	Language
en	American English
zh-Hans	简体中文
fr	français (France)
de	Deutsch
it	italiano
ja	日本語
ko	한국어
es	español de España
ar	العربية
bg	български
ca	català
hr	hrvatski
cs	čeština
da	dansk
nl	Nederlands
fi	suomi
el	Ελληνικά
he	עברית
hi	हिन्दी
hu	magyar
id	Indonesia
kk	қазақ тілі
ms	Melayu
nb	norsk bokmål
pl	polski
pt	português (Brasil)
ro	română
ru	русский
sk	slovenčina
sv	svenska
th	ไทย
tr	Türkçe
uk	українська
vi	Tiếng Việt
zh-Hant	繁體中文
en-AU	Australian English
en-GB	British English
fr-CA	français canadien
es-419	español latinoamericano
pt-PT	português europeu
zh-Hant-HK	繁體中文（中國香港特別行政區）

Build with Country

All tutorials →

Questions? Email

Country API

Lookup#

States in a country#

Deep#

Display language#

Build with Country

Lookup

States in a country

Deep

Display language