Global Reference Data API

A fast, reliable REST API for global reference data — countries, currencies, languages, timezones, holidays, regions, and units of measure. Built for AI agents and developers.

🌍 Base URL: https://reference-data-api.refdata.workers.dev — Served from 300+ locations globally via Cloudflare.

Overview

All endpoints are prefixed with /v1/ and require an API key. Responses are JSON.

Domain	Records	Endpoints
countries	197	/v1/countries
currencies	142	/v1/currencies
languages	183	/v1/languages
timezones	315	/v1/timezones
holidays	100+ countries	/v1/holidays
regions	28	/v1/regions
units	61	/v1/units

Authentication

Pass your API key in the X-API-Key header on every request.

curl https://reference-data-api.refdata.workers.dev/v1/countries/GB   -H "X-API-Key: rdak_your_api_key_here"

Pricing

Free

1,000 calls/month
10 req/min
All endpoints

Starter

$9/mo

50,000 calls/month
60 req/min
All endpoints

Pro

$49/mo

500,000 calls/month
300 req/min
All endpoints

Pay-as-you-go

$0.001/call

Unlimited calls
100 req/min
All endpoints

Errors

All errors return a JSON object with error and message fields.

HTTP Code	Error	Meaning
400	INVALID_REQUEST	Missing or invalid parameters
401	MISSING_API_KEY	No API key provided
401	INVALID_API_KEY	API key not found or invalid
404	NOT_FOUND	Resource not found
429	RATE_LIMITED	Too many requests per minute
429	USAGE_EXCEEDED	Monthly limit reached
500	INTERNAL_ERROR	Server error

Rate Limits

Rate limit info is returned in response headers on every request.

Header	Description
X-RateLimit-Limit	Max requests per minute for your plan
X-RateLimit-Remaining	Requests remaining in current window
X-RateLimit-Reset	Unix timestamp when window resets
X-Usage-This-Month	Total calls used this month
X-Monthly-Limit	Your monthly call limit
X-Usage-Remaining	Calls remaining this month

Countries

ISO 3166-1 country data including codes, names, capitals, regions, currencies, languages, timezones, and more.

GET/v1/countries/{code}

Get a single country by ISO 3166-1 alpha-2 or alpha-3 code.

curl /v1/countries/GB -H "X-API-Key: rdak_..."

GET/v1/countries

List all countries with optional filters.

Parameter	Type	Description
region	string	Africa, Americas, Asia, Europe, Oceania
continent	string	Filter by continent
landlocked	boolean	true = landlocked only
un_member	boolean	true = UN members only

GET/v1/countries/search?q={query}

Search by name, capital, currency, language, timezone, or dial code.

curl "/v1/countries/search?q=london" -H "X-API-Key: rdak_..."

POST/v1/countries/batch

Retrieve up to 50 countries in a single request.

curl -X POST /v1/countries/batch   -H "X-API-Key: rdak_..."   -H "Content-Type: application/json"   -d '{"codes": ["GB", "US", "DE", "FR", "JP"]}'

Currencies

ISO 4217 currency data including symbols, decimal places, separators, and countries using each currency.

GET/v1/currencies/{code}

Get a single currency by ISO 4217 code.

curl /v1/currencies/GBP -H "X-API-Key: rdak_..."

GET/v1/currencies

List all currencies with optional filters.

Parameter	Type	Description
region	string	Filter by region
type	string	fiat, crypto, precious_metal

GET/v1/currencies/search?q={query}

Search by name, code, symbol, or country.

POST/v1/currencies/batch

Retrieve up to 50 currencies in a single request.

curl -X POST /v1/currencies/batch   -H "X-API-Key: rdak_..."   -d '{"codes": ["GBP", "USD", "EUR"]}'

Languages

ISO 639-1 language data including English names and native names.

GET/v1/languages/{code}

Get a single language by ISO 639-1 code.

curl /v1/languages/ar -H "X-API-Key: rdak_..."

GET/v1/languages

List all 183 ISO 639-1 languages.

GET/v1/languages/search?q={query}

Search by English name or native name.

curl "/v1/languages/search?q=arabic" -H "X-API-Key: rdak_..."

Timezones

IANA timezone data including UTC offsets, abbreviations, countries, and main cities.

GET/v1/timezones/{name}

Get a single timezone by IANA name.

curl /v1/timezones/Europe/London -H "X-API-Key: rdak_..."

GET/v1/timezones

List all 315 timezones with optional filters.

Parameter	Type	Description
country_code	string	Filter by ISO country code e.g. GB
continent	string	Filter by continent name

GET/v1/timezones/search?q={query}

Search by city, country, abbreviation, or UTC offset.

curl "/v1/timezones/search?q=riyadh" -H "X-API-Key: rdak_..."

Public Holidays

Public holiday data for 100+ countries, queried by country and year.

GET/v1/holidays/{country_code}

Get all holidays for a country and year.

Parameter	Type	Description
year	integer	Year to retrieve holidays for (default: current year)
type	string	Filter by type: public, bank, observance, school

curl "/v1/holidays/GB?year=2025&type=public" -H "X-API-Key: rdak_..."

GET/v1/holidays/{country_code}/check

Check if a specific date is a public holiday.

Parameter	Type	Description
date	string	Date in YYYY-MM-DD format

curl "/v1/holidays/GB/check?date=2025-12-25" -H "X-API-Key: rdak_..."

Geographic Regions

Geographic regions and continents with country mappings.

GET/v1/regions/{code}

Get a region by code.

curl /v1/regions/EU -H "X-API-Key: rdak_..."
curl /v1/regions/EU-W -H "X-API-Key: rdak_..."

GET/v1/regions

List all regions with optional filters.

Parameter	Type	Description
type	string	continent or region
parent_code	string	Filter by parent e.g. EU returns all European sub-regions

Units of Measure

Units of measure across 10 categories with conversion factors to base units.

GET/v1/units/{code}

Get a unit by code.

curl /v1/units/km -H "X-API-Key: rdak_..."

GET/v1/units

List all units with optional filters.

Parameter	Type	Description
category	string	length, mass, temperature, volume, area, speed, digital_storage, energy, pressure, time
system	string	SI, imperial, US, other
base_unit	boolean	true = base units only

GET/v1/units/search?q={query}

Search by name, symbol, or category.

curl "/v1/units/search?q=metre" -H "X-API-Key: rdak_..."

Global Reference Data API — Built on Cloudflare Workers — 300+ global locations

RefData API