Country Lookup

Returns reference information about a country from its two-letter ISO code.

Overview#

lookup/country takes CountryCode in ISO 3166-1 alpha-2 form, such as GB or US, and returns static facts about that country: countryName, the numeric geographic ID, capital, population, international phoneCode, currency (name, code and symbol), the main language, and the timezone information of the country with sun times. It is reference data, not a risk assessment, and it does not involve any visitor IP.

When to use it#

• Populate country, currency or dial-code selectors from a single source.
• Show the local currency or language after the user picks a country.
• Normalize a country code you received from another system before storing or comparing it.

Reading the result#

• Use countryCode as the canonical key and countryName for display.
• phoneCode is the calling prefix without the plus sign; combine it with the national number when you build an international phone value, then verify the result with Phone Validation.
• currency.currencyCode is the ISO 4217 code, convenient for pricing and for comparing against the transaction_currency you send to Payment Fraud Detection.
• The timezone block describes one representative zone, so countries with several zones should not be treated as a single offset.

Notes#

• Counts as one request. Test mode returns fake data, is free and contacts no external service.
• Included in every plan, including Standard.
• It raises no events and has no custom rules or blacklist support.
• A missing code or a code that is not a valid alpha-2 country returns error 116 (invalid_country_code) with HTTP 200.
• Because the data changes rarely, cache the response on your side instead of calling the method for every page view.

Request#

• Authenticate with the key parameter or an Authorization: Bearer header.
• Counts as 1 request.
• Available on: Free trial Standard Premium Pay-as-you-go

Parameters#

Every method also accepts format, lang, mode, userID, callback. See Options.

Code samples#

curl -G "https://gurdx.cretip.com/api/lookup/country" \
  --data-urlencode "key=YOUR_API_KEY" \
  --data-urlencode "CountryCode=SA"

<?php

$response = file_get_contents('https://gurdx.cretip.com/api/lookup/country?'.http_build_query(['key' => 'YOUR_API_KEY', 'CountryCode' => 'SA']));
$result = json_decode($response, true);

if ($result['status'] === 'success') {
    print_r($result['data']);
} else {
    echo $result['code'].': '.$result['description'];
}

const params = new URLSearchParams({"key":"YOUR_API_KEY","CountryCode":"SA"});
const res = await fetch(`https://gurdx.cretip.com/api/lookup/country?${params}`);
const result = await res.json();

if (result.status === 'success') {
  console.log(result.data);
} else {
  console.error(result.code, result.description);
}

import requests

res = requests.get("https://gurdx.cretip.com/api/lookup/country", params={"key": "YOUR_API_KEY", "CountryCode": "SA"})
result = res.json()

if result["status"] == "success":
    print(result["data"])
else:
    print(result["code"], result["description"])

Response#

Success#

{
    "data": {
        "countryCode": "US",
        "countryName": "United States",
        "countryGeoNameID": 6252001,
        "capital": "Washington, D.C.",
        "population": 331000000,
        "phoneCode": "1",
        "currency": {
            "currencyName": "United States Dollar",
            "currencyCode": "USD",
            "currencySymbol": "$"
        },
        "language": {
            "name": "Portuguese",
            "code": "pt",
            "native": "Português"
        },
        "timezone": {
            "name": "America/Adak",
            "abbreviation": "HST",
            "offset": -36000,
            "currentTime": "11:51:19",
            "currentTimestamp": 1643406679,
            "isDST": false,
            "sunInfo": {
                "sunset": "08:17:34",
                "sunrise": "20:08:16",
                "transit": "02:12:55",
                "civilTwilightBegin": "19:47:39",
                "civilTwilightEnd": "08:38:10",
                "nauticalTwilightBegin": "19:22:22",
                "nauticalTwilightEnd": "09:03:28",
                "astronomicalTwilightBegin": "18:57:01",
                "astronomicalTwilightEnd": "09:28:49",
                "dayLength": "11:50:42"
            }
        },
        "flag": {
            "emoji": "🇺🇸",
            "unicode": "U+1F1FA U+1F1F8",
            "png": {
                "1000px": "https://gurdx.cretip.com/flags/png1000px/us.png",
                "250px": "https://gurdx.cretip.com/flags/png250px/us.png",
                "100px": "https://gurdx.cretip.com/flags/png100px/us.png"
            },
            "svg": "https://gurdx.cretip.com/flags/svg/us.svg"
        },
        "countryIsEU": false,
        "countryNeighbours": "CA,MX,CU",
        "tld": ".us",
        "continentName": "North America",
        "continentCode": "NA",
        "continentGeoNameID": 6255149
    },
    "status": "success",
    "executionTime": 0
}

Error#

Errors are delivered with HTTP 200 — always check the status field.

{
    "status": "error",
    "code": 101,
    "type": "invalid_key",
    "description": "The API Key is missing or invalid."
}