API Documentation
Complete reference for World Factbook & Partner Apps
https://www.worldfactbook.co
JSON
API Overview
The World Factbook API provides programmatic access to comprehensive country data, economic indicators, historical timelines, and all partner application data. Use a single API key to access everything.
Quick Start: Register for an API key, include it in the X-API-Key header, and make requests to any endpoint.
Available Data
Authentication
All API requests require authentication via an API key passed in the request header.
X-API-Key: wfb_your_api_key_here
Example Request
curl "https://www.worldfactbook.co/api/countries.php" \ -H "X-API-Key: wfb_your_api_key_here"
JavaScript
const response = await fetch('https://www.worldfactbook.co/api/countries.php', {
headers: { 'X-API-Key': 'wfb_your_api_key_here' }
});
const data = await response.json();
Rate Limits: Default is 100 requests per hour. Exceeding this returns a 429 Too Many Requests response. Contact admin for higher limits.
Get Your API Key
Countries API
/api/countries.php
List all countries with basic info (name, slug, region, flag URL)
| Parameter | Type | Description |
|---|---|---|
| search | string | Filter by name |
| region | string | Filter by region slug |
| type | string | Filter by entity type (country, territory, etc.) |
/api/countries.php?slug={slug}
Get detailed country data including all fields, categories, and rankings
| Parameter | Type | Description |
|---|---|---|
| slug | string | Country URL slug (e.g., united-states) |
| edition | int | Edition year (defaults to primary edition) |
/api/suggest.php?q={query}
Autocomplete country name suggestions (max 10)
| Parameter | Type | Description |
|---|---|---|
| q | string | Search query (min 2 chars) |
Example Response
{
"status": "ok",
"count": 261,
"countries": [
{
"id": 1,
"name": "United States",
"slug": "united-states",
"gec_code": "us",
"region": "north-america",
"flag_url": "/assets/flags/us.png"
}, ...
]
}
Timeline API
/api/timeline.phpGet historical data across editions for a country. First request lists available fields; add the field parameter for actual timeline data.
| Parameter | Type | Description |
|---|---|---|
| country | string | GEC code (e.g., us, gm, ch) |
| field | string | Field name (e.g., Population, GDP per capita) |
| sub_field | string | Optional sub-field for nested data |
Example
curl "https://www.worldfactbook.co/api/timeline.php?country=us&field=Population" \ -H "X-API-Key: YOUR_API_KEY"
Data Export API
/api/export.phpExport country data in CSV or JSON format. Filter by country, category, or edition.
| Parameter | Type | Description |
|---|---|---|
| format | string | csv or json |
| country | string | Filter by country slug |
| category | string | Filter by category name |
AI Chatbot API
/api/chat.phpQuery the AI chatbot for natural language answers about any country data. Supports comparisons, rankings, trends, and general knowledge queries.
| Parameter | Type | Description |
|---|---|---|
| message | string | Natural language question |
| session_token | string | Session token for conversation context |
Example
curl -X POST "https://www.worldfactbook.co/api/chat.php" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"message": "Compare GDP of US and China"}'
World Meters API
Real-time global statistics — population, economics, environment, health, and more with live animated counters.
Endpoints
/affiliates/worldmeter/api.php?action=info
Get app info, description, and metadata
/affiliates/worldmeter/api.php?action=stats
Get app statistics (data counts, content counts, online users)
/affiliates/worldmeter/api.php?action=data
Retrieve app data records with optional filters
Params: country, category, limit, offset
/affiliates/worldmeter/api.php?action=content
List content articles for this app
Params: slug, category, limit
/affiliates/worldmeter/api.php?action=search&q={query}
Search data and content within this app
Params: q (search query)
Embed Widget
Embed a widget for this app on any website:
<script src="https://www.worldfactbook.co/affiliates/worldmeter/embed.php?format=js"></script> <!-- Or use iframe --> <iframe src="https://www.worldfactbook.co/affiliates/worldmeter/embed.php" width="400" height="300" frameborder="0"></iframe>
Example Request
curl "https://www.worldfactbook.co/affiliates/worldmeter/api.php?action=data&limit=10" \ -H "X-API-Key: YOUR_API_KEY"
World Economies API
Country economic data explorer — GDP, trade, development indicators powered by World Bank data.
Endpoints
/affiliates/worldeconomies/api.php?action=info
Get app info, description, and metadata
/affiliates/worldeconomies/api.php?action=stats
Get app statistics (data counts, content counts, online users)
/affiliates/worldeconomies/api.php?action=data
Retrieve app data records with optional filters
Params: country, category, limit, offset
/affiliates/worldeconomies/api.php?action=content
List content articles for this app
Params: slug, category, limit
/affiliates/worldeconomies/api.php?action=search&q={query}
Search data and content within this app
Params: q (search query)
Embed Widget
Embed a widget for this app on any website:
<script src="https://www.worldfactbook.co/affiliates/worldeconomies/embed.php?format=js"></script> <!-- Or use iframe --> <iframe src="https://www.worldfactbook.co/affiliates/worldeconomies/embed.php" width="400" height="300" frameborder="0"></iframe>
Example Request
curl "https://www.worldfactbook.co/affiliates/worldeconomies/api.php?action=data&limit=10" \ -H "X-API-Key: YOUR_API_KEY"
World History API
Encyclopedia of civilizations, events, and historical figures — explore humanity's story through the ages.
Endpoints
/affiliates/worldhistory/api.php?action=info
Get app info, description, and metadata
/affiliates/worldhistory/api.php?action=stats
Get app statistics (data counts, content counts, online users)
/affiliates/worldhistory/api.php?action=data
Retrieve app data records with optional filters
Params: country, category, limit, offset
/affiliates/worldhistory/api.php?action=content
List content articles for this app
Params: slug, category, limit
/affiliates/worldhistory/api.php?action=search&q={query}
Search data and content within this app
Params: q (search query)
Embed Widget
Embed a widget for this app on any website:
<script src="https://www.worldfactbook.co/affiliates/worldhistory/embed.php?format=js"></script> <!-- Or use iframe --> <iframe src="https://www.worldfactbook.co/affiliates/worldhistory/embed.php" width="400" height="300" frameborder="0"></iframe>
Example Request
curl "https://www.worldfactbook.co/affiliates/worldhistory/api.php?action=data&limit=10" \ -H "X-API-Key: YOUR_API_KEY"
Old Maps Online API
Discover historical maps from libraries around the world — browse by region, era, and place.
Endpoints
/affiliates/oldmaps/api.php?action=info
Get app info, description, and metadata
/affiliates/oldmaps/api.php?action=stats
Get app statistics (data counts, content counts, online users)
/affiliates/oldmaps/api.php?action=data
Retrieve app data records with optional filters
Params: country, category, limit, offset
/affiliates/oldmaps/api.php?action=content
List content articles for this app
Params: slug, category, limit
/affiliates/oldmaps/api.php?action=search&q={query}
Search data and content within this app
Params: q (search query)
Embed Widget
Embed a widget for this app on any website:
<script src="https://www.worldfactbook.co/affiliates/oldmaps/embed.php?format=js"></script> <!-- Or use iframe --> <iframe src="https://www.worldfactbook.co/affiliates/oldmaps/embed.php" width="400" height="300" frameborder="0"></iframe>
Example Request
curl "https://www.worldfactbook.co/affiliates/oldmaps/api.php?action=data&limit=10" \ -H "X-API-Key: YOUR_API_KEY"
World AI & Technology API
Global technology adoption, AI usage statistics, and digital infrastructure data by country.
Endpoints
/affiliates/worldai/api.php?action=info
Get app info, description, and metadata
/affiliates/worldai/api.php?action=stats
Get app statistics (data counts, content counts, online users)
/affiliates/worldai/api.php?action=data
Retrieve app data records with optional filters
Params: country, category, limit, offset
/affiliates/worldai/api.php?action=content
List content articles for this app
Params: slug, category, limit
/affiliates/worldai/api.php?action=search&q={query}
Search data and content within this app
Params: q (search query)
Embed Widget
Embed a widget for this app on any website:
<script src="https://www.worldfactbook.co/affiliates/worldai/embed.php?format=js"></script> <!-- Or use iframe --> <iframe src="https://www.worldfactbook.co/affiliates/worldai/embed.php" width="400" height="300" frameborder="0"></iframe>
Example Request
curl "https://www.worldfactbook.co/affiliates/worldai/api.php?action=data&limit=10" \ -H "X-API-Key: YOUR_API_KEY"
Crypto World API
Global cryptocurrency adoption, market data, and blockchain statistics by country — tracking Bitcoin, Ethereum, and the digital asset ecosystem.
Endpoints
/affiliates/cryptoworld/api.php?action=info
Get app info, description, and metadata
/affiliates/cryptoworld/api.php?action=stats
Get app statistics (data counts, content counts, online users)
/affiliates/cryptoworld/api.php?action=data
Retrieve app data records with optional filters
Params: country, category, limit, offset
/affiliates/cryptoworld/api.php?action=content
List content articles for this app
Params: slug, category, limit
/affiliates/cryptoworld/api.php?action=search&q={query}
Search data and content within this app
Params: q (search query)
Embed Widget
Embed a widget for this app on any website:
<script src="https://www.worldfactbook.co/affiliates/cryptoworld/embed.php?format=js"></script> <!-- Or use iframe --> <iframe src="https://www.worldfactbook.co/affiliates/cryptoworld/embed.php" width="400" height="300" frameborder="0"></iframe>
Example Request
curl "https://www.worldfactbook.co/affiliates/cryptoworld/api.php?action=data&limit=10" \ -H "X-API-Key: YOUR_API_KEY"
World Sports API
Global sports data — Olympic medal tables, FIFA rankings, major sporting events, and country athletic profiles with performance analytics.
Endpoints
/affiliates/worldsports/api.php?action=info
Get app info, description, and metadata
/affiliates/worldsports/api.php?action=stats
Get app statistics (data counts, content counts, online users)
/affiliates/worldsports/api.php?action=data
Retrieve app data records with optional filters
Params: country, category, limit, offset
/affiliates/worldsports/api.php?action=content
List content articles for this app
Params: slug, category, limit
/affiliates/worldsports/api.php?action=search&q={query}
Search data and content within this app
Params: q (search query)
Embed Widget
Embed a widget for this app on any website:
<script src="https://www.worldfactbook.co/affiliates/worldsports/embed.php?format=js"></script> <!-- Or use iframe --> <iframe src="https://www.worldfactbook.co/affiliates/worldsports/embed.php" width="400" height="300" frameborder="0"></iframe>
Example Request
curl "https://www.worldfactbook.co/affiliates/worldsports/api.php?action=data&limit=10" \ -H "X-API-Key: YOUR_API_KEY"
World Music API
Global music charts, genre exploration, artist profiles, and country music landscapes. Discover trending songs and musical traditions worldwide.
Endpoints
/affiliates/worldmusic/api.php?action=info
Get app info, description, and metadata
/affiliates/worldmusic/api.php?action=stats
Get app statistics (data counts, content counts, online users)
/affiliates/worldmusic/api.php?action=data
Retrieve app data records with optional filters
Params: country, category, limit, offset
/affiliates/worldmusic/api.php?action=content
List content articles for this app
Params: slug, category, limit
/affiliates/worldmusic/api.php?action=search&q={query}
Search data and content within this app
Params: q (search query)
Embed Widget
Embed a widget for this app on any website:
<script src="https://www.worldfactbook.co/affiliates/worldmusic/embed.php?format=js"></script> <!-- Or use iframe --> <iframe src="https://www.worldfactbook.co/affiliates/worldmusic/embed.php" width="400" height="300" frameborder="0"></iframe>
Example Request
curl "https://www.worldfactbook.co/affiliates/worldmusic/api.php?action=data&limit=10" \ -H "X-API-Key: YOUR_API_KEY"
World Movies & TV API
World cinema and television — trending films, box office rankings, award trackers, and country film industry profiles with streaming guides.
Endpoints
/affiliates/worldmovies/api.php?action=info
Get app info, description, and metadata
/affiliates/worldmovies/api.php?action=stats
Get app statistics (data counts, content counts, online users)
/affiliates/worldmovies/api.php?action=data
Retrieve app data records with optional filters
Params: country, category, limit, offset
/affiliates/worldmovies/api.php?action=content
List content articles for this app
Params: slug, category, limit
/affiliates/worldmovies/api.php?action=search&q={query}
Search data and content within this app
Params: q (search query)
Embed Widget
Embed a widget for this app on any website:
<script src="https://www.worldfactbook.co/affiliates/worldmovies/embed.php?format=js"></script> <!-- Or use iframe --> <iframe src="https://www.worldfactbook.co/affiliates/worldmovies/embed.php" width="400" height="300" frameborder="0"></iframe>
Example Request
curl "https://www.worldfactbook.co/affiliates/worldmovies/api.php?action=data&limit=10" \ -H "X-API-Key: YOUR_API_KEY"
World Religion & Culture API
Religious demographics, cultural practices, diversity indexes, sacred sites, holidays, and heritage for every country worldwide.
Endpoints
/affiliates/worldreligion/api.php?action=info
Get app info, description, and metadata
/affiliates/worldreligion/api.php?action=stats
Get app statistics (data counts, content counts, online users)
/affiliates/worldreligion/api.php?action=data
Retrieve app data records with optional filters
Params: country, category, limit, offset
/affiliates/worldreligion/api.php?action=content
List content articles for this app
Params: slug, category, limit
/affiliates/worldreligion/api.php?action=search&q={query}
Search data and content within this app
Params: q (search query)
Embed Widget
Embed a widget for this app on any website:
<script src="https://www.worldfactbook.co/affiliates/worldreligion/embed.php?format=js"></script> <!-- Or use iframe --> <iframe src="https://www.worldfactbook.co/affiliates/worldreligion/embed.php" width="400" height="300" frameborder="0"></iframe>
Example Request
curl "https://www.worldfactbook.co/affiliates/worldreligion/api.php?action=data&limit=10" \ -H "X-API-Key: YOUR_API_KEY"
World Food & Cuisine API
World cuisine explorer — national dishes, food security data, agricultural statistics, and culinary traditions by country and region.
Endpoints
/affiliates/worldfood/api.php?action=info
Get app info, description, and metadata
/affiliates/worldfood/api.php?action=stats
Get app statistics (data counts, content counts, online users)
/affiliates/worldfood/api.php?action=data
Retrieve app data records with optional filters
Params: country, category, limit, offset
/affiliates/worldfood/api.php?action=content
List content articles for this app
Params: slug, category, limit
/affiliates/worldfood/api.php?action=search&q={query}
Search data and content within this app
Params: q (search query)
Embed Widget
Embed a widget for this app on any website:
<script src="https://www.worldfactbook.co/affiliates/worldfood/embed.php?format=js"></script> <!-- Or use iframe --> <iframe src="https://www.worldfactbook.co/affiliates/worldfood/embed.php" width="400" height="300" frameborder="0"></iframe>
Example Request
curl "https://www.worldfactbook.co/affiliates/worldfood/api.php?action=data&limit=10" \ -H "X-API-Key: YOUR_API_KEY"
Error Codes
| Code | Status | Description |
|---|---|---|
| 200 | OK | Request successful |
| 400 | Bad Request | Invalid parameters or missing required fields |
| 401 | Unauthorized | Missing or invalid API key |
| 403 | Forbidden | API key is revoked, rejected, or expired |
| 404 | Not Found | Resource or endpoint not found |
| 429 | Too Many Requests | Rate limit exceeded — slow down |
| 500 | Internal Server Error | Server-side error — try again later |
Error Response Format
{
"status": "error",
"code": 401,
"message": "Invalid or missing API key"
}
Widgets & Embeds
Each partner app provides an embeddable widget that can be added to any website. Widgets are available as JavaScript embeds or iframes.
Available Widgets
/affiliates/worldmeter/embed.php
/affiliates/worldeconomies/embed.php
/affiliates/worldhistory/embed.php
/affiliates/oldmaps/embed.php
/affiliates/worldai/embed.php
/affiliates/cryptoworld/embed.php
/affiliates/worldsports/embed.php
/affiliates/worldmusic/embed.php
/affiliates/worldmovies/embed.php
/affiliates/worldreligion/embed.php
/affiliates/worldfood/embed.php
JavaScript Embed
<div id="wfb-widget"></div>
<script src="https://www.worldfactbook.co/affiliates/{app_key}/embed.php?format=js"></script>
Iframe Embed
<iframe src="https://www.worldfactbook.co/affiliates/{app_key}/embed.php"
width="100%" height="400" frameborder="0"
style="border-radius:12px; border:1px solid #e2e8f0;"></iframe>