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
JSON + CSV Export
ISO country codes. Every system.
Resolve ISO2, ISO3, and numeric identifiers against the full ISO 3166 dataset in a single call. Export all 249 countries as JSON or CSV when you need the reference data locally.
249 · countries3 · code systemsJSON + CSV · export
Resolve any country code.
This calls the live Country Codes API. Pass an ISO2, ISO3, or numeric code and get the full record back.
Request builder
Exact code resolution across all three ISO 3166 systems.
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.
Search and fuzzy match are temporarily unavailable
GET /countries/search and GET /countries/match are documented but currently return 404 in production, so they are not wired into this demo.
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.
Full list in one call
/countries returns all 249 records sorted by name, with a count field for pagination-free consumption.
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 metadata object with counts, query echo, timestamps, and a correlationId for tracing.
/api/v1/country-codes
Endpoints, at a glance.
Lookup, list, and export over one consistent dataset. Search and fuzzy match are documented but currently unavailable.
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. Currently returns 404 in production — do not depend on it yet.
GET/api/v1/country-codes/countries/match
Fuzzy match
Requires q. Exact code match first, then typo-tolerant name matching with a similarity score. Currently returns 404 in production — do not depend on it yet.
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. Both endpoints are currently unavailable. |
| format | string | no | Export format for /export: "json" (default) or "csv". |
Error reference
Predictable failure shapes.
Service errors set success: false with an error message and a metadata.correlationId. Gateway auth failures are rejected before the service and return error plus message instead.
429Rate Limit
Plan quota exhausted. Service responses carry metadata.rate_limit with limit, remaining, and reset so you can back off first.
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, e.g. /countries/XYZ. The error echoes the failing input.
500Internal Error
Database or query processing failure. Include the metadata.correlationId when reporting the issue.
Example error response
{
"success": false,
"error": "No country found for input 'XYZ'",
"metadata": {
"correlationId": "req-1788110429275-zr3dbg9ct",
"timestamp": "2026-08-30T17:20:29.296Z",
"processingTime": "5ms",
"api_token_name": null,
"rate_limit": { "limit": 10000, "remaining": 9982, "reset": 1788110914 }
}
}FAQ
API questions developers ask first.
What happens when a code does not exist?
The API returns HTTP 404 with success false and an error message that echoes the failing input, for example "No country found for input 'XYZ'". Every response also carries a metadata.correlationId for tracing.
Can I get every country in one request?
Yes. GET /countries returns all 249 records sorted by name, each with countryName, iso2, iso3, and numericCode, plus a count field. There is no pagination to work through.
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 ISO2, ISO3, and numeric codes with one reference API. Export the full ISO 3166 dataset whenever you need it locally.