API Documentation
JSON endpoints for programmatic access to 36 years of CIA World Factbook data
All API endpoints return JSON. No authentication is required. The base URL is:
https://cia-factbook-archive.fly.dev
FastAPI also provides auto-generated interactive documentation at /docs (Swagger UI) and /redoc (ReDoc). The endpoints below are the public API surface.
/api/years
List all available years with country count and field count per year.
/api/archive/{year}
List all countries in a specific year with ISO codes and entity types.
| Parameter | Type | Description |
|---|---|---|
year | int | Year (1990–2025) |
/api/archive/{year}/{code}
Full country profile for a specific year. Returns all categories and fields.
| Parameter | Type | Description |
|---|---|---|
year | int | Year (1990–2025) |
code | string | ISO Alpha-2 code (e.g. US, CN, RU) |
/api/field/{code}/{field_name}
Time series for a specific field across all available years.
| Parameter | Type | Description |
|---|---|---|
code | string | ISO Alpha-2 code |
field_name | string | Canonical field name (e.g. Population) |
/api/search
Full-text search across all 1,071,213 fields. Supports boolean operators (AND, OR, NOT), phrase matching, and year filtering.
| Parameter | Type | Description |
|---|---|---|
q | string | Search query (required) |
year_start | int | Filter: start year (optional) |
year_end | int | Filter: end year (optional) |
page | int | Page number, 50 results per page (default: 1) |
/api/fields
List all 414 canonical field names with variant counts.
/api/archive/fields/{code}
List all canonical field names available for a specific country (across all years).
| Parameter | Type | Description |
|---|---|---|
code | string | ISO Alpha-2 code |
/api/countries
All 281 master country entities with canonical names, ISO codes, and entity type classification.
/api/countries/{code}
Single country details including all year appearances and category counts.
| Parameter | Type | Description |
|---|---|---|
code | string | ISO Alpha-2 code |
/api/analysis/regions
Summary statistics for all six COCOM regions (population, GDP, military, life expectancy).
/api/analysis/region/{cocom}
Country-level indicators for all nations in a specific COCOM region.
| Parameter | Type | Description |
|---|---|---|
cocom | string | COCOM code (EUCOM, AFRICOM, CENTCOM, INDOPACOM, SOUTHCOM, NORTHCOM) |
/api/analysis/map-data
Choropleth map data for all countries. Returns ISO3 codes, indicator values, and metadata for map rendering.
| Parameter | Type | Description |
|---|---|---|
indicator | string | Indicator key (population, gdp_percap, life_exp, etc.) |
/api/analysis/map-data/{year}
Choropleth data for a specific year and indicator. Used by timeline and map compare features.
| Parameter | Type | Description |
|---|---|---|
year | int | Year (1990–2025) |
indicator | string | Indicator key (query param) |
/api/analysis/timeseries
Parsed numeric time series for a country and indicator across all available years.
| Parameter | Type | Description |
|---|---|---|
code | string | ISO Alpha-2 code |
indicator | string | Indicator key |
/api/analysis/dossier/{code}
Structured intelligence dossier for a country. Returns demographics, economy, military, infrastructure, and strategic assessment data.
| Parameter | Type | Description |
|---|---|---|
code | string | ISO Alpha-2 code |
/api/analysis/comms-data/{year}
Communications infrastructure data for all countries in a given year. Internet users, mobile subscriptions, fixed lines, and broadband.
| Parameter | Type | Description |
|---|---|---|
year | int | Year (1990–2025) |
/api/analysis/rankings
Ranked leaderboard of all sovereign states for any indicator and year.
| Parameter | Type | Description |
|---|---|---|
indicator | string | Indicator key (population, gdp_percap, life_exp, etc.) |
year | int | Year (default: latest) |
/api/analysis/changes
Year-over-year change detection across 6 core indicators. Returns percentage changes with severity classification.
| Parameter | Type | Description |
|---|---|---|
year | int | Comparison year (default: latest) |
indicator | string | Filter by indicator key (optional) |
region | string | Filter by COCOM region (optional) |
/api/analysis/dissolved/{group}
Time series data for all successor states of a dissolved federation.
| Parameter | Type | Description |
|---|---|---|
group | string | Group key: soviet_union, yugoslavia, czechoslovakia |
indicator | string | Indicator key (default: population) |
/export/{code}/{year}/csv
Download all fields for a country-year as a CSV file.
/export/{code}/{year}/xlsx
Download all fields for a country-year as an Excel (.xlsx) file.
/export/bulk/{code}/csv
Bulk export: all years of data for a country as a single CSV file.
/export/bulk/{code}/xlsx
Bulk export: all years of data for a country as a single Excel (.xlsx) file.
The following indicator keys are accepted by analysis endpoints (indicator parameter):
| Key | CIA Factbook Field | Unit |
|---|---|---|
population | Population | Count |
gdp_billions | Real GDP (purchasing power parity) | $B |
gdp_percap | Real GDP per capita | $ |
life_exp | Life expectancy at birth | Years |
mil_pct_gdp | Military expenditures | % GDP |
pop_growth | Population growth rate | % |
birth_rate | Birth rate | /1,000 |
death_rate | Death rate | /1,000 |
internet_pct | Internet users | % |
mobile_per100 | Telephones - mobile cellular | /100 |
unemployment | Unemployment rate | % |
inflation | Inflation rate (consumer prices) | % |
The CIA World Factbook is a work of the United States Government and is in the public domain (17 U.S.C. § 105). This API is provided as-is with no rate limits or authentication. Please be respectful of shared resources. For bulk data access, consider downloading the SQL dumps from the GitHub repository.