Countries

Eg:countries/USCount:247Links:works, institutions

A country is a geographic nation, identified by its ISO 3166-1 alpha-2 code — US for the United States, JP for Japan, BR for Brazil. Countries are a vocabulary: OpenAlex doesn’t decide what a country is, it just attaches a consistent handle to each one so you can filter and group reliably. Country codes show up throughout the graph — on an institution’s country_code, inside a work’s authorships (each author’s affiliation carries the institution’s country), and as the last_known_institutions country of an author. A country’s OpenAlex ID looks like https://openalex.org/countries/US; fetch one at api.openalex.org/countries/US.

About

We don’t build the list — we adopt it. Countries are the ISO 3166-1 standard set of nations, keyed by their two-letter alpha-2 codes. OpenAlex adds live scholarly counts and a few conveniences (continent, Global South flag, name variants) on top of that fixed list. There are 247 countries.

Values

The full list of 247 countries is at api.openalex.org/countries — to pull every one, page through with per_page=200. A sample of the largest by works count:

Attributes

The top-level fields on a country object. Attributes shared with other entities (id, ids, display_name, works_count, cited_by_count, created_date, updated_date) are documented once on Common attributes.

id

String. The OpenAlex ID for this country, e.g. https://openalex.org/countries/US. The final path segment is the ISO alpha-2 code. See Common attributes.

ids

Object. External identifiers for the country: openalex, iso (a link to the ISO 3166 registry entry), wikidata, and wikipedia.

display_name

String. The country’s common English name, e.g. United States. See Common attributes.

country_code

String. The ISO 3166-1 alpha-2 code, e.g. US. This is the value you filter on across the graph. Same as the last segment of id.

alpha_3

String. The ISO 3166-1 alpha-3 code, e.g. USA. Handy for joining OpenAlex country data to datasets keyed on three-letter codes (World Bank, UN, many national statistics). Null for Kosovo (XK), which has no ISO alpha-3 code. Filtering across the graph always uses the alpha-2 country_code.

description

String. A short one-line description of the country, e.g. “country primarily located in North America”.

display_name_alternatives

List. Other names and spellings for the country (USA, America, United States of America, …). Useful for matching free-text mentions.

continent

Object. The continent this country belongs to, as a dehydrated { id, display_name }.

is_global_south

Boolean. True if the country is part of the Global South, a grouping OpenAlex carries for equity-focused analysis.

works_count

Integer. How many works have an authorship affiliated with an institution in this country. See Common attributes.

cited_by_count

Integer. Total citations across those works. See Common attributes.

works_api_url

String. A ready-made Works API URL for every work affiliated with this country (filter=authorships.countries:<CODE>).

authors_api_url

String. A ready-made Authors API URL for authors whose last known institution is in this country (filter=last_known_institutions.country_code:<CODE>).

institutions_api_url

String. A ready-made Institutions API URL for institutions in this country (filter=country_code:<CODE>).

created_date

String. When the country record was added to OpenAlex (YYYY-MM-DD). See Common attributes.

updated_date

String. When the country record last changed. See Common attributes.

In the API

The Countries endpoint is at api.openalex.org/countries. Fetch one by code — /countries/US — or list them all.

Countries are more useful as a filter on other entities than as a list of their own. Filter institutions by country with filter=country_code:us, filter works by author country with filter=authorships.countries:us, and roll up any list by country with group_by=authorships.countries. See Filtering for the full syntax and the endpoints index for every endpoint. Related: continents.