openapi: 3.1.0
info:
title: REST Countries
description: >-
REST Countries is a free, open-source RESTful API that returns information
about world countries. Each country resource exposes ISO 3166-1 codes (cca2,
cca3, ccn3, cioc), common and official names, native names, translations,
capital cities, regions and subregions, continents, area, population, latitude
and longitude, top level domains, calling codes, currencies, languages,
timezones, demonyms, flags and coats of arms, postal code patterns, FIFA code,
independence and UN membership status, regional bloc affiliations, driving
side, Gini index, start of week, and links to map services. The API is
read-only and unauthenticated; the canonical hosted version runs at
restcountries.com and the source is maintained at github.com/apilayer/restcountries
(community-run, MPL-2.0 licensed).
version: '3.1'
license:
name: Mozilla Public License 2.0
url: https://www.mozilla.org/en-US/MPL/2.0/
contact:
name: REST Countries
url: https://restcountries.com
externalDocs:
description: REST Countries Documentation
url: https://restcountries.com
servers:
- url: https://restcountries.com/v3.1
description: REST Countries v3.1 production
tags:
- name: All
description: Bulk retrieval of every country in the dataset.
- name: Name
description: Lookup countries by common or official name.
- name: Alpha
description: Lookup countries by ISO 3166-1 alpha-2, alpha-3, numeric, or CIOC code.
- name: Currency
description: Lookup countries by ISO 4217 currency code or currency name.
- name: Language
description: Lookup countries by ISO 639 language code or language name.
- name: Capital
description: Lookup countries by capital city.
- name: Region
description: Lookup countries within a UN geographic region.
- name: Subregion
description: Lookup countries within a UN geographic subregion.
- name: Translation
description: Lookup countries by translated name.
- name: Demonym
description: Lookup countries by demonym (citizen designation).
- name: Independent
description: Lookup countries filtered by ISO 3166-1 independence status.
paths:
/all:
get:
operationId: listAllCountries
summary: List All Countries
description: >-
Returns every country in the dataset. As of v3.1, the `fields` query
parameter is required (up to 10 fields); requests without `fields` may
return 400 Bad Request because the unfiltered payload is large.
tags:
- All
parameters:
- $ref: '#/components/parameters/FieldsQuery'
responses:
'200':
description: A list of country resources.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Country'
examples:
ListAllCountries200Example:
summary: Default listAllCountries 200 response
x-microcks-default: true
value:
- name:
common: Germany
official: Federal Republic of Germany
cca2: DE
cca3: DEU
capital:
- Berlin
region: Europe
flags:
png: https://flagcdn.com/w320/de.png
svg: https://flagcdn.com/de.svg
'400':
$ref: '#/components/responses/BadRequest'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/name/{name}:
get:
operationId: getCountriesByName
summary: Get Countries By Name
description: >-
Search countries by common or official name. Partial, case-insensitive
substring matches are returned by default. Set `fullText=true` to
require an exact full-name match.
tags:
- Name
parameters:
- name: name
in: path
required: true
description: Common or official country name (URL-encoded).
schema:
type: string
examples:
united:
value: united
germany:
value: germany
- name: fullText
in: query
required: false
description: When `true`, only an exact full-name match is returned.
schema:
type: boolean
default: false
- $ref: '#/components/parameters/FieldsQuery'
responses:
'200':
description: A list of countries whose name matches the query.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Country'
'404':
$ref: '#/components/responses/NotFound'
/alpha/{code}:
get:
operationId: getCountryByAlphaCode
summary: Get Country By Alpha Code
description: >-
Lookup a country by ISO 3166-1 alpha-2 (cca2), alpha-3 (cca3), numeric
(ccn3), or International Olympic Committee (cioc) code.
tags:
- Alpha
parameters:
- name: code
in: path
required: true
description: ISO 3166-1 alpha-2, alpha-3, numeric, or CIOC code.
schema:
type: string
examples:
usa:
value: usa
de:
value: de
'276':
value: '276'
- $ref: '#/components/parameters/FieldsQuery'
responses:
'200':
description: A list containing a single country resource.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Country'
'404':
$ref: '#/components/responses/NotFound'
/alpha:
get:
operationId: getCountriesByAlphaCodes
summary: Get Countries By Multiple Alpha Codes
description: Batch lookup of countries by a comma-separated list of alpha codes.
tags:
- Alpha
parameters:
- name: codes
in: query
required: true
description: Comma-separated list of ISO 3166-1 codes (alpha-2, alpha-3, numeric, or CIOC).
schema:
type: string
examples:
multiple:
value: 'usa,de,fr,jp'
- $ref: '#/components/parameters/FieldsQuery'
responses:
'200':
description: A list of country resources for the requested codes.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Country'
'404':
$ref: '#/components/responses/NotFound'
/currency/{currency}:
get:
operationId: getCountriesByCurrency
summary: Get Countries By Currency
description: Search countries by ISO 4217 currency code or currency name (e.g. `usd`, `dollar`, `eur`).
tags:
- Currency
parameters:
- name: currency
in: path
required: true
description: ISO 4217 currency code or currency name.
schema:
type: string
examples:
usd:
value: usd
eur:
value: eur
- $ref: '#/components/parameters/FieldsQuery'
responses:
'200':
description: A list of countries that use the requested currency.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Country'
'404':
$ref: '#/components/responses/NotFound'
/lang/{language}:
get:
operationId: getCountriesByLanguage
summary: Get Countries By Language
description: Search countries by ISO 639 language code or language name (e.g. `spanish`, `cym`).
tags:
- Language
parameters:
- name: language
in: path
required: true
description: ISO 639 language code or language name.
schema:
type: string
examples:
spanish:
value: spanish
cym:
value: cym
- $ref: '#/components/parameters/FieldsQuery'
responses:
'200':
description: A list of countries that use the requested language.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Country'
'404':
$ref: '#/components/responses/NotFound'
/capital/{capital}:
get:
operationId: getCountriesByCapital
summary: Get Countries By Capital
description: Search countries by their capital city.
tags:
- Capital
parameters:
- name: capital
in: path
required: true
description: Capital city name.
schema:
type: string
examples:
tallinn:
value: tallinn
- $ref: '#/components/parameters/FieldsQuery'
responses:
'200':
description: A list of countries whose capital matches the query.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Country'
'404':
$ref: '#/components/responses/NotFound'
/region/{region}:
get:
operationId: getCountriesByRegion
summary: Get Countries By Region
description: Filter countries by UN demographic region (e.g. `europe`, `asia`, `africa`, `americas`, `oceania`).
tags:
- Region
parameters:
- name: region
in: path
required: true
description: UN region name.
schema:
type: string
enum:
- africa
- americas
- antarctic
- asia
- europe
- oceania
- $ref: '#/components/parameters/FieldsQuery'
responses:
'200':
description: A list of countries within the region.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Country'
'404':
$ref: '#/components/responses/NotFound'
/subregion/{subregion}:
get:
operationId: getCountriesBySubregion
summary: Get Countries By Subregion
description: Filter countries by UN demographic subregion (e.g. `northern europe`, `southern asia`).
tags:
- Subregion
parameters:
- name: subregion
in: path
required: true
description: UN subregion name.
schema:
type: string
examples:
northern-europe:
value: northern europe
- $ref: '#/components/parameters/FieldsQuery'
responses:
'200':
description: A list of countries within the subregion.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Country'
'404':
$ref: '#/components/responses/NotFound'
/translation/{translation}:
get:
operationId: getCountriesByTranslation
summary: Get Countries By Translation
description: Search countries by translated name in any supported language.
tags:
- Translation
parameters:
- name: translation
in: path
required: true
description: Translated country name.
schema:
type: string
examples:
deutschland:
value: deutschland
- $ref: '#/components/parameters/FieldsQuery'
responses:
'200':
description: A list of countries whose translated name matches the query.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Country'
'404':
$ref: '#/components/responses/NotFound'
/demonym/{demonym}:
get:
operationId: getCountriesByDemonym
summary: Get Countries By Demonym
description: Search countries by the demonym used for their inhabitants (e.g. `french`, `peruvian`).
tags:
- Demonym
parameters:
- name: demonym
in: path
required: true
description: Demonym (citizen designation).
schema:
type: string
examples:
peruvian:
value: peruvian
- $ref: '#/components/parameters/FieldsQuery'
responses:
'200':
description: A list of countries matching the demonym.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Country'
'404':
$ref: '#/components/responses/NotFound'
/independent:
get:
operationId: listIndependentCountries
summary: List Independent Countries
description: Filter countries by ISO 3166-1 independence status.
tags:
- Independent
parameters:
- name: status
in: query
required: false
description: When `true`, returns only independent countries. When `false`, returns only non-independent territories.
schema:
type: boolean
default: true
- $ref: '#/components/parameters/FieldsQuery'
responses:
'200':
description: A list of countries filtered by independence status.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Country'
'400':
$ref: '#/components/responses/BadRequest'
components:
parameters:
FieldsQuery:
name: fields
in: query
required: false
description: >-
Comma-separated list of fields to return on each country. Up to 10
fields may be requested. Required on `/all`.
schema:
type: string
examples:
basic:
value: 'name,capital,region,flags'
responses:
BadRequest:
description: The request was rejected (typically because `fields` was omitted on `/all`).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: No country matched the query.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
Error:
type: object
properties:
status:
type: integer
description: HTTP status code.
message:
type: string
description: Human readable error message.
required:
- status
- message
Name:
type: object
description: Country name, including official and common forms plus per-language native names.
properties:
common:
type: string
description: Common country name in English.
official:
type: string
description: Official country name in English.
nativeName:
type: object
description: Native names keyed by ISO 639-3 language code.
additionalProperties:
type: object
properties:
official:
type: string
common:
type: string
Currency:
type: object
description: Currency descriptor keyed by ISO 4217 code.
properties:
name:
type: string
symbol:
type: string
InternationalDirectDialing:
type: object
description: International calling code descriptor.
properties:
root:
type: string
description: IDD root (e.g. `+1`).
suffixes:
type: array
items:
type: string
description: Country code suffixes appended to the root.
Flags:
type: object
description: Flag image references.
properties:
png:
type: string
format: uri
svg:
type: string
format: uri
alt:
type: string
description: Textual description of the flag for accessibility.
CoatOfArms:
type: object
description: Coat of arms image references.
properties:
png:
type: string
format: uri
svg:
type: string
format: uri
Maps:
type: object
description: Links to external mapping services.
properties:
googleMaps:
type: string
format: uri
openStreetMaps:
type: string
format: uri
Car:
type: object
description: Vehicular registration data.
properties:
signs:
type: array
items:
type: string
description: Distinguishing (oval) vehicle signs.
side:
type: string
enum:
- left
- right
description: Driving side.
CapitalInfo:
type: object
description: Capital city metadata.
properties:
latlng:
type: array
items:
type: number
minItems: 2
maxItems: 2
description: Capital latitude and longitude.
PostalCode:
type: object
description: Postal code format descriptor.
properties:
format:
type: string
description: Human-readable postal code format mask.
regex:
type: string
description: Regular expression validating postal codes.
Demonyms:
type: object
description: Demonyms keyed by language code with gendered variants.
additionalProperties:
type: object
properties:
f:
type: string
m:
type: string
Country:
type: object
description: A country resource as returned by the REST Countries API.
properties:
name:
$ref: '#/components/schemas/Name'
tld:
type: array
items:
type: string
description: Internet top-level domains assigned to the country.
cca2:
type: string
minLength: 2
maxLength: 2
description: ISO 3166-1 alpha-2 code.
ccn3:
type: string
description: ISO 3166-1 numeric (UN M49) code.
cca3:
type: string
minLength: 3
maxLength: 3
description: ISO 3166-1 alpha-3 code.
cioc:
type: string
description: International Olympic Committee code.
independent:
type: boolean
description: ISO 3166-1 independence status.
status:
type: string
description: ISO 3166-1 assignment status (e.g. `officially-assigned`).
unMember:
type: boolean
description: Whether the country is a United Nations member.
currencies:
type: object
description: Currencies keyed by ISO 4217 code.
additionalProperties:
$ref: '#/components/schemas/Currency'
idd:
$ref: '#/components/schemas/InternationalDirectDialing'
capital:
type: array
items:
type: string
description: List of capital cities.
altSpellings:
type: array
items:
type: string
description: Alternate spellings of the country name.
region:
type: string
description: UN demographic region.
subregion:
type: string
description: UN demographic subregion.
languages:
type: object
description: Official languages keyed by ISO 639-3 code.
additionalProperties:
type: string
translations:
type: object
description: Country name translations keyed by ISO 639-3 code.
additionalProperties:
type: object
properties:
official:
type: string
common:
type: string
latlng:
type: array
items:
type: number
minItems: 2
maxItems: 2
description: Country latitude and longitude.
landlocked:
type: boolean
description: Whether the country has no coastline.
borders:
type: array
items:
type: string
description: ISO 3166-1 alpha-3 codes of bordering countries.
area:
type: number
description: Geographic area in square kilometres.
demonyms:
$ref: '#/components/schemas/Demonyms'
flag:
type: string
description: Unicode flag emoji.
maps:
$ref: '#/components/schemas/Maps'
population:
type: integer
description: Estimated population.
gini:
type: object
description: World Bank Gini index keyed by year.
additionalProperties:
type: number
fifa:
type: string
description: FIFA country code.
car:
$ref: '#/components/schemas/Car'
timezones:
type: array
items:
type: string
description: Country timezones in `UTC±HH:MM` form.
continents:
type: array
items:
type: string
description: Continents that contain the country.
flags:
$ref: '#/components/schemas/Flags'
coatOfArms:
$ref: '#/components/schemas/CoatOfArms'
startOfWeek:
type: string
enum:
- monday
- sunday
- saturday
description: First day of the week in the country.
capitalInfo:
$ref: '#/components/schemas/CapitalInfo'
postalCode:
$ref: '#/components/schemas/PostalCode'