Which country code systems does the API resolve?
All three ISO 3166-1 systems: alpha-2 (US), alpha-3 (USA), and numeric (840). GET /countries/:code accepts any of them and returns the full record with all identifiers.
Country Codes API
ISO 3166
Fuzzy Matching
JSON + CSV Export
ISO country codes. Typos included.
Resolve ISO2, ISO3, and numeric codes, search by partial name, and recover from misspellings with fuzzy matching. Export the full dataset when you need it locally.
249 · countries3 · code systems25 · search results maxJSON + CSV · export
Resolve any country input.
This calls the live Country Codes API. Look up exact codes, search partial names, or throw a typo at the fuzzy matcher.
Request builder
Three resolution modes for messy inputs.
GET /countries/:code
Exact code resolution: ISO2, ISO3, or numeric. Try US, DEU, or 840.
Full dataset export
GET /export returns all 249 countries as JSON, or a CSV attachment with format=csv, when you want the reference data cached locally.
Output preview
Live response from the API, plus the exact request to reproduce it.
| countryName | iso2 | iso3 | numericCode |
|---|---|---|---|
| Loading live response... | |||
Why Country Codes API
Normalize country data at the edge.
Complete ISO 3166 dataset
249 countries with countryName, iso2, iso3, and numericCode, kept consistent across every endpoint.
Any code system in
/countries/:code resolves ISO2 (US), ISO3 (USA), and numeric (840) identifiers with a single lookup.
Partial name search
/countries/search returns up to 25 matches for fragments like united, making autocomplete inputs trivial.
Typo-tolerant matching
/countries/match tries an exact code first, then fuzzy-matches names. Responses include matchType and a similarity score.
JSON and CSV export
/export delivers the full dataset as JSON or a CSV attachment for seeding local caches and spreadsheets.
Structured metadata
Every JSON response carries a meta object with counts, query echo, timestamps, and a correlationId for tracing.
/api/v1/country-codes
Endpoints, at a glance.
Lookup, list, search, fuzzy match, and export. Five read-only endpoints over one consistent dataset.
GET/api/v1/country-codes/countries/:code
Exact code lookup
Resolve ISO2, ISO3, or numeric codes to a full country record in one call.
GET/api/v1/country-codes/countries
List all countries
All 249 countries sorted by name, with ISO2, ISO3, and numeric codes.
GET/api/v1/country-codes/countries/search
Partial name search
Requires q. Returns up to 25 partial matches for autocomplete and validation flows.
GET/api/v1/country-codes/countries/match
Fuzzy match
Requires q. Exact code match first, then typo-tolerant name matching with a similarity score.
GET/api/v1/country-codes/export
Dataset export
Full dataset as JSON by default, or a CSV attachment with format=csv.
GET/health
Service health
Status, service name, version, timestamp, and uptime.
| Parameter | Type | Required | Description |
|---|---|---|---|
| code | path | for /countries/:code | Country identifier: ISO2 (US), ISO3 (USA), or numeric code text (840). |
| q | string | search, match | Search input. Partial names for /search; codes or misspelled names for /match. |
| format | string | no | Export format for /export: "json" (default) or "csv". |
Error reference
Predictable failure shapes.
Every error sets success: false with an error message and a meta.correlationId.
400Missing Query
The q parameter is required for /countries/search and /countries/match.
401Authentication Error
Missing or invalid API key at the gateway. Send x-api-key or api_key with every request.
404Country Not Found
No country matched the code lookup or fuzzy match, e.g. /countries/XYZ. The error echoes the failing input.
500Internal Error
Database or query processing failure. Include the meta.correlationId when reporting the issue.
Example error response
{
"success": false,
"error": "No country found for input 'XYZ'",
"meta": {
"correlationId": "req_abc123def456",
"timestamp": "2026-06-09T00:00:00.000Z"
}
}FAQ
API questions developers ask first.
How does fuzzy matching handle misspellings?
GET /countries/match first attempts an exact code match, then falls back to fuzzy name matching. A query like afganistan returns Afghanistan with matchType fuzzy and a similarity score you can threshold against.
What is the difference between search and match?
Search returns up to 25 partial-name matches and is built for autocomplete. Match returns the single best candidate for messy or misspelled input and reports how confident the match is.
Can I download the whole dataset?
Yes. GET /export returns all 249 countries as JSON, or set format=csv for a CSV attachment, useful for seeding local caches, spreadsheets, and offline validation.
How do I authenticate requests?
Send your Datpaq API key as an x-api-key header or an api_key query parameter. Keys are created in the Datpaq dashboard and a free tier is included.
Country inputs, normalized for good.
Resolve codes, search names, and recover typos with one reference API. Export the full ISO 3166 dataset whenever you need it locally.