Countries API

Description

Lookup a specific country. Our database contains information about most countries and sovereign territories around the world.

Endpoint

> GET https://api.jsonrepo.com/v1/knowledge/location/countries

Headers

Field Description
api_key Required Your API Key

Parameters

Field Type Description
name String Optional The country name (case insensitive)
Example: United States
iso String Optional The country ISO code (case insensitive)
Accepts: ISO a-2, ISO a-3
Example: US or USA

Parameter Requirement:

You must provide either the name or iso parameter. If neither is provided, the execution will fail. If both are provided, an OR comparison will be executed.

Response

A successful request will result in a populated payload field with the expected output.

Note:

This endpoint will return no more than 20 matches if your search term is too broad.

A failed request will result in an error output as detailed in Error Rules. If the endpoint validation fails due to missing, badly formatted or invalid parameters, the endpoint will return HTTP code 400 along with a message detailing the error.

See the examples section for more information.

A Lorenum.com product

Twitter Discord Email

Request

  • Curl
// Lookup by `name`

curl -G \
https://api.jsonrepo.com/v1/knowledge/location/countries \
-H "api_key: {YOUR_API_KEY_HERE}" \
--data-urlencode "name=united states of america"

// Lookup by `iso`

curl -G \
https://api.jsonrepo.com/v1/knowledge/finance/currencies \
-H "api_key: {YOUR_API_KEY_HERE}" \
--data-urlencode "iso=USA"

Success Response

{
    "http_code": 200,
    "http_message": "Ok",
    "message": "Successful execution",
    "payload": {
        "countries": [
            {
                "id": 236,
                "name": "United States of America",
                "name_short": "United States",
                "code_2": "US",
                "code_3": "USA",
                "coordinates": {
                    "latitude": 38,
                    "longitude": -97
                },
                "capital": "Washington D.C.",
                "region": "Americas",
                "subregion": "North America",
                "area_km2": 9372610,
                "population": 333287557,
                "gdp": 25439700000000,
                "gdp_per_capita": 76330,
                "languages": [
                    "English"
                ],
                "religion": "Christian",
                "currencies": [
                    {
                        "currency_name": "United States dollar",
                        "currency_short": "USD",
                        "currency_symbol": "$"
                    }
                ],
                "tlds": [
                    ".us"
                ],
                "dial_codes": [
                    "+1201",
                    "+1202",
                    "+1203",
                    "+1205",

                    // More dial codes
                    ...

                    "+1986",
                    "+1989"
                ],
                "db_entry_last_updated_at": "2024-07-31 17:52:51"
            }
        ]
    }
}

Error Response Examples

// Request with missing `name` & `iso` parameters

{
    "http_code": 400,
    "http_message": "Bad Request",
    "message": "Malformed request: `name` and `iso` parameters were not provided. One of them must be supplied.",
    "payload": []
}