# REST Countries > Look up any of 250+ countries and territories by code or name, then search and list them by region, group, currency or language, with names, capitals, codes, currencies, calling codes and flags. The same REST Countries key also locates IP addresses, identifies browsers and bots from user agents, analyzes email addresses and converts currencies. App · Misc References · 13 actions. Web page: https://docs.lodol.com/docs/integrations/rest-countries ## Actions ### Analyze email address Learn about an email address without sending it anything: its parts, who handles its mail, its MX, SPF and DMARC records, when its domain was registered, whether it is a free, disposable, forwarding or role address, whether it has a Gravatar, and a fix for a mistyped domain like gmial.com. It cannot tell whether the mailbox exists. **Inputs** - Email address (`email`, text, required): The address to analyze. - Checks to skip (`skip_checks`, list): Checks to leave out, which makes the analysis faster. Skip Gravatar if your privacy policy does not cover sharing a hash of the address with it. One or more of: `gravatar` (Gravatar (sends a hash of the address to Gravatar)), `domain.registration` (Domain registration dates (the slowest check)), `domain.authentication` (SPF and DMARC records). **Outputs** - `attributes` (object) - `did_you_mean` (text): A corrected address when the domain looks mistyped, e.g. gmial.com; empty otherwise - `domain` (object) - `email` (text): The address analyzed - `gravatar` (object): The address's Gravatar. Not present when skipped - `parts` (object): The address in pieces - `tld` (object) **Example output** ```json { "attributes": { "has_plus_addressing": false, "is_disposable": false, "is_forwarder": false, "is_free": true, "is_likely_role_based": false, "is_valid_syntax": true }, "did_you_mean": null, "domain": { "authentication": { "dmarc": { "percentage": null, "policy": "none", "present": true, "record": "v=DMARC1; p=none; sp=quarantine; rua=mailto:mailauth-reports@google.com", "subdomain_policy": "quarantine" }, "spf": { "policy": "softfail", "present": true, "record": "v=spf1 redirect=_spf.google.com" } }, "category": "free", "favicon_url": "https://favicon.restcountries.com/v1/gmail.com", "mx": [ { "exchange": "gmail-smtp-in.l.google.com", "priority": 5 }, { "exchange": "alt1.gmail-smtp-in.l.google.com", "priority": 10 }, { "exchange": "alt2.gmail-smtp-in.l.google.com", "priority": 20 }, { "exchange": "alt3.gmail-smtp-in.l.google.com", "priority": 30 }, { "exchange": "alt4.gmail-smtp-in.l.google.com", "priority": 40 } ], "provider": { "name": "Google", "type": "mailbox", "url": "https://workspace.google.com" }, "registration": { "age_days": 11371, "expires_on": "2027-08-12", "registered_on": "1995-08-13", "transferred_on": null, "updated_on": "2026-07-11" } }, "email": "someone@gmail.com", "gravatar": { "avatar_url": null, "exists": false, "profile_url": null }, "parts": { "domain": "gmail.com", "local": "someone", "tag": null, "username": "someone" }, "tld": { "country": null, "name": "com" } } ``` ### Convert currency Convert an amount from one currency into up to five others at once, crypto like BTC included, at the latest rate. Rates are refreshed daily on the free plan and hourly on paid plans, and each result says when its rate is from. **Inputs** - From currency (`from_currency`, text, required): The code of the currency the amount is in. - To currencies (`to_currencies`, text, required): The code of the currency to convert to, or up to five separated by commas. - Amount (`amount`, number): How much to convert. 1 if left empty, which gives the rate. Default: `1`. **Outputs** - `amount` (number): The amount converted, in the from currency - `as_of` (text): When the rate was published, ISO 8601 in UTC - `conversions` (list): One conversion per currency converted to, in the order asked. The top-level fields are the first of these - `from` (object) - `rate` (number): How many of the to currency one of the from currency buys - `result` (number): The amount in the to currency - `to` (object) **Example output** ```json { "amount": 100, "as_of": "2026-09-30T00:00:00Z", "conversions": [ { "amount": 100, "as_of": "2026-09-30T00:00:00Z", "from": { "code": "USD", "name": "United States dollar", "symbol": "$" }, "rate": 0.88243363, "result": 88.243363, "to": { "code": "EUR", "name": "Euro", "symbol": "\u20ac" } } ], "from": { "code": "USD", "name": "United States dollar", "symbol": "$" }, "rate": 0.88243363, "result": 88.243363, "to": { "code": "EUR", "name": "Euro", "symbol": "\u20ac" } } ``` ### Find countries by property Find every country with an exact value in one field, ignoring case: the countries that use a currency (EUR), speak a language (Spanish), share a calling code (44), border a country (FRA), use an internet domain (.de), drive on the left, or are territories of another country (GB). **Inputs** - Property (`property_name`, text, required): Which field to match. One of: `currencies` (Currency (a code, like EUR)), `languages` (Language (its English name, like Spanish)), `calling_codes` (Calling code (like 44)), `borders` (Borders a country (its three-letter code, like FRA)), `capitals` (Capital city (like Ottawa)), `continents` (Continent (like Europe)), `timezones` (Time zone (a UTC offset, like UTC+05:30)), `tlds` (Internet domain (like .de)), `demonyms` (Demonym (like Canadian)), `names.translations` (Name in another language (like Allemagne)), and 9 more. - Value (`value`, text, required): The value the field has to hold, written as the property's example shows. - Limit (`limit`, number): How many countries to return at most: up to 100 on the free plan, and 500 on paid plans. From 1 to 500. Default: `25`. - Offset (`offset`, number): How many matching countries to skip, to get a later page. Each result gives the offset of the page after it. At least 0. Default: `0`. - Fields (`fields`, text): Only these fields, to keep the result small: paths separated by commas, like names.common, codes.alpha_2, flag.url_png. Leave it empty for all of them. **Outputs** - `count` (number): How many are on this page - `countries` (list): The countries on this page, alphabetically - `has_more` (true/false): True when more countries matched than this page holds - `next_offset` (number): The offset that gets the next page, or empty on the last page - `offset` (number): How many matching countries came before this page - `total` (number): How many countries matched in all **Example output** ```json { "count": 1, "countries": [ { "_meta": { "lastUpdatedTimestamp": 1790182685 }, "area": { "kilometers": 9984670, "miles": 3855101.1 }, "assets": [], "borders": [ "USA" ], "calling_codes": [ "1" ], "capitals": [ { "attributes": { "administrative": false, "constitutional": false, "executive": false, "judicial": false, "legislative": false, "primary": true }, "coordinates": { "lat": 45.42, "lng": -75.7 }, "name": "Ottawa" } ], "cars": { "driving_side": "right", "signs": [ "CDN" ] }, "classification": { "dependency": false, "dependency_type": "", "disputed": false, "iso_status": "official", "sovereign": true, "un_member": true, "un_observer": false }, "codes": { "alpha_2": "CA", "alpha_3": "CAN", "ccn3": "124", "cioc": "CAN", "fifa": "CAN", "fips": "CA", "gec": "CA" }, "continents": [ "North America" ], "coordinates": { "lat": 60, "lng": -95 }, "currencies": [ { "code": "CAD", "name": "Canadian dollar", "symbol": "$" } ], "date": { "academic_year_start": { "day": 1, "month": 9 }, "fiscal_year_start": { "corporate": { "basis": "convention", "day": 1, "month": 1 }, "government": { "day": 1, "month": 4 }, "personal": { "day": 1, "month": 1 } }, "start_of_week": "sunday" }, "demonyms": { "eng": { "f": "Canadian", "m": "Canadian" }, "fra": { "f": "Canadienne", "m": "Canadien" } }, "descriptions": { "long": "Canada is a Commonwealth realm with Ottawa as its capital and English and French as official languages. The Canadian dollar is the currency, and energy, minerals, forestry, manufacturing and services support a mostly southern population.", "short": "Canada is a federal parliamentary state in northern North America, second in the world by area." }, "economy": { "gini_coefficient": { "2018": 32.5, "2019": 31.8, "2020": 29.9, "2021": 31.1, "2022": 31.5 } }, "flag": { "colors": { "dominant": "#fcfaf5", "palette": [ { "hex": "#fcfaf5", "proportion": 0.35886481537992065 }, { "hex": "#ff181b", "proportion": 0.6341165700335673 }, { "hex": "#ff8d94", "proportion": 0.00183094293561184 }, { "hex": "#ff9ea3", "proportion": 0.0012206286237412267 }, { "hex": "#ffbbbd", "proportion": 0.00183094293561184 }, { "hex": "#ff7a6b", "proportion": 0.00091547146780592 }, { "hex": "#ff5c4f", "proportion": 0.0012206286237412267 }, { "hex": "#f27400", "proportion": 0 } ], "prominent": "#ff181b", "swatches": { "dark_muted": null, "dark_vibrant": null, "light_muted": "#ffbbbd", "light_vibrant": "#ff7a6b", "muted": "#ff9ea3", "vibrant": "#ff181b" } }, "description": "The flag of Canada is composed of a red vertical band on the hoist and fly sides and a central white square that is twice the width of the vertical bands. A large eleven-pointed red maple leaf is centered in the white square.", "emoji": "\ud83c\udde8\ud83c\udde6", "html_entity": "🇨🇦", "unicode": "U+1F1E8 U+1F1E6", "url_png": "https://flags.restcountries.com/v5/w640/ca.png", "url_svg": "https://flags.restcountries.com/v5/svg/ca.svg" }, "government_type": "Federal parliamentary constitutional monarchy", "landlocked": false, "languages": [ { "bcp47": "en", "iso639_1": "en", "iso639_2b": "eng", "iso639_2t": "eng", "iso639_3": "eng", "name": "English", "native_name": "English" }, { "bcp47": "fr", "iso639_1": "fr", "iso639_2b": "fre", "iso639_2t": "fra", "iso639_3": "fra", "name": "French", "native_name": "fran\u00e7ais" } ], "leaders": [ { "assets": { "wikipedia.article.open_graph_image": { "renditions": [ { "content_hash": "1a9955aacbfd63c81aeb0f2317dd3faf", "content_type": "image/webp", "filesize": 7646, "height": 256, "max_edge": 256, "url": "https://assets-03.restcountries.com/assets.00/asst85zaqnak/charles-iii-182x256.webp", "width": 182 } ], "source": "wikipedia", "type": "article.open_graph_image" } }, "attributes": { "administers_executive": false, "de_facto_executive": false, "head_of_government": false, "head_of_state": true, "is_representative": false, "pending_office": false, "provisional": false }, "links": { "wikipedia": "https://en.wikipedia.org/wiki/Charles_III" }, "name": "Charles III", "title": "Monarch", "uuid": "861547aa-d5cd-5dd0-ba76-b58a1dfae3f0" }, { "assets": { "wikipedia.article.open_graph_image": { "renditions": [ { "content_hash": "f93f3d869d61cbe530e8cdc98b803473", "content_type": "image/webp", "filesize": 8010, "height": 256, "max_edge": 256, "url": "https://assets-03.restcountries.com/assets.00/asstru9leop5/louise-arbour-171x256.webp", "width": 171 } ], "source": "wikipedia", "type": "article.open_graph_image" } }, "attributes": { "administers_executive": false, "de_facto_executive": false, "head_of_government": false, "head_of_state": true, "is_representative": true, "pending_office": false, "provisional": false }, "links": { "wikipedia": "https://en.wikipedia.org/wiki/Louise_Arbour" }, "name": "Louise Arbour", "title": "Governor General", "uuid": "6e79fcc8-c2af-5510-b0ef-a8f4ede96059" }, { "assets": { "wikipedia.article.open_graph_image": { "renditions": [ { "content_hash": "455c86374739a59b12544f7d680c6040", "content_type": "image/webp", "filesize": 6150, "height": 256, "max_edge": 256, "url": "https://assets-03.restcountries.com/assets.00/assti2l9gpkk/mark-carney-192x256.webp", "width": 192 } ], "source": "wikipedia", "type": "article.open_graph_image" } }, "attributes": { "administers_executive": true, "de_facto_executive": false, "head_of_government": true, "head_of_state": false, "is_representative": false, "pending_office": false, "provisional": false }, "links": { "wikipedia": "https://en.wikipedia.org/wiki/Mark_Carney" }, "name": "Mark Carney", "title": "Prime Minister", "uuid": "146fc918-3dab-56a7-8e0e-ebf42865aa89" } ], "links": { "google_maps": "https://goo.gl/maps/jmEVLugreeqiZXxbA", "official": "https://www.canada.ca", "open_street_maps": "https://www.openstreetmap.org/relation/1428125", "wikipedia": "https://en.wikipedia.org/wiki/Canada" }, "memberships": { "african_union": false, "arab_league": false, "asean": false, "brics": false, "commonwealth": true, "eu": false, "eurozone": false, "g20": true, "g7": true, "nato": true, "oecd": true, "opec": false, "schengen": false, "un": true }, "names": { "alternates": [], "common": "Canada", "native": { "eng": { "common": "Canada", "official": "Canada" }, "fra": { "common": "Canada", "official": "Canada" } }, "official": "Canada", "translations": { "deu": { "common": "Kanada", "official": "Kanada" }, "fra": { "common": "Canada", "official": "Canada" }, "jpn": { "common": "\u30ab\u30ca\u30c0", "official": "\u30ab\u30ca\u30c0" }, "spa": { "common": "Canad\u00e1", "official": "Canad\u00e1" }, "zho": { "common": "\u52a0\u62ff\u5927", "official": "\u52a0\u62ff\u5927" } } }, "number_format": { "decimal_separator": ".", "thousands_separator": "," }, "parent": { "alpha_2": "", "alpha_3": "" }, "population": 41798407, "postal_code": { "format": "@#@ #@#", "regex": "^([ABCEGHJKLMNPRSTVXY]\\d[ABCEGHJKLMNPRSTVWXYZ]) ?(\\d[ABCEGHJKLMNPRSTVWXYZ]\\d)$" }, "region": "Americas", "subregion": "North America", "timezones": [ "UTC-08:00", "UTC-07:00", "UTC-06:00", "UTC-05:00", "UTC-04:00", "UTC-03:30" ], "tlds": [ ".ca" ], "units": { "measurement_system": "metric", "temperature_scale": "Celsius" }, "uuid": "189581ed-44b0-47d7-9849-6b097401a7d6" } ], "has_more": false, "next_offset": null, "offset": 0, "total": 1 } ``` ### Find country by name Find the one country a name means, such as a country typed into a form, and get its codes and details. Matches the common name (Germany), the official name (Federal Republic of Germany), its name in its own language (Deutschland) or another name it goes by (Holland), ignoring case and accents, and then its name in other languages (Allemagne). A name that could mean several countries, like Korea, fails with the list of them instead of guessing. **Inputs** - Country name (`name`, text, required): The country's name, in any of its forms. - Fields (`fields`, text): Only these fields, to keep the result small: paths separated by commas, like names.common, codes.alpha_2, flag.url_png. Leave it empty for all of them. **Outputs**: A country, as REST Countries describes it. With Fields set, only those fields are present - `_meta` (object): About the record itself - `area` (object): Its land area - `assets` (list): Images of the country, where there are any - `borders` (list): Alpha-3 codes of the countries it shares a land border with - `calling_codes` (list): International calling codes, e.g. '1' or '44' - `capitals` (list): Its capital cities, usually one - `cars` (object): Road traffic - `classification` (object): What kind of entity it is - `codes` (object): The country's codes - `continents` (list): The continents it is on - `coordinates` (object): Where its geographic center is - `currencies` (list): The currencies it officially uses - `date` (object): Calendar conventions - `demonyms` (object): What its people are called, keyed by ISO 639-3 code, each with masculine (m) and feminine (f) forms - `descriptions` (object): Descriptions of the country - `economy` (object): Economic figures - `flag` (object): The country's flag - `government_type` (text): The type of government in power - `landlocked` (true/false): True when it has no coastline - `languages` (list): The languages used in the country - `leaders` (list): Its current political leaders. Paid plans only: on the free plan this holds a notice instead - `links` (object): Links about the country - `memberships` (object): Which organizations it belongs to - `names` (object): The country's names - `number_format` (object): How numbers are written - `parent` (object): The country a dependency belongs to; empty codes otherwise - `population` (number): Population, from the country's own official figures - `postal_code` (object): Postal codes - `region` (text): Region: Africa, Americas, Antarctic, Asia, Europe or Oceania - `subregion` (text): Subregion, e.g. 'North America' or 'Western Europe' - `timezones` (list): The UTC offsets it observes, e.g. 'UTC-05:00' - `tlds` (list): Its internet domains, e.g. '.ca' - `units` (object): Units in everyday use - `uuid` (text): REST Countries' identifier for the record **Example output** ```json { "_meta": { "lastUpdatedTimestamp": 1790182685 }, "area": { "kilometers": 9984670, "miles": 3855101.1 }, "assets": [], "borders": [ "USA" ], "calling_codes": [ "1" ], "capitals": [ { "attributes": { "administrative": false, "constitutional": false, "executive": false, "judicial": false, "legislative": false, "primary": true }, "coordinates": { "lat": 45.42, "lng": -75.7 }, "name": "Ottawa" } ], "cars": { "driving_side": "right", "signs": [ "CDN" ] }, "classification": { "dependency": false, "dependency_type": "", "disputed": false, "iso_status": "official", "sovereign": true, "un_member": true, "un_observer": false }, "codes": { "alpha_2": "CA", "alpha_3": "CAN", "ccn3": "124", "cioc": "CAN", "fifa": "CAN", "fips": "CA", "gec": "CA" }, "continents": [ "North America" ], "coordinates": { "lat": 60, "lng": -95 }, "currencies": [ { "code": "CAD", "name": "Canadian dollar", "symbol": "$" } ], "date": { "academic_year_start": { "day": 1, "month": 9 }, "fiscal_year_start": { "corporate": { "basis": "convention", "day": 1, "month": 1 }, "government": { "day": 1, "month": 4 }, "personal": { "day": 1, "month": 1 } }, "start_of_week": "sunday" }, "demonyms": { "eng": { "f": "Canadian", "m": "Canadian" }, "fra": { "f": "Canadienne", "m": "Canadien" } }, "descriptions": { "long": "Canada is a Commonwealth realm with Ottawa as its capital and English and French as official languages. The Canadian dollar is the currency, and energy, minerals, forestry, manufacturing and services support a mostly southern population.", "short": "Canada is a federal parliamentary state in northern North America, second in the world by area." }, "economy": { "gini_coefficient": { "2018": 32.5, "2019": 31.8, "2020": 29.9, "2021": 31.1, "2022": 31.5 } }, "flag": { "colors": { "dominant": "#fcfaf5", "palette": [ { "hex": "#fcfaf5", "proportion": 0.35886481537992065 }, { "hex": "#ff181b", "proportion": 0.6341165700335673 }, { "hex": "#ff8d94", "proportion": 0.00183094293561184 }, { "hex": "#ff9ea3", "proportion": 0.0012206286237412267 }, { "hex": "#ffbbbd", "proportion": 0.00183094293561184 }, { "hex": "#ff7a6b", "proportion": 0.00091547146780592 }, { "hex": "#ff5c4f", "proportion": 0.0012206286237412267 }, { "hex": "#f27400", "proportion": 0 } ], "prominent": "#ff181b", "swatches": { "dark_muted": null, "dark_vibrant": null, "light_muted": "#ffbbbd", "light_vibrant": "#ff7a6b", "muted": "#ff9ea3", "vibrant": "#ff181b" } }, "description": "The flag of Canada is composed of a red vertical band on the hoist and fly sides and a central white square that is twice the width of the vertical bands. A large eleven-pointed red maple leaf is centered in the white square.", "emoji": "\ud83c\udde8\ud83c\udde6", "html_entity": "🇨🇦", "unicode": "U+1F1E8 U+1F1E6", "url_png": "https://flags.restcountries.com/v5/w640/ca.png", "url_svg": "https://flags.restcountries.com/v5/svg/ca.svg" }, "government_type": "Federal parliamentary constitutional monarchy", "landlocked": false, "languages": [ { "bcp47": "en", "iso639_1": "en", "iso639_2b": "eng", "iso639_2t": "eng", "iso639_3": "eng", "name": "English", "native_name": "English" }, { "bcp47": "fr", "iso639_1": "fr", "iso639_2b": "fre", "iso639_2t": "fra", "iso639_3": "fra", "name": "French", "native_name": "fran\u00e7ais" } ], "leaders": [ { "assets": { "wikipedia.article.open_graph_image": { "renditions": [ { "content_hash": "1a9955aacbfd63c81aeb0f2317dd3faf", "content_type": "image/webp", "filesize": 7646, "height": 256, "max_edge": 256, "url": "https://assets-03.restcountries.com/assets.00/asst85zaqnak/charles-iii-182x256.webp", "width": 182 } ], "source": "wikipedia", "type": "article.open_graph_image" } }, "attributes": { "administers_executive": false, "de_facto_executive": false, "head_of_government": false, "head_of_state": true, "is_representative": false, "pending_office": false, "provisional": false }, "links": { "wikipedia": "https://en.wikipedia.org/wiki/Charles_III" }, "name": "Charles III", "title": "Monarch", "uuid": "861547aa-d5cd-5dd0-ba76-b58a1dfae3f0" }, { "assets": { "wikipedia.article.open_graph_image": { "renditions": [ { "content_hash": "f93f3d869d61cbe530e8cdc98b803473", "content_type": "image/webp", "filesize": 8010, "height": 256, "max_edge": 256, "url": "https://assets-03.restcountries.com/assets.00/asstru9leop5/louise-arbour-171x256.webp", "width": 171 } ], "source": "wikipedia", "type": "article.open_graph_image" } }, "attributes": { "administers_executive": false, "de_facto_executive": false, "head_of_government": false, "head_of_state": true, "is_representative": true, "pending_office": false, "provisional": false }, "links": { "wikipedia": "https://en.wikipedia.org/wiki/Louise_Arbour" }, "name": "Louise Arbour", "title": "Governor General", "uuid": "6e79fcc8-c2af-5510-b0ef-a8f4ede96059" }, { "assets": { "wikipedia.article.open_graph_image": { "renditions": [ { "content_hash": "455c86374739a59b12544f7d680c6040", "content_type": "image/webp", "filesize": 6150, "height": 256, "max_edge": 256, "url": "https://assets-03.restcountries.com/assets.00/assti2l9gpkk/mark-carney-192x256.webp", "width": 192 } ], "source": "wikipedia", "type": "article.open_graph_image" } }, "attributes": { "administers_executive": true, "de_facto_executive": false, "head_of_government": true, "head_of_state": false, "is_representative": false, "pending_office": false, "provisional": false }, "links": { "wikipedia": "https://en.wikipedia.org/wiki/Mark_Carney" }, "name": "Mark Carney", "title": "Prime Minister", "uuid": "146fc918-3dab-56a7-8e0e-ebf42865aa89" } ], "links": { "google_maps": "https://goo.gl/maps/jmEVLugreeqiZXxbA", "official": "https://www.canada.ca", "open_street_maps": "https://www.openstreetmap.org/relation/1428125", "wikipedia": "https://en.wikipedia.org/wiki/Canada" }, "memberships": { "african_union": false, "arab_league": false, "asean": false, "brics": false, "commonwealth": true, "eu": false, "eurozone": false, "g20": true, "g7": true, "nato": true, "oecd": true, "opec": false, "schengen": false, "un": true }, "names": { "alternates": [], "common": "Canada", "native": { "eng": { "common": "Canada", "official": "Canada" }, "fra": { "common": "Canada", "official": "Canada" } }, "official": "Canada", "translations": { "deu": { "common": "Kanada", "official": "Kanada" }, "fra": { "common": "Canada", "official": "Canada" }, "jpn": { "common": "\u30ab\u30ca\u30c0", "official": "\u30ab\u30ca\u30c0" }, "spa": { "common": "Canad\u00e1", "official": "Canad\u00e1" }, "zho": { "common": "\u52a0\u62ff\u5927", "official": "\u52a0\u62ff\u5927" } } }, "number_format": { "decimal_separator": ".", "thousands_separator": "," }, "parent": { "alpha_2": "", "alpha_3": "" }, "population": 41798407, "postal_code": { "format": "@#@ #@#", "regex": "^([ABCEGHJKLMNPRSTVXY]\\d[ABCEGHJKLMNPRSTVWXYZ]) ?(\\d[ABCEGHJKLMNPRSTVWXYZ]\\d)$" }, "region": "Americas", "subregion": "North America", "timezones": [ "UTC-08:00", "UTC-07:00", "UTC-06:00", "UTC-05:00", "UTC-04:00", "UTC-03:30" ], "tlds": [ ".ca" ], "units": { "measurement_system": "metric", "temperature_scale": "Celsius" }, "uuid": "189581ed-44b0-47d7-9849-6b097401a7d6" } ``` ### Get country by code Look up one country by its ISO 3166-1 code: two letters (CA), three letters (CAN) or three digits (124). Returns everything REST Countries has on it: names, capital, region, population, currencies, languages, calling codes, time zones, flag and more. **Inputs** - Country code (`code`, text, required): The country's ISO code: two letters, three letters or three digits. - Fields (`fields`, text): Only these fields, to keep the result small: paths separated by commas, like names.common, codes.alpha_2, flag.url_png. Leave it empty for all of them. **Outputs**: A country, as REST Countries describes it. With Fields set, only those fields are present - `_meta` (object): About the record itself - `area` (object): Its land area - `assets` (list): Images of the country, where there are any - `borders` (list): Alpha-3 codes of the countries it shares a land border with - `calling_codes` (list): International calling codes, e.g. '1' or '44' - `capitals` (list): Its capital cities, usually one - `cars` (object): Road traffic - `classification` (object): What kind of entity it is - `codes` (object): The country's codes - `continents` (list): The continents it is on - `coordinates` (object): Where its geographic center is - `currencies` (list): The currencies it officially uses - `date` (object): Calendar conventions - `demonyms` (object): What its people are called, keyed by ISO 639-3 code, each with masculine (m) and feminine (f) forms - `descriptions` (object): Descriptions of the country - `economy` (object): Economic figures - `flag` (object): The country's flag - `government_type` (text): The type of government in power - `landlocked` (true/false): True when it has no coastline - `languages` (list): The languages used in the country - `leaders` (list): Its current political leaders. Paid plans only: on the free plan this holds a notice instead - `links` (object): Links about the country - `memberships` (object): Which organizations it belongs to - `names` (object): The country's names - `number_format` (object): How numbers are written - `parent` (object): The country a dependency belongs to; empty codes otherwise - `population` (number): Population, from the country's own official figures - `postal_code` (object): Postal codes - `region` (text): Region: Africa, Americas, Antarctic, Asia, Europe or Oceania - `subregion` (text): Subregion, e.g. 'North America' or 'Western Europe' - `timezones` (list): The UTC offsets it observes, e.g. 'UTC-05:00' - `tlds` (list): Its internet domains, e.g. '.ca' - `units` (object): Units in everyday use - `uuid` (text): REST Countries' identifier for the record **Example output** ```json { "_meta": { "lastUpdatedTimestamp": 1790182685 }, "area": { "kilometers": 9984670, "miles": 3855101.1 }, "assets": [], "borders": [ "USA" ], "calling_codes": [ "1" ], "capitals": [ { "attributes": { "administrative": false, "constitutional": false, "executive": false, "judicial": false, "legislative": false, "primary": true }, "coordinates": { "lat": 45.42, "lng": -75.7 }, "name": "Ottawa" } ], "cars": { "driving_side": "right", "signs": [ "CDN" ] }, "classification": { "dependency": false, "dependency_type": "", "disputed": false, "iso_status": "official", "sovereign": true, "un_member": true, "un_observer": false }, "codes": { "alpha_2": "CA", "alpha_3": "CAN", "ccn3": "124", "cioc": "CAN", "fifa": "CAN", "fips": "CA", "gec": "CA" }, "continents": [ "North America" ], "coordinates": { "lat": 60, "lng": -95 }, "currencies": [ { "code": "CAD", "name": "Canadian dollar", "symbol": "$" } ], "date": { "academic_year_start": { "day": 1, "month": 9 }, "fiscal_year_start": { "corporate": { "basis": "convention", "day": 1, "month": 1 }, "government": { "day": 1, "month": 4 }, "personal": { "day": 1, "month": 1 } }, "start_of_week": "sunday" }, "demonyms": { "eng": { "f": "Canadian", "m": "Canadian" }, "fra": { "f": "Canadienne", "m": "Canadien" } }, "descriptions": { "long": "Canada is a Commonwealth realm with Ottawa as its capital and English and French as official languages. The Canadian dollar is the currency, and energy, minerals, forestry, manufacturing and services support a mostly southern population.", "short": "Canada is a federal parliamentary state in northern North America, second in the world by area." }, "economy": { "gini_coefficient": { "2018": 32.5, "2019": 31.8, "2020": 29.9, "2021": 31.1, "2022": 31.5 } }, "flag": { "colors": { "dominant": "#fcfaf5", "palette": [ { "hex": "#fcfaf5", "proportion": 0.35886481537992065 }, { "hex": "#ff181b", "proportion": 0.6341165700335673 }, { "hex": "#ff8d94", "proportion": 0.00183094293561184 }, { "hex": "#ff9ea3", "proportion": 0.0012206286237412267 }, { "hex": "#ffbbbd", "proportion": 0.00183094293561184 }, { "hex": "#ff7a6b", "proportion": 0.00091547146780592 }, { "hex": "#ff5c4f", "proportion": 0.0012206286237412267 }, { "hex": "#f27400", "proportion": 0 } ], "prominent": "#ff181b", "swatches": { "dark_muted": null, "dark_vibrant": null, "light_muted": "#ffbbbd", "light_vibrant": "#ff7a6b", "muted": "#ff9ea3", "vibrant": "#ff181b" } }, "description": "The flag of Canada is composed of a red vertical band on the hoist and fly sides and a central white square that is twice the width of the vertical bands. A large eleven-pointed red maple leaf is centered in the white square.", "emoji": "\ud83c\udde8\ud83c\udde6", "html_entity": "🇨🇦", "unicode": "U+1F1E8 U+1F1E6", "url_png": "https://flags.restcountries.com/v5/w640/ca.png", "url_svg": "https://flags.restcountries.com/v5/svg/ca.svg" }, "government_type": "Federal parliamentary constitutional monarchy", "landlocked": false, "languages": [ { "bcp47": "en", "iso639_1": "en", "iso639_2b": "eng", "iso639_2t": "eng", "iso639_3": "eng", "name": "English", "native_name": "English" }, { "bcp47": "fr", "iso639_1": "fr", "iso639_2b": "fre", "iso639_2t": "fra", "iso639_3": "fra", "name": "French", "native_name": "fran\u00e7ais" } ], "leaders": [ { "assets": { "wikipedia.article.open_graph_image": { "renditions": [ { "content_hash": "1a9955aacbfd63c81aeb0f2317dd3faf", "content_type": "image/webp", "filesize": 7646, "height": 256, "max_edge": 256, "url": "https://assets-03.restcountries.com/assets.00/asst85zaqnak/charles-iii-182x256.webp", "width": 182 } ], "source": "wikipedia", "type": "article.open_graph_image" } }, "attributes": { "administers_executive": false, "de_facto_executive": false, "head_of_government": false, "head_of_state": true, "is_representative": false, "pending_office": false, "provisional": false }, "links": { "wikipedia": "https://en.wikipedia.org/wiki/Charles_III" }, "name": "Charles III", "title": "Monarch", "uuid": "861547aa-d5cd-5dd0-ba76-b58a1dfae3f0" }, { "assets": { "wikipedia.article.open_graph_image": { "renditions": [ { "content_hash": "f93f3d869d61cbe530e8cdc98b803473", "content_type": "image/webp", "filesize": 8010, "height": 256, "max_edge": 256, "url": "https://assets-03.restcountries.com/assets.00/asstru9leop5/louise-arbour-171x256.webp", "width": 171 } ], "source": "wikipedia", "type": "article.open_graph_image" } }, "attributes": { "administers_executive": false, "de_facto_executive": false, "head_of_government": false, "head_of_state": true, "is_representative": true, "pending_office": false, "provisional": false }, "links": { "wikipedia": "https://en.wikipedia.org/wiki/Louise_Arbour" }, "name": "Louise Arbour", "title": "Governor General", "uuid": "6e79fcc8-c2af-5510-b0ef-a8f4ede96059" }, { "assets": { "wikipedia.article.open_graph_image": { "renditions": [ { "content_hash": "455c86374739a59b12544f7d680c6040", "content_type": "image/webp", "filesize": 6150, "height": 256, "max_edge": 256, "url": "https://assets-03.restcountries.com/assets.00/assti2l9gpkk/mark-carney-192x256.webp", "width": 192 } ], "source": "wikipedia", "type": "article.open_graph_image" } }, "attributes": { "administers_executive": true, "de_facto_executive": false, "head_of_government": true, "head_of_state": false, "is_representative": false, "pending_office": false, "provisional": false }, "links": { "wikipedia": "https://en.wikipedia.org/wiki/Mark_Carney" }, "name": "Mark Carney", "title": "Prime Minister", "uuid": "146fc918-3dab-56a7-8e0e-ebf42865aa89" } ], "links": { "google_maps": "https://goo.gl/maps/jmEVLugreeqiZXxbA", "official": "https://www.canada.ca", "open_street_maps": "https://www.openstreetmap.org/relation/1428125", "wikipedia": "https://en.wikipedia.org/wiki/Canada" }, "memberships": { "african_union": false, "arab_league": false, "asean": false, "brics": false, "commonwealth": true, "eu": false, "eurozone": false, "g20": true, "g7": true, "nato": true, "oecd": true, "opec": false, "schengen": false, "un": true }, "names": { "alternates": [], "common": "Canada", "native": { "eng": { "common": "Canada", "official": "Canada" }, "fra": { "common": "Canada", "official": "Canada" } }, "official": "Canada", "translations": { "deu": { "common": "Kanada", "official": "Kanada" }, "fra": { "common": "Canada", "official": "Canada" }, "jpn": { "common": "\u30ab\u30ca\u30c0", "official": "\u30ab\u30ca\u30c0" }, "spa": { "common": "Canad\u00e1", "official": "Canad\u00e1" }, "zho": { "common": "\u52a0\u62ff\u5927", "official": "\u52a0\u62ff\u5927" } } }, "number_format": { "decimal_separator": ".", "thousands_separator": "," }, "parent": { "alpha_2": "", "alpha_3": "" }, "population": 41798407, "postal_code": { "format": "@#@ #@#", "regex": "^([ABCEGHJKLMNPRSTVXY]\\d[ABCEGHJKLMNPRSTVWXYZ]) ?(\\d[ABCEGHJKLMNPRSTVWXYZ]\\d)$" }, "region": "Americas", "subregion": "North America", "timezones": [ "UTC-08:00", "UTC-07:00", "UTC-06:00", "UTC-05:00", "UTC-04:00", "UTC-03:30" ], "tlds": [ ".ca" ], "units": { "measurement_system": "metric", "temperature_scale": "Celsius" }, "uuid": "189581ed-44b0-47d7-9849-6b097401a7d6" } ``` ### Get exchange rates Get what one unit of a currency buys in every other currency REST Countries supports, or only in the ones you name, with when the rates are from. **Inputs** - Base currency (`base_currency`, text, required): The code of the currency the rates are for. - Only these currencies (`currencies`, text): Codes separated by commas, to get just their rates. Every currency's, if left empty. **Outputs** - `as_of` (text): When the rates were published, ISO 8601 in UTC - `base` (text): The base currency, e.g. 'USD' - `rates` (object): Currency code to how many of it one of the base buys, e.g. {'EUR': 0.877} **Example output** ```json { "as_of": "2026-09-30T00:00:00Z", "base": "USD", "rates": { "AUD": 1.43419687, "BTC": 1.202264e-05, "CAD": 1.41978985, "CHF": 0.83461957, "CNY": 6.70523387, "ETH": 0.00037466602, "EUR": 0.88243363, "GBP": 0.75598562, "INR": 95.96541915, "JPY": 157.136531, "MXN": 18.07260707, "USD": 1, "XAU": 0.0002391493 } } ``` ### Get favicon Get a link to a website's icon (its favicon) on REST Countries' free favicon CDN, from its domain, a web address or an email address, and whether the site has an icon of its own or the link shows the CDN's plain globe instead. Ready for an email, a message or a web page, and it uses none of the month's requests. **Inputs** - Website (`website`, text, required): The website's domain, like stripe.com. A web address or an email address works too: only its domain is used. **Outputs** - `domain` (text): The domain the icon is for, e.g. 'stripe.com': the one asked for, or the one above it if the CDN refused that - `has_icon` (true/false): True if the site has an icon of its own, false if the link shows the CDN's plain globe instead, and empty if that could not be checked - `url` (text): The icon's address on the free favicon CDN, e.g. 'https://favicon.restcountries.com/v1/stripe.com' **Example output** ```json { "domain": "stripe.com", "has_icon": true, "url": "https://favicon.restcountries.com/v1/stripe.com" } ``` ### Get flag image Get a link to a country's flag on REST Countries' free flag CDN, as PNG, JPG, GIF or SVG, from 160 to 2560 pixels wide, and cropped square or to 4:3 if you like. Ready for an email, a message or a web page, and it uses none of the month's requests. **Inputs** - Country code (`country_code`, text, required): The country's two-letter code. - Format (`image_format`, text): The image format. SVG scales to any size. One of: `png`, `jpg`, `gif`, `svg` (SVG (any size)). Default: `png`. - Width (`width`, text): How wide the image is. Another width rounds up to the next of these. Not used for SVG. One of: `160` (160 pixels), `320` (320 pixels), `640` (640 pixels), `1280` (1280 pixels), `2560` (2560 pixels). Default: `640`. - Shape (`shape`, text): The flag's own proportions, or cropped square or to 4:3. SVG comes only in its own proportions. One of: `original`, `square` (Square (1:1)), `4x3` (4:3). Default: `original`. **Outputs** - `country_code` (text): The country's two-letter code, e.g. 'CA' - `format` (text): png, jpg, gif or svg - `shape` (text): original, square or 4x3 - `url` (text): The image's address on the free flag CDN, e.g. 'https://flags.restcountries.com/v5/w640/ca.png' - `width` (number): Its width in pixels, or empty for an SVG **Example output** ```json { "country_code": "CA", "format": "png", "shape": "original", "url": "https://flags.restcountries.com/v5/w640/ca.png", "width": 640 } ``` ### List countries List countries alphabetically, a page at a time: all of them, or only those in a region or subregion, or those in groups like the EU, NATO or the G20, or landlocked ones. Each page says how many matched in all and which offset gets the next page. **Inputs** - Region (`region`, text): Only countries in this region. One of: `Africa`, `Americas`, `Antarctic`, `Asia`, `Europe`, `Oceania`. - Subregion (`subregion`, text): Only countries whose subregion contains this, like Western Europe, South America or Caribbean. - Only include (`only`, list): Only countries that are all of these, for example EU members that are landlocked. One or more of: `memberships.eu` (EU members), `memberships.eurozone` (Eurozone members), `memberships.schengen` (Schengen Area members), `memberships.nato` (NATO members), `memberships.un` (UN members), `memberships.commonwealth` (Commonwealth members), `memberships.oecd` (OECD members), `memberships.g7` (G7 members), `memberships.g20` (G20 members), `memberships.brics` (BRICS members), and 8 more. - Limit (`limit`, number): How many countries to return at most: up to 100 on the free plan, and 500 on paid plans. From 1 to 500. Default: `25`. - Offset (`offset`, number): How many matching countries to skip, to get a later page. Each result gives the offset of the page after it. At least 0. Default: `0`. - Fields (`fields`, text): Only these fields, to keep the result small: paths separated by commas, like names.common, codes.alpha_2, flag.url_png. Leave it empty for all of them. **Outputs** - `count` (number): How many are on this page - `countries` (list): The countries on this page, alphabetically - `has_more` (true/false): True when more countries matched than this page holds - `next_offset` (number): The offset that gets the next page, or empty on the last page - `offset` (number): How many matching countries came before this page - `total` (number): How many countries matched in all **Example output** ```json { "count": 1, "countries": [ { "_meta": { "lastUpdatedTimestamp": 1790182685 }, "area": { "kilometers": 9984670, "miles": 3855101.1 }, "assets": [], "borders": [ "USA" ], "calling_codes": [ "1" ], "capitals": [ { "attributes": { "administrative": false, "constitutional": false, "executive": false, "judicial": false, "legislative": false, "primary": true }, "coordinates": { "lat": 45.42, "lng": -75.7 }, "name": "Ottawa" } ], "cars": { "driving_side": "right", "signs": [ "CDN" ] }, "classification": { "dependency": false, "dependency_type": "", "disputed": false, "iso_status": "official", "sovereign": true, "un_member": true, "un_observer": false }, "codes": { "alpha_2": "CA", "alpha_3": "CAN", "ccn3": "124", "cioc": "CAN", "fifa": "CAN", "fips": "CA", "gec": "CA" }, "continents": [ "North America" ], "coordinates": { "lat": 60, "lng": -95 }, "currencies": [ { "code": "CAD", "name": "Canadian dollar", "symbol": "$" } ], "date": { "academic_year_start": { "day": 1, "month": 9 }, "fiscal_year_start": { "corporate": { "basis": "convention", "day": 1, "month": 1 }, "government": { "day": 1, "month": 4 }, "personal": { "day": 1, "month": 1 } }, "start_of_week": "sunday" }, "demonyms": { "eng": { "f": "Canadian", "m": "Canadian" }, "fra": { "f": "Canadienne", "m": "Canadien" } }, "descriptions": { "long": "Canada is a Commonwealth realm with Ottawa as its capital and English and French as official languages. The Canadian dollar is the currency, and energy, minerals, forestry, manufacturing and services support a mostly southern population.", "short": "Canada is a federal parliamentary state in northern North America, second in the world by area." }, "economy": { "gini_coefficient": { "2018": 32.5, "2019": 31.8, "2020": 29.9, "2021": 31.1, "2022": 31.5 } }, "flag": { "colors": { "dominant": "#fcfaf5", "palette": [ { "hex": "#fcfaf5", "proportion": 0.35886481537992065 }, { "hex": "#ff181b", "proportion": 0.6341165700335673 }, { "hex": "#ff8d94", "proportion": 0.00183094293561184 }, { "hex": "#ff9ea3", "proportion": 0.0012206286237412267 }, { "hex": "#ffbbbd", "proportion": 0.00183094293561184 }, { "hex": "#ff7a6b", "proportion": 0.00091547146780592 }, { "hex": "#ff5c4f", "proportion": 0.0012206286237412267 }, { "hex": "#f27400", "proportion": 0 } ], "prominent": "#ff181b", "swatches": { "dark_muted": null, "dark_vibrant": null, "light_muted": "#ffbbbd", "light_vibrant": "#ff7a6b", "muted": "#ff9ea3", "vibrant": "#ff181b" } }, "description": "The flag of Canada is composed of a red vertical band on the hoist and fly sides and a central white square that is twice the width of the vertical bands. A large eleven-pointed red maple leaf is centered in the white square.", "emoji": "\ud83c\udde8\ud83c\udde6", "html_entity": "🇨🇦", "unicode": "U+1F1E8 U+1F1E6", "url_png": "https://flags.restcountries.com/v5/w640/ca.png", "url_svg": "https://flags.restcountries.com/v5/svg/ca.svg" }, "government_type": "Federal parliamentary constitutional monarchy", "landlocked": false, "languages": [ { "bcp47": "en", "iso639_1": "en", "iso639_2b": "eng", "iso639_2t": "eng", "iso639_3": "eng", "name": "English", "native_name": "English" }, { "bcp47": "fr", "iso639_1": "fr", "iso639_2b": "fre", "iso639_2t": "fra", "iso639_3": "fra", "name": "French", "native_name": "fran\u00e7ais" } ], "leaders": [ { "assets": { "wikipedia.article.open_graph_image": { "renditions": [ { "content_hash": "1a9955aacbfd63c81aeb0f2317dd3faf", "content_type": "image/webp", "filesize": 7646, "height": 256, "max_edge": 256, "url": "https://assets-03.restcountries.com/assets.00/asst85zaqnak/charles-iii-182x256.webp", "width": 182 } ], "source": "wikipedia", "type": "article.open_graph_image" } }, "attributes": { "administers_executive": false, "de_facto_executive": false, "head_of_government": false, "head_of_state": true, "is_representative": false, "pending_office": false, "provisional": false }, "links": { "wikipedia": "https://en.wikipedia.org/wiki/Charles_III" }, "name": "Charles III", "title": "Monarch", "uuid": "861547aa-d5cd-5dd0-ba76-b58a1dfae3f0" }, { "assets": { "wikipedia.article.open_graph_image": { "renditions": [ { "content_hash": "f93f3d869d61cbe530e8cdc98b803473", "content_type": "image/webp", "filesize": 8010, "height": 256, "max_edge": 256, "url": "https://assets-03.restcountries.com/assets.00/asstru9leop5/louise-arbour-171x256.webp", "width": 171 } ], "source": "wikipedia", "type": "article.open_graph_image" } }, "attributes": { "administers_executive": false, "de_facto_executive": false, "head_of_government": false, "head_of_state": true, "is_representative": true, "pending_office": false, "provisional": false }, "links": { "wikipedia": "https://en.wikipedia.org/wiki/Louise_Arbour" }, "name": "Louise Arbour", "title": "Governor General", "uuid": "6e79fcc8-c2af-5510-b0ef-a8f4ede96059" }, { "assets": { "wikipedia.article.open_graph_image": { "renditions": [ { "content_hash": "455c86374739a59b12544f7d680c6040", "content_type": "image/webp", "filesize": 6150, "height": 256, "max_edge": 256, "url": "https://assets-03.restcountries.com/assets.00/assti2l9gpkk/mark-carney-192x256.webp", "width": 192 } ], "source": "wikipedia", "type": "article.open_graph_image" } }, "attributes": { "administers_executive": true, "de_facto_executive": false, "head_of_government": true, "head_of_state": false, "is_representative": false, "pending_office": false, "provisional": false }, "links": { "wikipedia": "https://en.wikipedia.org/wiki/Mark_Carney" }, "name": "Mark Carney", "title": "Prime Minister", "uuid": "146fc918-3dab-56a7-8e0e-ebf42865aa89" } ], "links": { "google_maps": "https://goo.gl/maps/jmEVLugreeqiZXxbA", "official": "https://www.canada.ca", "open_street_maps": "https://www.openstreetmap.org/relation/1428125", "wikipedia": "https://en.wikipedia.org/wiki/Canada" }, "memberships": { "african_union": false, "arab_league": false, "asean": false, "brics": false, "commonwealth": true, "eu": false, "eurozone": false, "g20": true, "g7": true, "nato": true, "oecd": true, "opec": false, "schengen": false, "un": true }, "names": { "alternates": [], "common": "Canada", "native": { "eng": { "common": "Canada", "official": "Canada" }, "fra": { "common": "Canada", "official": "Canada" } }, "official": "Canada", "translations": { "deu": { "common": "Kanada", "official": "Kanada" }, "fra": { "common": "Canada", "official": "Canada" }, "jpn": { "common": "\u30ab\u30ca\u30c0", "official": "\u30ab\u30ca\u30c0" }, "spa": { "common": "Canad\u00e1", "official": "Canad\u00e1" }, "zho": { "common": "\u52a0\u62ff\u5927", "official": "\u52a0\u62ff\u5927" } } }, "number_format": { "decimal_separator": ".", "thousands_separator": "," }, "parent": { "alpha_2": "", "alpha_3": "" }, "population": 41798407, "postal_code": { "format": "@#@ #@#", "regex": "^([ABCEGHJKLMNPRSTVXY]\\d[ABCEGHJKLMNPRSTVWXYZ]) ?(\\d[ABCEGHJKLMNPRSTVWXYZ]\\d)$" }, "region": "Americas", "subregion": "North America", "timezones": [ "UTC-08:00", "UTC-07:00", "UTC-06:00", "UTC-05:00", "UTC-04:00", "UTC-03:30" ], "tlds": [ ".ca" ], "units": { "measurement_system": "metric", "temperature_scale": "Celsius" }, "uuid": "189581ed-44b0-47d7-9849-6b097401a7d6" } ], "has_more": false, "next_offset": null, "offset": 0, "total": 1 } ``` ### List currencies List every currency REST Countries converts, fiat and crypto, with its code, name and symbol. **Inputs**: None. **Outputs** - `count` (number): How many currencies there are - `currencies` (list): Every supported currency, by code **Example output** ```json { "count": 8, "currencies": [ { "code": "BTC", "name": "Bitcoin", "symbol": "\u20bf" }, { "code": "CAD", "name": "Canadian dollar", "symbol": "$" }, { "code": "ETH", "name": "Ethereum", "symbol": "\u039e" }, { "code": "EUR", "name": "Euro", "symbol": "\u20ac" }, { "code": "GBP", "name": "British pound", "symbol": "\u00a3" }, { "code": "JPY", "name": "Japanese yen", "symbol": "\u00a5" }, { "code": "USD", "name": "United States dollar", "symbol": "$" }, { "code": "XAU", "name": "Gold (troy ounce)", "symbol": null } ] } ``` ### Look up IP address Find where an IPv4 or IPv6 address is (continent, country, region, city, postal code and coordinates), which network runs it, whether it is a Tor exit node, a proxy, a VPN or a data center, and its local time zone. **Inputs** - IP address (`ip_address`, text, required): A public IPv4 or IPv6 address. **Outputs** - `connection` (object): The network the address belongs to - `ip` (text): The address looked up - `location` (object): Where the address is. A value that is not known is empty - `security` (object): Reputation flags. Empty means unknown, not no - `timezone` (object) - `type` (text): IPv4 or IPv6 **Example output** ```json { "connection": { "asn": { "number": 577 }, "domain": "bell.ca", "organization": { "name": "Bell Canada" } }, "ip": "216.209.248.188", "location": { "city": { "name": "Toronto" }, "continent": { "codes": { "common": "NA" }, "name": "North America" }, "coordinates": { "lat": 43.70643, "lng": -79.39864 }, "country": { "attributes": { "is_eu": false }, "codes": { "alpha_2": "CA" }, "flag": { "emoji": "\ud83c\udde8\ud83c\udde6", "html_entity": "🇨🇦", "url_png": "https://flags.restcountries.com/v5/w640/ca.png", "url_svg": "https://flags.restcountries.com/v5/svg/ca.svg" }, "name": "Canada" }, "label": "Toronto, Ontario", "postal": { "code": "M2J" }, "subdivision": { "codes": { "common": "ON", "iso_3166_2": "CA-ON" }, "name": "Ontario" } }, "security": { "anonymous": false, "data_center": false, "proxy": false, "tor": false, "vpn": null }, "timezone": { "current": { "abbreviation": "EDT", "attributes": { "is_dst": true }, "offset": { "iso_8601": "-04:00", "seconds": -14400 } }, "id": "America/Toronto" }, "type": "IPv4" } ``` ### Parse user agent Identify the browser, rendering engine, operating system and device behind a user-agent string, and whether it is a bot, a search or AI crawler, or an AI assistant fetching a page for someone, along with the company it acts for. **Inputs** - User agent (`user_agent`, text, required): The User-Agent header's value, as a browser or bot sent it. - Client hints (`client_hints`, object): Optional Sec-CH-UA headers the browser sent with it, which name the device model and system version that Chrome leaves out of the user agent. Other headers are ignored, so a request's whole header map can be passed. **Outputs** - `client` (object): The software making the requests - `device` (object): The hardware - `flags` (object): What kind of agent it is. False means not established - `label` (text): A summary ready to show, e.g. 'Chrome on macOS' - `operator` (object): Who a bot or in-app browser acts for. Empty for an ordinary browser - `os` (object): The operating system, or empty when the string names none - `ua` (text): The user-agent string parsed **Example output** ```json { "client": { "attributes": { "is_android": false, "is_chrome": true, "is_chromium": false, "is_chromium_based": true, "is_edge": false, "is_firefox": false, "is_headless": false, "is_internet_explorer": false, "is_opera": false, "is_safari": false, "is_web_view": false }, "engine": { "label": "Google Blink (v150)", "logo": { "url_svg": "https://brands.restcountries.com/v1/svg/blink/logo.svg" }, "maker": { "links": { "official": "https://www.google.com/", "wikipedia": "https://en.wikipedia.org/wiki/Google" }, "logo": { "url_svg": "https://brands.restcountries.com/v1/svg/google/logo.svg" }, "name": "Google", "wordmark": { "url_svg": "https://brands.restcountries.com/v1/svg/google/wordmark.svg" } }, "name": "Blink", "version": { "full": "150.0.0.0", "major": 150 }, "wordmark": null }, "label": "Google Chrome (v150)", "logo": { "url_svg": "https://brands.restcountries.com/v1/svg/chrome/logo.svg" }, "maker": { "links": { "official": "https://www.google.com/", "wikipedia": "https://en.wikipedia.org/wiki/Google" }, "logo": { "url_svg": "https://brands.restcountries.com/v1/svg/google/logo.svg" }, "name": "Google", "wordmark": { "url_svg": "https://brands.restcountries.com/v1/svg/google/wordmark.svg" } }, "name": "Chrome", "type": "browser", "version": { "full": "150.0.0.0", "major": 150 }, "wordmark": { "url_svg": "https://brands.restcountries.com/v1/svg/chrome/wordmark.svg" } }, "device": { "attributes": { "is_camera": false, "is_desktop": true, "is_media_player": false, "is_mobile": false, "is_phone": false, "is_set_top_box": false, "is_smart_tv": false, "is_tablet": false, "is_watch": false, "is_wearable": false }, "label": "Apple Macintosh", "maker": { "links": { "official": "https://www.apple.com/", "wikipedia": "https://en.wikipedia.org/wiki/Apple_Inc." }, "logo": { "url_svg": "https://brands.restcountries.com/v1/svg/apple/logo.svg" }, "name": "Apple", "wordmark": { "url_svg": "https://brands.restcountries.com/v1/svg/apple/wordmark.svg" } }, "name": "Macintosh", "type": "desktop" }, "flags": { "is_ai_assistant": false, "is_ai_crawler": false, "is_bot": false, "is_crawler": false }, "label": "Chrome on macOS", "operator": null, "os": { "label": "Apple macOS (v10)", "logo": { "url_svg": "https://brands.restcountries.com/v1/svg/macos/logo.svg" }, "maker": { "links": { "official": "https://www.apple.com/", "wikipedia": "https://en.wikipedia.org/wiki/Apple_Inc." }, "logo": { "url_svg": "https://brands.restcountries.com/v1/svg/apple/logo.svg" }, "name": "Apple", "wordmark": { "url_svg": "https://brands.restcountries.com/v1/svg/apple/wordmark.svg" } }, "name": "macOS", "version": { "full": "10.15.7", "major": 10 }, "wordmark": { "url_svg": "https://brands.restcountries.com/v1/svg/macos/wordmark.svg" } }, "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/150.0.0.0 Safari/537.36" } ``` ### Search countries Find every country with the text anywhere in it, ignoring case: in any field, or only in names, codes, capitals, demonyms, languages, currencies, flag descriptions or government types. Results come alphabetically, a page at a time. **Inputs** - Search text (`query`, text, required): The text to look for, or part of it, like 'land' or 'ger'. - Search in (`search_in`, text): Where to look for the text. Everything, if not chosen. One of: `all` (Everything), `name` (Names (common, official, alternate and native)), `code` (Codes (ISO, FIPS, FIFA and Olympic)), `capitals` (Capital cities), `names.translations` (Names in other languages), `demonyms` (Demonyms (what the people are called)), `languages`, `currencies`, `flag.description` (Flag descriptions), `government_type` (Government type), `leaders` (Current leaders (paid plans)). Default: `all`. - Limit (`limit`, number): How many countries to return at most: up to 100 on the free plan, and 500 on paid plans. From 1 to 500. Default: `25`. - Offset (`offset`, number): How many matching countries to skip, to get a later page. Each result gives the offset of the page after it. At least 0. Default: `0`. - Fields (`fields`, text): Only these fields, to keep the result small: paths separated by commas, like names.common, codes.alpha_2, flag.url_png. Leave it empty for all of them. **Outputs** - `count` (number): How many are on this page - `countries` (list): The countries on this page, alphabetically - `has_more` (true/false): True when more countries matched than this page holds - `next_offset` (number): The offset that gets the next page, or empty on the last page - `offset` (number): How many matching countries came before this page - `total` (number): How many countries matched in all **Example output** ```json { "count": 1, "countries": [ { "_meta": { "lastUpdatedTimestamp": 1790182685 }, "area": { "kilometers": 9984670, "miles": 3855101.1 }, "assets": [], "borders": [ "USA" ], "calling_codes": [ "1" ], "capitals": [ { "attributes": { "administrative": false, "constitutional": false, "executive": false, "judicial": false, "legislative": false, "primary": true }, "coordinates": { "lat": 45.42, "lng": -75.7 }, "name": "Ottawa" } ], "cars": { "driving_side": "right", "signs": [ "CDN" ] }, "classification": { "dependency": false, "dependency_type": "", "disputed": false, "iso_status": "official", "sovereign": true, "un_member": true, "un_observer": false }, "codes": { "alpha_2": "CA", "alpha_3": "CAN", "ccn3": "124", "cioc": "CAN", "fifa": "CAN", "fips": "CA", "gec": "CA" }, "continents": [ "North America" ], "coordinates": { "lat": 60, "lng": -95 }, "currencies": [ { "code": "CAD", "name": "Canadian dollar", "symbol": "$" } ], "date": { "academic_year_start": { "day": 1, "month": 9 }, "fiscal_year_start": { "corporate": { "basis": "convention", "day": 1, "month": 1 }, "government": { "day": 1, "month": 4 }, "personal": { "day": 1, "month": 1 } }, "start_of_week": "sunday" }, "demonyms": { "eng": { "f": "Canadian", "m": "Canadian" }, "fra": { "f": "Canadienne", "m": "Canadien" } }, "descriptions": { "long": "Canada is a Commonwealth realm with Ottawa as its capital and English and French as official languages. The Canadian dollar is the currency, and energy, minerals, forestry, manufacturing and services support a mostly southern population.", "short": "Canada is a federal parliamentary state in northern North America, second in the world by area." }, "economy": { "gini_coefficient": { "2018": 32.5, "2019": 31.8, "2020": 29.9, "2021": 31.1, "2022": 31.5 } }, "flag": { "colors": { "dominant": "#fcfaf5", "palette": [ { "hex": "#fcfaf5", "proportion": 0.35886481537992065 }, { "hex": "#ff181b", "proportion": 0.6341165700335673 }, { "hex": "#ff8d94", "proportion": 0.00183094293561184 }, { "hex": "#ff9ea3", "proportion": 0.0012206286237412267 }, { "hex": "#ffbbbd", "proportion": 0.00183094293561184 }, { "hex": "#ff7a6b", "proportion": 0.00091547146780592 }, { "hex": "#ff5c4f", "proportion": 0.0012206286237412267 }, { "hex": "#f27400", "proportion": 0 } ], "prominent": "#ff181b", "swatches": { "dark_muted": null, "dark_vibrant": null, "light_muted": "#ffbbbd", "light_vibrant": "#ff7a6b", "muted": "#ff9ea3", "vibrant": "#ff181b" } }, "description": "The flag of Canada is composed of a red vertical band on the hoist and fly sides and a central white square that is twice the width of the vertical bands. A large eleven-pointed red maple leaf is centered in the white square.", "emoji": "\ud83c\udde8\ud83c\udde6", "html_entity": "🇨🇦", "unicode": "U+1F1E8 U+1F1E6", "url_png": "https://flags.restcountries.com/v5/w640/ca.png", "url_svg": "https://flags.restcountries.com/v5/svg/ca.svg" }, "government_type": "Federal parliamentary constitutional monarchy", "landlocked": false, "languages": [ { "bcp47": "en", "iso639_1": "en", "iso639_2b": "eng", "iso639_2t": "eng", "iso639_3": "eng", "name": "English", "native_name": "English" }, { "bcp47": "fr", "iso639_1": "fr", "iso639_2b": "fre", "iso639_2t": "fra", "iso639_3": "fra", "name": "French", "native_name": "fran\u00e7ais" } ], "leaders": [ { "assets": { "wikipedia.article.open_graph_image": { "renditions": [ { "content_hash": "1a9955aacbfd63c81aeb0f2317dd3faf", "content_type": "image/webp", "filesize": 7646, "height": 256, "max_edge": 256, "url": "https://assets-03.restcountries.com/assets.00/asst85zaqnak/charles-iii-182x256.webp", "width": 182 } ], "source": "wikipedia", "type": "article.open_graph_image" } }, "attributes": { "administers_executive": false, "de_facto_executive": false, "head_of_government": false, "head_of_state": true, "is_representative": false, "pending_office": false, "provisional": false }, "links": { "wikipedia": "https://en.wikipedia.org/wiki/Charles_III" }, "name": "Charles III", "title": "Monarch", "uuid": "861547aa-d5cd-5dd0-ba76-b58a1dfae3f0" }, { "assets": { "wikipedia.article.open_graph_image": { "renditions": [ { "content_hash": "f93f3d869d61cbe530e8cdc98b803473", "content_type": "image/webp", "filesize": 8010, "height": 256, "max_edge": 256, "url": "https://assets-03.restcountries.com/assets.00/asstru9leop5/louise-arbour-171x256.webp", "width": 171 } ], "source": "wikipedia", "type": "article.open_graph_image" } }, "attributes": { "administers_executive": false, "de_facto_executive": false, "head_of_government": false, "head_of_state": true, "is_representative": true, "pending_office": false, "provisional": false }, "links": { "wikipedia": "https://en.wikipedia.org/wiki/Louise_Arbour" }, "name": "Louise Arbour", "title": "Governor General", "uuid": "6e79fcc8-c2af-5510-b0ef-a8f4ede96059" }, { "assets": { "wikipedia.article.open_graph_image": { "renditions": [ { "content_hash": "455c86374739a59b12544f7d680c6040", "content_type": "image/webp", "filesize": 6150, "height": 256, "max_edge": 256, "url": "https://assets-03.restcountries.com/assets.00/assti2l9gpkk/mark-carney-192x256.webp", "width": 192 } ], "source": "wikipedia", "type": "article.open_graph_image" } }, "attributes": { "administers_executive": true, "de_facto_executive": false, "head_of_government": true, "head_of_state": false, "is_representative": false, "pending_office": false, "provisional": false }, "links": { "wikipedia": "https://en.wikipedia.org/wiki/Mark_Carney" }, "name": "Mark Carney", "title": "Prime Minister", "uuid": "146fc918-3dab-56a7-8e0e-ebf42865aa89" } ], "links": { "google_maps": "https://goo.gl/maps/jmEVLugreeqiZXxbA", "official": "https://www.canada.ca", "open_street_maps": "https://www.openstreetmap.org/relation/1428125", "wikipedia": "https://en.wikipedia.org/wiki/Canada" }, "memberships": { "african_union": false, "arab_league": false, "asean": false, "brics": false, "commonwealth": true, "eu": false, "eurozone": false, "g20": true, "g7": true, "nato": true, "oecd": true, "opec": false, "schengen": false, "un": true }, "names": { "alternates": [], "common": "Canada", "native": { "eng": { "common": "Canada", "official": "Canada" }, "fra": { "common": "Canada", "official": "Canada" } }, "official": "Canada", "translations": { "deu": { "common": "Kanada", "official": "Kanada" }, "fra": { "common": "Canada", "official": "Canada" }, "jpn": { "common": "\u30ab\u30ca\u30c0", "official": "\u30ab\u30ca\u30c0" }, "spa": { "common": "Canad\u00e1", "official": "Canad\u00e1" }, "zho": { "common": "\u52a0\u62ff\u5927", "official": "\u52a0\u62ff\u5927" } } }, "number_format": { "decimal_separator": ".", "thousands_separator": "," }, "parent": { "alpha_2": "", "alpha_3": "" }, "population": 41798407, "postal_code": { "format": "@#@ #@#", "regex": "^([ABCEGHJKLMNPRSTVXY]\\d[ABCEGHJKLMNPRSTVWXYZ]) ?(\\d[ABCEGHJKLMNPRSTVWXYZ]\\d)$" }, "region": "Americas", "subregion": "North America", "timezones": [ "UTC-08:00", "UTC-07:00", "UTC-06:00", "UTC-05:00", "UTC-04:00", "UTC-03:30" ], "tlds": [ ".ca" ], "units": { "measurement_system": "metric", "temperature_scale": "Celsius" }, "uuid": "189581ed-44b0-47d7-9849-6b097401a7d6" } ], "has_more": false, "next_offset": null, "offset": 0, "total": 1 } ```