🎉 Announcing! New API documentation with downloadable Swagger file. Click here

Please use the above link for up-to-date endpoints.

Guides

Usage

Our API can be used through the following url, and appending the relevant endpoint to the end of it.

https://api.tellusdb.com/

Authentication

First create an account, we have a free plan you can use. Then go to your dashboard → Usage to find your API token.

Keep in mind all the below code samples does not include the token. This is done for readability. You should always include the ?token= parameter even if the example does not show it.

This API token should be appended to your API calls as a URL parameter, like so:

https://api.tellusdb.com/v1/countries?token=123456

Language Support

The payload includes translations for the official and the common representation of each country name. Our Fix Data endpoint also supports matching by language automatically. Currently we support the following languages.

The languages are listed by name name and their corresponding ISO 639-3 Alpha-3 code.

We also have an endpoint to get all supported languages, including ISO 639-2 Alpha-2 codes and english translation of the name.

Please note that some languages only includes translations for the common spelling of the country name, not the official. An example of common name is "United Kingdom", whereas the official name is "United Kingdom of Great Britain and Northern Ireland".

  • Native language(s) for each country
  • English: eng (default returned name)
  • Arabic: ara
  • Bulgarian: bul
  • Czech: ces
  • Danish: dan
  • German: deu
  • Greek: ell
  • Esperanto: epo
  • Spanish: spa
  • Estonian: est
  • Basque: eus
  • Finnish: fin
  • French: fra
  • Croatian: hr
  • Hungarian: hun
  • Armenian: hye
  • Italian: ita
  • Japanese: jpn
  • Korean: kor
  • Lithuanian: lit
  • Dutch: nld
  • Norwegian: nor
  • Polish: pol
  • Portuguese: por
  • Romanian: ron
  • Russian: rus
  • Slovak: slk
  • Slovenian: slv
  • Serbian: srp
  • Swedish: swe
  • Thai: tha
  • Ukrainian: ukr
  • Chinese: zho
  • Chinese (Traditional): zho-tw
  • Persian: per
  • Urdu: urd

Errors

We use HTTP error codes to alert you of problems, in case of an invalid request, token and more. Error codes we use and their meaning:

  • 422: Invalid request. A message is returned in the JSON response, explaining what went wrong.
  • 401: Invalid or missing API token. Please provide your token through a ?token= URL parameter.
  • 404: Resource not found. For example if you request a specific country that does not exist.
  • 429: Too many requests. You have exceeded the rate limiting for your account.
  • 5XX: Server error

Examples

Below are some language-specific examples, to get you started quicker.

cURL

curl "https://api.tellusdb.com/v1/countries?token=abc"

JavaScript w/ Fetch

fetch('https://api.tellusdb.com/v1/countries?token=abc')
     .then(response => response.json())
     .then(data => console.log(data.result));

Full Payload

This is a example of the full output for a single country, to show the format as well as what data we provide.

{
    "name": {
        "common": "Norway",
        "official": "Kingdom of Norway",
        "native": {
            "nno": {
                "official": "Kongeriket Noreg",
                "common": "Noreg"
            },
            "nob": {
                "official": "Kongeriket Norge",
                "common": "Norge"
            },
            "smi": {
                "official": "Norgga gonagasriika",
                "common": "Norgga"
            }
        },
        "translations": {
            "ara": {
                "common": "النرويج"
            },
            "bul": {
                "common": "Норвегия"
            },
            "ces": {
                "official": "Norské království",
                "common": "Norsko"
            },
            "dan": {
                "common": "Norge"
            }
        },
        "alternatives": [
            "NO",
            "Norge",
            "Noreg",
            "Kingdom of Norway",
            "Kongeriket Norge",
            "Kongeriket Noreg"
        ]
    },
    "tld": [
        ".no"
    ],
    "status": "officially-assigned",
    "currencies": {
        "NOK": {
            "name": "Norwegian krone",
            "symbol": "kr"
        }
    },
    "capital": [
        "Oslo"
    ],
    "region": "Europe",
    "subregion": "Northern Europe",
    "languages": {
        "nno": "Norwegian Nynorsk",
        "nob": "Norwegian Bokmål",
        "smi": "Sami"
    },
    "landlocked": false,
    "borders": [
        "FIN",
        "SWE",
        "RUS"
    ],
    "area": {
        "m2": 323802,
        "sqft": 3485375.72
    },
    "flag": {
        "emoji": "🇳🇴",
        "svg": "https:\/\/api.tellusdb.com\/v1\/countries\/flags\/svg\/nor.svg",
        "png": "https:\/\/api.tellusdb.com\/v1\/countries\/flags\/png\/no.png"
    },
    "demonyms": {
        "eng": {
            "f": "Norwegian",
            "m": "Norwegian"
        },
        "fra": {
            "f": "Norvégienne",
            "m": "Norvégien"
        }
    },
    "coordinates": {
        "latitude": 62,
        "longitude": 10
    },
    "continent": {
        "code": "EU",
        "name": "Europe",
        "others": []
    },
    "calling": {
        "base": "+47",
        "idd": {
            "root": "+4",
            "suffixes": [
                "7"
            ]
        },
        "codes": [
            "+47"
        ]
    },
    "political": {
        "is_independent": true,
        "is_un_memeber": true
    },
    "iso3166": {
        "alpha2": "NO",
        "alpha3": "NOR",
        "numeric": "578"
    },
    "ioc_code": "NOR",
    "purchasing_power": {
        "year": 2022,
        "value": 8.882011
    },
    "addressing": {
        "labels": {
            "state": {
                "english": "State"
            },
            "zip": {
                "english": "ZIP Code"
            },
            "city": {
                "english": "Post Town"
            },
            "district": {
                "english": "District"
            }
        },
        "zip_regex": "\\d{4}",
        "zip_examples": [
            "0025",
            "0107",
            "6631"
        ],
        "fields": {
            "available": [
                "name",
                "company_name",
                "street",
                "zip",
                "city"
            ],
            "required": [
                "street",
                "city",
                "zip"
            ]
        }
    }
}

Rate Limiting

Our paid plans are never rate limited, and you can continue to use the API even if you exceed your monthly quota, with no overage cost. It is our policy that your service uptime is our highest priority, therefor if you continously exceed your monthly quota, we will reach out to you to discuss upgrading your plan or finding alternate solutions.
We will never charge overage fees, or automatically upgrade you.

If you are using the free plan, we will enforce a hard-limit if you exceed your monthly request quota.

Only successful responses will count towards your quota, and will contain two headers to help you monitor usage instantly:

Api-Ratelimit-Usage: 85   # Current usage
Api-Ratelimit-Quota: 1000 # Total quota available in plan

Filtering results

We currently offer 8 filters and a search option across all country endpoints.

  • Search (string)
  • Regions (array)
  • Continents (array)
  • Languages (array)
  • Currencies (array)
  • Capitals (array)
  • Calling Codes (array)
  • Timezones (array)
  • Independence status (boolean, yes,no)
  • UN Membership status (boolean, yes,no)

All the filters above listed as array, permits filtering by multiple values at once, letting you broaden your search. For example getting all countries with either English or Spanish as their main language: ?languages=eng,spa

The filters can be combined as well, letting you narrow down the results even further.

GET /v1/countries?independent=true
GET /v1/countries?un-member=true
GET /v1/countries?continents=EU,NA
GET /v1/countries?regions=Europe
GET /v1/countries?regions/subregions=Northern+Europe
GET /v1/countries?currencies=dkk,gbp,usd
GET /v1/countries?languages=dan,eng
GET /v1/countries?capitals=London,Copenhagen
GET /v1/countries?capitals=callingcodes=44,1
GET /v1/countries?timezones=europe/copenhagen
GET /v1/countries?search=Spa # replace Spa with the search query

Country Flags

All country payloads contains 3 variables with flag information.

Note: the svg url uses Alpha-3 and the png url uses Alpha-2. We recommend using the url from the API payload, to stay up to date with our format.

{
    "flag": {
        "emoji": "🇺🇸",
        "svg": "https:\/\/api.tellusdb.com\/v1\/countries\/flags\/svg\/usa.svg",
        "png": "https:\/\/api.tellusdb.com\/v1\/countries\/flags\/png\/us.png"
    }
}

Address Formats

In all country related enpoints, we return an 'addressing' attribute, which contains useful information about the specific country and how they format addresses.

It will contain the following:

  • labels: English text for different fields, such as Postal Code vs ZIP Code
  • zip_regex: Regex for validation of ZIP Codes (might return null)
  • zip_examples: An array of ZIP Code examples (might be empty)
  • fields: contains two attributes, available and required. Available lists all fields which the country uses for address inputs. Required lists all fields that are required to fill out for the country. Country is left out, as it is generally always required. (both might return null).

The fields.required array might not contain "name", as it technically depends on the recipient, but it is generally adviced to have the field visible regardless.

By using fields.available, you can display certain fields conditionally, for example not all countries use "state" for shipping.

labels has 4 attributes: state, zip, city, district. Each with an english translation. You can use that to switch the text on the input labels, for example from ZIP Code to Postal Code.

The attributes in labels also contain a "type", which is our internal key to identify the different options. You can use that for translating internally to other languages, or completely ignore it.

{
    "labels": {
        "state": {
            "english": "State"
        },
        "zip": {
            "english": "ZIP Code"
        },
        "city": {
            "english": "Post Town"
        },
        "district": {
            "english": "District"
        }
    },
    "zip_regex": "\\d{4}",
    "zip_examples": [
        "0025",
        "0107",
        "6631"
    ],
    "fields": {
        "available": [
            "name",
            "company_name",
            "street",
            "zip",
            "city"
        ],
        "required": [
            "street",
            "city",
            "zip"
        ]
    }
}

Purchasing Power Parity (PPP)

We provide Purchasing Power Parity data as a ppp variable on all products, with the latest year value. It is included in all API calls to our country endpoints.

For historical data, you can use the Purchasing Power Parity Endpoints.

Note: these are not updated live, but rather a yearly value. This is not suitable for real-time purchasing power parity data, but rather for a best-effort approach.

"Purchasing power parity conversion factor is the number of units of a country's currency required to buy the same amounts of goods and services in the domestic market as U.S. dollar would buy in the United States. *" 
{
    "result": {
        "name": {
            "common": "Denmark"
        },
        "purchasing_power": {
            "year": 2022,
            "value": 6.404699
        }
    }
}

The above is an abbreviated version of the full payload.

Usage in Frontend

It is possible to use the TellusDB API through the browser directly, using for example JavaScript with Fetch or Axios, exactly how you would use it in the backend. See examples.

Worth noting however is that it would expose your API token to the user, as the request goes through their device, rather than your backend. For that reason, we recommend that even when using our Country search filter, that you do it through the backend, to not expose your token for potential abuse.

Glossary

Continent is a large landmass, of which Earth has seven: Asia, African, North America, South America, Antarctica, Europe, and Australia.

Region is a large geographic area that can be defined by culture, climate or a geographic feature.

Endpoints

List all countries

To get a full list of all countries in our database, you can use this endpoint. This endpoint does not include translated names of each country, to reduce response size and time.

For narrowing down results, you can refer to the filtering section of the documentation.

GET /v1/countries

{
    "result": [
        {
            "name": {
                "common": "United Kingdom",
                "official": "United Kingdom of Great Britain and Northern Ireland"
            }
        },
        {
            "name": {
                "common": "Denmark",
                "official": "the Kingdom of Denmark"
            }
        }
    ],
    "count": 2,
    "time_taken_ms": 10.472834
}

The above is an abbreviated version of the full payload. See full example here.

The full returned payload for all countries will be ~390KB (this is after stripping translations), which can be quite a lot of JSON to parse and return to users.

Therefor, we provide a minimal version that provide just the bare essential data, which will be ~179KB (A saving of +50%!). It can be used like so:

GET /v1/countries?minimal=true

{
    "result": [
        {
            "name": {
                "common": "Denmark",
                "official": "Kingdom of Denmark"
            },
            "currencies": {
                "DKK": {
                    "name": "Danish krone",
                    "symbol": "kr"
                }
            },
            "capital": [
                "Copenhagen"
            ],
            "region": "Europe",
            "subregion": "Northern Europe",
            "flag": {
                "emoji": "\ud83c\udde9\ud83c\uddf0"
            },
            "continent": {
                "code": "EU",
                "name": "Europe",
                "others": [
                    {
                        "code": "NA",
                        "name": "North America"
                    }
                ]
            },
            "calling": {
                "base": "+45"
            },
            "iso3166": {
                "alpha2": "DK",
                "alpha3": "DNK",
                "numeric": "208"
            },
            "ioc_code": "DEN",
            "addressing": {
                "labels": {
                    "state": {
                        "english": "State",
                        "type": "state"
                    },
                    "zip": {
                        "english": "ZIP Code",
                        "type": "zip"
                    },
                    "city": {
                        "english": "City",
                        "type": "city"
                    },
                    "district": {
                        "english": "District",
                        "type": "district"
                    }
                },
                "zip_regex": "\\d{4}",
                "zip_examples": [
                    "8660",
                    "1566"
                ],
                "fields": {
                    "available": [
                        "name",
                        "company_name",
                        "street",
                        "zip",
                        "city"
                    ],
                    "required": [
                        "street",
                        "city",
                        "zip"
                    ]
                }
            }
        }
    ],
    "count": 250,
    "time_taken_ms": 10.472834
}

The above is an abbreviated version of the full payload. See full example here.

Find specific country

You can find a specific country by ISO3166 alpha2 or alpha3 code by using this endpoint. This endpoint includes translated names.

GET /v1/countries/gb # replace gb with the country ISO3166 code

{
    "result": {
        "name": {
            "common": "United Kingdom",
            "official": "United Kingdom of Great Britain and Northern Ireland"
        }
    },
    "time_taken_ms": 10.472834
}

The above is an abbreviated version of the full payload. See full example here.

Get countries by calling code

Useful if you have a phone number and need to determine which country it belongs to.

GET /v1/countries?callingcodes=44 # replace 44 with the callingcode

{
    "result": [
        {
            "name": {
                "common": "United Kingdom",
                "official": "United Kingdom of Great Britain and Northern Ireland"
            }
        }
    ],
    "count": 1,
    "time_taken_ms": 10.472834
}

The above is an abbreviated version of the full payload. See full example here.

Get countries by language code

This will list all countries that has the specified language as one of their 'primary' languages.

Supports ISO 639-3 Alpha-2 and Alpha-3 code (See list of Alpha-3 codes here)

GET /v1/countries?languages=eng # replace eng with the language

{
    "result": [
        {
            "name": {
                "common": "United Kingdom",
                "official": "United Kingdom of Great Britain and Northern Ireland"
            }
        }
    ],
    "count": 1,
    "time_taken_ms": 10.472834
}

The above is an abbreviated version of the full payload. See full example here.

Get countries by timezone

This will list all countries that are in the specified timezone(s).

GET /v1/countries?timezones=europe/london

{
    "result": [
        {
            "name": {
                "common": "United Kingdom",
                "official": "United Kingdom of Great Britain and Northern Ireland"
            }
        }
    ],
    "count": 1,
    "time_taken_ms": 10.472834
}

The above is an abbreviated version of the full payload. See full example here.

Get countries by region

This will list all countries that are part of the specified region.

Keep in mind, regions are not continents. For continents, see our Continent endpoints..

See list of supported regions and their sub-regions.

GET /v1/countries?regions=europe # replace europe with the region

{
    "result": [
        {
            "name": {
                "common": "United Kingdom",
                "official": "United Kingdom of Great Britain and Northern Ireland"
            }
        }
    ],
    "count": 1,
    "time_taken_ms": 10.472834
}

The above is an abbreviated version of the full payload. See full example here.

Get countries by capital

This will list all countries has a capital with the specified value. Currently only supports english translations of the capitals.

Some countries has multiple capitals (example: Malaysia has Kuala Lumpur and Putrajaya), we will search all of them.

GET /v1/countries?capitals=London # replace London with the capital

{
    "result": [
        {
            "name": {
                "common": "United Kingdom",
                "official": "United Kingdom of Great Britain and Northern Ireland"
            }
        }
    ],
    "count": 1,
    "time_taken_ms": 10.472834
}

The above is an abbreviated version of the full payload. See full example here.

Get countries by currency

This will list all countries using the specified currency as one of their main currencies.

GET /v1/countries?currencies=GBP # replace GBP with the currency

{
    "result": [
        {
            "name": {
                "common": "United Kingdom",
                "official": "United Kingdom of Great Britain and Northern Ireland"
            }
        }
    ],
    "count": 1,
    "time_taken_ms": 10.472834
}

The above is an abbreviated version of the full payload. See full example here.

Search country

If you are building a autocomplete or search field, you can use this endpoint. It returns all results that matches a search query by their commonly used name in english.

We recommend that you add some throttling on your input field, to not exhaust your API limits.

GET /v1/countries?search={search}

{
    "result": [
        {
            "name": {
                "common": "United Kingdom",
                "official": "United Kingdom of Great Britain and Northern Ireland"
            },
            "search_score": 100
        },
        {
            "name": {
                "common": "Denmark",
                "official": "the Kingdom of Denmark"
            },
            "search_score": 66.5
        }
    ],
    "count": 2,
    "time_taken_ms": 10.472834
}

The above is an abbreviated version of the full payload. See full example here.

By default, we will search based on text similarity. If you require that the country name starts with the query, you can enable strict mode with ?strict-search=true

GET /v1/countries?search={search}&strict-search=true

{
    "result": [
        "# Abbreviated for readability #"
    ],
    "count": 2,
    "time_taken_ms": 10.472834
}

The above is an abbreviated version of the full payload. See full example here.

Match and fix data

For some applications, especially those allowing free-text country input, it can be useful to be able to convert the user input into a structured format.

This endpoint helps you with that, by using a best-effort approach at suggesting a country that matches your query. It even handles typos and multiple languages.

GET /v1/country-matching/Unt+kingdem

{
    "result": {
        "name": {
            "common": "United Kingdom",
            "official": "United Kingdom of Great Britain and Northern Ireland"
        }
    },
    "count": 4,
    "result_method": "Found match by comparing with field name_common, matched by 88.8889%",
    "time_taken_ms": 10.472834
}

The above is an abbreviated version of the full payload. See full example here.

Region Endpoints

Get all regions

This will list all regions.

GET /v1/regions

{
    "result": [
        "Africa",
        "Americas",
        "Antarctic",
        "Asia",
        "Europe",
        "Oceania"
    ],
    "count": 6,
    "time_taken_ms": 4.2171478271484375
}

Get all sub-regions for a region

This will list all sub-regions that belongs to a specific region.

GET /v1/regions/Europe/subregions

{
    "result": [
        "Central Europe",
        "Eastern Europe",
        "Northern Europe",
        "Southeast Europe",
        "Southern Europe",
        "Western Europe"
    ],
    "count": 6,
    "time_taken_ms": 1.5811920166015625
}

Get all sub-regions

This will list all sub-regions.

GET /v1/regions/subregions

{
    "result": [
        {
            "name": "Australia and New Zealand",
            "region": "Oceania"
        },
        {
            "name": "Caribbean",
            "region": "Americas"
        },
        {
            "name": "Central America",
            "region": "Americas"
        },
        {
            "name": "Central Asia",
            "region": "Asia"
        },
        {
            "name": "Central Europe",
            "region": "Europe"
        },
        {
            "name": "Eastern Africa",
            "region": "Africa"
        },
        {
            "name": "Eastern Asia",
            "region": "Asia"
        },
        {
            "name": "Eastern Europe",
            "region": "Europe"
        },
        {
            "name": "Melanesia",
            "region": "Oceania"
        },
        {
            "name": "Micronesia",
            "region": "Oceania"
        },
        {
            "name": "Middle Africa",
            "region": "Africa"
        },
        {
            "name": "North America",
            "region": "Americas"
        },
        {
            "name": "Northern Africa",
            "region": "Africa"
        },
        {
            "name": "Northern Europe",
            "region": "Europe"
        },
        {
            "name": "Polynesia",
            "region": "Oceania"
        },
        {
            "name": "South America",
            "region": "Americas"
        },
        {
            "name": "South-Eastern Asia",
            "region": "Asia"
        },
        {
            "name": "Southeast Europe",
            "region": "Europe"
        },
        {
            "name": "Southern Africa",
            "region": "Africa"
        },
        {
            "name": "Southern Asia",
            "region": "Asia"
        },
        {
            "name": "Southern Europe",
            "region": "Europe"
        },
        {
            "name": "Western Africa",
            "region": "Africa"
        },
        {
            "name": "Western Asia",
            "region": "Asia"
        },
        {
            "name": "Western Europe",
            "region": "Europe"
        }
    ],
    "count": 24,
    "time_taken_ms": 3.3540725708007812
}

Language Endpoints

Get supported languages

This will list all languages we currently support.

GET /v1/languages

{
    "result": [
        {
            "alpha2": "ar",
            "alpha3": "ara",
            "name": "Arabic"
        },
        {
            "alpha2": "bg",
            "alpha3": "bul",
            "name": "Bulgarian"
        },
        {
            "alpha2": "cs",
            "alpha3": "ces",
            "name": "Czech"
        },
        {
            "alpha2": "es",
            "alpha3": "spa",
            "name": "Spanish"
        },
        {
            "alpha2": "sr",
            "alpha3": "srp",
            "name": "Serbian"
        },
        {
            "alpha2": "sv",
            "alpha3": "swe",
            "name": "Swedish"
        }
    ],
    "count": 34,
    "time_taken_ms": 4.4269561767578125
}

The above is an abbreviated version of the full payload.

Purchasing Power Parity Endpoints

Get Purchasing Power Parity for all countries

Return a list of all countries with their extended Purchasing Power Parity history, for every year we have data.

All our country endpoints will return purchasing_power data, however this one will include the full history rather than just latest year.

GET /v1/purchasing-power-parity

{
    "result": [
        {
            "name": {
                "common": "Afghanistan"
            },
            "iso3166": {
                "alpha2": "AF",
                "alpha3": "AFG",
                "numeric": "004"
            },
            "currencies": {
                "AFN": {
                    "name": "Afghan afghani",
                    "symbol": "\u060b"
                }
            },
            "purchasing_power_history": {
                "2021": {
                    "year": 2021,
                    "value": 18.3665874787932
                },
                "2020": {
                    "year": 2020,
                    "value": 19.1005684554336
                },
                "2019": {
                    "year": 2019,
                    "value": 17.9461277074541
                },
                "2018": {
                    "year": 2018,
                    "value": 17.1496573204731
                },
                "2017": {
                    "year": 2017,
                    "value": 17.2055580487587
                },
                "2016": {
                    "year": 2016,
                    "value": 17.4458279431472
                },
                "2015": {
                    "year": 2015,
                    "value": 17.0225200169416
                },
                "2014": {
                    "year": 2014,
                    "value": 17.0358776005124
                },
                "2013": {
                    "year": 2013,
                    "value": 17.5094188570492
                },
                "2012": {
                    "year": 2012,
                    "value": 17.2422638894206
                },
                "2011": {
                    "year": 2011,
                    "value": 16.6134779097919
                },
                "2010": {
                    "year": 2010,
                    "value": 14.5451339307295
                },
                "2009": {
                    "year": 2009,
                    "value": 14.1790575059122
                },
                "2008": {
                    "year": 2008,
                    "value": 14.5854818052397
                },
                "2007": {
                    "year": 2007,
                    "value": 14.5600018893242
                },
                "2006": {
                    "year": 2006,
                    "value": 12.2041652214925
                },
                "2005": {
                    "year": 2005,
                    "value": 11.735787358862
                },
                "2004": {
                    "year": 2004,
                    "value": 10.9129008458112
                },
                "2003": {
                    "year": 2003,
                    "value": 10.0707319256054
                },
                "2002": {
                    "year": 2002,
                    "value": 9.19749757075501
                }
            }
        }
    ],
    "count": 200,
    "time_taken_ms": 1.234
}

The above is an abbreviated version of the full payload.

Get Historical Purchasing Power Parity for a specific country

Endpoint to get only for a specific country, by Alpha-2 or Alpha-3 code.

GET /v1/country/af/purchasing-power # replace af with the code for country

{
    "result": {
        "name": {
            "common": "Afghanistan"
        },
        "iso3166": {
            "alpha2": "AF",
            "alpha3": "AFG",
            "numeric": "004"
        },
        "currencies": {
            "AFN": {
                "name": "Afghan afghani",
                "symbol": "\u060b"
            }
        },
        "purchasing_power": {
            "2021": {
                "year": 2021,
                "value": 18.3665874787932
            },
            "2020": {
                "year": 2020,
                "value": 19.1005684554336
            },
            "2019": {
                "year": 2019,
                "value": 17.9461277074541
            },
            "2018": {
                "year": 2018,
                "value": 17.1496573204731
            },
            "2017": {
                "year": 2017,
                "value": 17.2055580487587
            },
            "2016": {
                "year": 2016,
                "value": 17.4458279431472
            },
            "2015": {
                "year": 2015,
                "value": 17.0225200169416
            },
            "2014": {
                "year": 2014,
                "value": 17.0358776005124
            },
            "2013": {
                "year": 2013,
                "value": 17.5094188570492
            },
            "2012": {
                "year": 2012,
                "value": 17.2422638894206
            },
            "2011": {
                "year": 2011,
                "value": 16.6134779097919
            },
            "2010": {
                "year": 2010,
                "value": 14.5451339307295
            },
            "2009": {
                "year": 2009,
                "value": 14.1790575059122
            },
            "2008": {
                "year": 2008,
                "value": 14.5854818052397
            },
            "2007": {
                "year": 2007,
                "value": 14.5600018893242
            },
            "2006": {
                "year": 2006,
                "value": 12.2041652214925
            },
            "2005": {
                "year": 2005,
                "value": 11.735787358862
            },
            "2004": {
                "year": 2004,
                "value": 10.9129008458112
            },
            "2003": {
                "year": 2003,
                "value": 10.0707319256054
            },
            "2002": {
                "year": 2002,
                "value": 9.19749757075501
            }
        }
    },
    "time_taken_ms": 1.234
}

The above is an abbreviated version of the full payload.

Timezone Endpoints

Get all timezones

Return a list of timezones with their name and abbreviation.

GET /v1/timezones

{
    "result": [
        {
            "name": "Africa\/Abidjan",
            "abbreviation": "GMT"
        },
        {
            "name": "Africa\/Accra",
            "abbreviation": "GMT"
        },
        {
            "name": "Africa\/Addis_Ababa",
            "abbreviation": "EAT"
        },
        {
            "name": "Africa\/Algiers",
            "abbreviation": "CET"
        },
        {
            "name": "Africa\/Asmara",
            "abbreviation": "EAT"
        },
        {
            "name": "Africa\/Bamako",
            "abbreviation": "GMT"
        },
        {
            "name": "Africa\/Bangui",
            "abbreviation": "WAT"
        },
        {
            "name": "Africa\/Banjul",
            "abbreviation": "GMT"
        },
        {
            "name": "Africa\/Bissau",
            "abbreviation": "GMT"
        },
        {
            "name": "Africa\/Blantyre",
            "abbreviation": "CAT"
        },
        {
            "name": "Africa\/Brazzaville",
            "abbreviation": "WAT"
        },
        {
            "name": "Africa\/Bujumbura",
            "abbreviation": "CAT"
        },
        {
            "name": "Africa\/Cairo",
            "abbreviation": "EET"
        },
        {
            "name": "Africa\/Casablanca",
            "abbreviation": "WEST"
        },
        {
            "name": "Africa\/Ceuta",
            "abbreviation": "CET"
        },
        {
            "name": "Africa\/Conakry",
            "abbreviation": "GMT"
        },
        {
            "name": "Africa\/Dakar",
            "abbreviation": "GMT"
        },
        {
            "name": "Africa\/Dar_es_Salaam",
            "abbreviation": "EAT"
        }
    ],
    "count": 200,
    "time_taken_ms": 1.234
}

The above is an abbreviated version of the full payload.

Get timezones for a specific country

This will return all available timezones for the given country, by country Alpha-2 or Alpha-3 code.

GET /v1/country/dk/timezones # replace dk with the code for country

{
    "result": [
        {
            "name": "Europe\/Copenhagen",
            "abbreviation": "CET"
        }
    ],
    "count": 1,
    "time_taken_ms": 1.4069080352783203
}

Calling Code Endpoints

Get all callingcodes

This will return a list of all calling codes, as well as their corresponding country with some base info, such as flag, english name, area codes and more.

GET /v1/callingcodes

{
    "result": [
        {
            "base": "+93",
            "name": {
                "common": "Afghanistan"
            },
            "iso3166": {
                "alpha2": "AF",
                "alpha3": "AFG",
                "numeric": "004"
            },
            "flag": {
                "emoji": "\ud83c\udde6\ud83c\uddeb",
                "svg": "https:\/\/api.tellusdb.com\/v1\/countries\/flags\/svg\/afg.svg",
                "png": "https:\/\/api.tellusdb.com\/v1\/countries\/flags\/png\/af.png"
            },
            "calling": {
                "base": "+93",
                "idd": {
                    "root": "+9",
                    "suffixes": [
                        "3"
                    ]
                },
                "codes": [
                    "+93"
                ]
            }
        },
        {
            "base": "+355",
            "name": {
                "common": "Albania"
            },
            "iso3166": {
                "alpha2": "AL",
                "alpha3": "ALB",
                "numeric": "008"
            },
            "flag": {
                "emoji": "\ud83c\udde6\ud83c\uddf1",
                "svg": "https:\/\/api.tellusdb.com\/v1\/countries\/flags\/svg\/alb.svg",
                "png": "https:\/\/api.tellusdb.com\/v1\/countries\/flags\/png\/al.png"
            },
            "calling": {
                "base": "+355",
                "idd": {
                    "root": "+3",
                    "suffixes": [
                        "55"
                    ]
                },
                "codes": [
                    "+355"
                ]
            }
        }
    ],
    "count": 250,
    "time_taken_ms": 1.234
}

The above is an abbreviated version of the full payload.

Continent Endpoints

Get all continents

This will return a list of all continents with their corresponding key.

Keep in mind continents are very unlikely to change, so it is safe to store these values locally, to not use up quota on infrequently updated data. Should they change in the future, we will notify you on the email you registered with us.

GET /v1/continents

{
    "result": [
        {
            "key": "AF",
            "name": "Africa"
        },
        {
            "key": "AN",
            "name": "Antarctica"
        },
        {
            "key": "AS",
            "name": "Asia"
        },
        {
            "key": "EU",
            "name": "Europe"
        },
        {
            "key": "NA",
            "name": "North America"
        },
        {
            "key": "OC",
            "name": "Oceania"
        },
        {
            "key": "SA",
            "name": "South America"
        }
    ],
    "count": 7,
    "time_taken_ms": 2.0830631256103516
}