Countries API

Pass your API key as the apikey query parameter on every request, for example /countries/v1/code/AW?apikey=YOUR_KEY. There are no special headers required for the direct Worker endpoint. When subscribing through RapidAPI, you instead send the standard X-RapidAPI-Key header that RapidAPI provides.

The /countries/v1/code/{code} endpoint resolves a country by cca2 (two-letter, e.g. AW), cca3 (three-letter, e.g. ABW), ccn3 (numeric, e.g. 533) or cioc (IOC, e.g. ARU). It tries those formats in that order and matches case-insensitively, so you can pass user input directly. If no country matches, the API returns a 404 with an error message.

Every country object is enriched with two ready-to-use flag image URLs: flag_png (a 320px PNG hosted on flagcdn.com) and flag_svg (a scalable vector version). You can use these directly in an img tag without hosting any assets yourself. A flag_emoji field is also included for text-based rendering.

The calling_codes array contains clean, full international dialing codes such as ['+297']. North American Numbering Plan members like the US and Canada collapse to a single ['+1'] instead of listing hundreds of area codes, and code-less territories like Antarctica return an empty array. The /countries/v1/calling-code/{code} endpoint resolves both shared roots (+1 returns US and CA) and specific codes (+297 returns Aruba), with or without a leading plus.

Yes. The /countries/v1/all endpoint supports a ?fields= parameter that projects only the comma-separated fields you specify, for example name_common,cca2,flag_svg. All list endpoints also accept a ?limit= parameter clamped between 1 and 500 (default 300 for lists, 50 for search), so you can keep payloads small and fast for UI components like country pickers.

The entire ~250-country dataset is bundled and served from Cloudflare's edge, so lookups resolve locally without any upstream third-party calls. That delivers predictable single-digit to low-tens-of-milliseconds latency worldwide, no third-party rate-limit risk, and consistent availability backed by a 99.9% uptime target. Because country reference data changes rarely, responses are also highly cacheable on your side.

Region filtering accepts Africa, Americas, Asia, Europe, Oceania or Antarctic (case-insensitive) via /countries/v1/region/{region} or the region query parameter on /all. Currency filtering uses ISO 4217 codes such as EUR via /countries/v1/currency/{code}, and language filtering uses ISO 639-3 codes such as eng via /countries/v1/language/{code}.