Countries

Introduction 🔗︎ click to copy

Mydex Data Services CIC provides an API known as the 'Master Reference Data Services' or MRD. This API provides access to a variety of non-personal, general purpose datasets that may be of use when integrating with the rest of the Mydex platform or simply a valuable managed API service for a range of datasets that can be subscribed to.

One of the datasets provided on the MRD API is the Countries service.

This dataset provides JSON endpoints that contain a variety of attributes about countries and territories around the world. This data includes (but is not limited to) the following attributes:

• Its ISO 3166-1 codes (CCA alpha-2, CCA alpha-3, CCN3 (numeric))
• Official and 'common' country names, as well as many translated names for the country in other languages
• Official Language (codes) of a country
• Capital cities of a country and latitude/longitude
• Region, subregion and continent information about where the country is
• Map links to the country (Google and Open Street Maps)
• Approximate size and population
• International telephone calling codes (IDD) for the country
• Currency information
• Whether the country is landlocked
• Whether the country is a UN member
• Timezone information
• Post code formats
• Flag emojis

How to use the Countries content via the MRD API 🔗︎ click to copy

It is possible to retrieve a list of all countries and their attributes, or look up a country by its CCA2 code (e.g GB for Great Britain).

It is also possible to filter the fields that are returned in the JSON, both for the 'all countries' endpoint as well as an individual country.

Authenticating with OAuth2.0 🔗︎ click to copy

The Mydex MRD API requires authentication using the industry standard OAuth2.0 protocol. To use the Countries service, you will need an OAuth2.0 client that is scoped to (at least) countries. Please see our online documentation for more information on this: https://dev.mydex.org/mrd-api/mrd-authentication.html

Returning all countries 🔗︎ click to copy

For example, to return the data for all countries, use the following endpoint:

• https://api-mrd.mydex.org/countries

This will return a JSON response of all countries and their data. There is no pagination, as there are only about 250 results.

Returning a single country 🔗︎ click to copy

To return the data for a single country, add the country's CCA2 code (e.g GB for Great Britain) to the end of the URL:

• https://api-mrd.mydex.org/countries/GB

This will return a JSON response of just that country and its data.

The request is case-insensitive, so you can put gb instead of GB and it will still work.

Filtering fields (query parameters) 🔗︎ click to copy

It is possible to filter what fields are returned in the JSON, using the filters query parameter.

The filters parameter can be specified either with a repeated 'array' of values, or with a simple comma-delimited set of values.

For example, to return just the name, capital, region, idd codes and maps links for Great Britain, either of the following two URLs work:

• https://api-mrd.mydex.org/countries/GB?filters[]=name&filters[]=capital&filters[]=region&filters[]=idd&filters[]=maps
• https://api-mrd.mydex.org/countries/GB?filters=name,capital,region,idd,maps

Result:🔗︎ click to copy

{
  "idd": {
    "root": "+4",
    "suffixes": [
      "4"
    ]
  },
  "maps": {
    "googleMaps": "https://goo.gl/maps/FoDtc3UKMkFsXAjHA",
    "openStreetMaps": "https://www.openstreetmap.org/relation/62149"
  },
  "name": {
    "common": "United Kingdom",
    "official": "United Kingdom of Great Britain and Northern Ireland"
  },
  "region": "Europe",
  "capital": [
    "London"
  ]
}

Note that the same filter technique works for the 'all countries' endpoint. In this way, for example, you can retrieve just international telephone codes and names for all countries around the world:

• https://api-mrd.mydex.org/countries?filters[]=idd&filters[]=name
• https://api-mrd.mydex.org/countries?filters=idd,name

Result:🔗︎ click to copy

[...]
{
  "idd": {
    "root": "+3",
    "suffixes": [
      "0"
    ]
  },
  "name": {
    "common": "Greece",
    "official": "Hellenic Republic"
  }
},
{
  "idd": {
    "root": "+2",
    "suffixes": [
      "99"
    ]
  },
  "name": {
    "common": "Greenland",
    "official": "Greenland"
  }
},
{
  "idd": {
    "root": "+1",
    "suffixes": [
      "473"
    ]
  },
  "name": {
    "common": "Grenada",
    "official": "Grenada"
  }
},
[...]

Example code 🔗︎ click to copy

For more example code in Python, PHP or Postman, including steps to obtain an OAuth2.0 token and use it, the required headers and so on, please visit our Github repository.

---