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.

For other groupings, such as the European Union, Latin America and the Caribbean, the World Bank income groups or OECD members, use a public collection: one ID that stands for the whole group in any country filter, e.g. filter=authorships.countries:col_LV29j8URoX for the EU27.

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.