The "Country" resource is the main resource in the region hierachy. Form the country resource you can retrieve all regional data for a specific country and thus providing a gateway to all the regional data you require.
Use this endpoint to retrieve a complete list of countries.
# retrieve Country list
>>> url = "https://www.the-datagarden.io/country/"
>>> headers = {'Content-Type': 'application/json', 'Authorization': 'Bearer <access_token>'}
>>>
>>> response = requests.request("GET§", url, headers=headers, payload=payload)
The response contains a paginated list, where each country entry includes the country name and a URL linking to its detailed resource.
# response
{
"count": 200,
"next": "http://www.the-datagarden.io/country/?page=2",
"previous": null,
"results": [
{
"url": "http://www.the-datagarden.io/country/afghanistan/",
"name": "Afghanistan",
"parent_region": "Asia",
"iso_cc_3": "AFG",
"iso_cc_2": "AF",
"un_sdg_region": "CENTRAL AND SOUTHERN ASIA",
"un_sub_region": "Southern Asia",
"iso6391_language_code": null
},
{
"url": "http://www.the-datagarden.io/country/albania/",
"name": "Albania",
"parent_region": "Europe",
"iso_cc_3": "ALB",
"iso_cc_2": "AL",
"un_sdg_region": "EUROPE AND NORTHERN AMERICA",
"un_sub_region": "Southern Europe",
"iso6391_language_code": null
},
{
"url": "http://www.the-datagarden.io/country/algeria/",
"name": "Algeria",
"parent_region": "Africa",
"iso_cc_3": "DZA",
"iso_cc_2": "DZ",
"un_sdg_region": "NORTHERN AFRICA AND WESTERN ASIA",
"un_sub_region": "Northern Africa",
"iso6391_language_code": null
},
{
"url": "http://www.the-datagarden.io/country/angola/",
"name": "Angola",
"parent_region": "Africa",
"iso_cc_3": "AGO",
"iso_cc_2": "AO",
"un_sdg_region": "SUB-SAHARAN AFRICA",
"un_sub_region": "Middle Africa",
"iso6391_language_code": null
},
{
"url": "http://www.the-datagarden.io/country/antigua-and-barbuda/",
"name": "Antigua and Barbuda",
"parent_region": "Latin America and the Caribbean",
"iso_cc_3": "ATG",
"iso_cc_2": "AG",
"un_sdg_region": "LATIN AMERICA AND THE CARIBBEAN",
"un_sub_region": "Caribbean",
"iso6391_language_code": null
},
{
"url": "http://www.the-datagarden.io/country/argentina/",
"name": "Argentina",
"parent_region": "Latin America and the Caribbean",
"iso_cc_3": "ARG",
"iso_cc_2": "AR",
"un_sdg_region": "LATIN AMERICA AND THE CARIBBEAN",
"un_sub_region": "South America",
"iso6391_language_code": null
},
{
"url": "http://www.the-datagarden.io/country/armenia/",
"name": "Armenia",
"parent_region": "Asia",
"iso_cc_3": "ARM",
"iso_cc_2": "AM",
"un_sdg_region": "NORTHERN AFRICA AND WESTERN ASIA",
"un_sub_region": "Western Asia",
"iso6391_language_code": null
},
{
"url": "http://www.the-datagarden.io/country/aruba/",
"name": "Aruba",
"parent_region": "Latin America and the Caribbean",
"iso_cc_3": "ABW",
"iso_cc_2": "AW",
"un_sdg_region": "LATIN AMERICA AND THE CARIBBEAN",
"un_sub_region": "Caribbean",
"iso6391_language_code": null
},
{
"url": "http://www.the-datagarden.io/country/australia/",
"name": "Australia",
"parent_region": "Oceania",
"iso_cc_3": "AUS",
"iso_cc_2": "AU",
"un_sdg_region": "AUSTRALIA/NEW ZEALAND",
"un_sub_region": "",
"iso6391_language_code": null
},
{
"url": "http://www.the-datagarden.io/country/austria/",
"name": "Austria",
"parent_region": "Europe",
"iso_cc_3": "AUT",
"iso_cc_2": "AT",
"un_sdg_region": "EUROPE AND NORTHERN AMERICA",
"un_sub_region": "Western Europe",
"iso6391_language_code": null
},
{
"url": "http://www.the-datagarden.io/country/azerbaijan/",
"name": "Azerbaijan",
"parent_region": "Asia",
"iso_cc_3": "AZE",
"iso_cc_2": "AZ",
"un_sdg_region": "NORTHERN AFRICA AND WESTERN ASIA",
"un_sub_region": "Western Asia",
"iso6391_language_code": null
},
{
"url": "http://www.the-datagarden.io/country/bahamas/",
"name": "Bahamas",
"parent_region": "Latin America and the Caribbean",
"iso_cc_3": "BHS",
"iso_cc_2": "BS",
"un_sdg_region": "LATIN AMERICA AND THE CARIBBEAN",
"un_sub_region": "Caribbean",
"iso6391_language_code": null
},
{
"url": "http://www.the-datagarden.io/country/bahrain/",
"name": "Bahrain",
"parent_region": "Asia",
"iso_cc_3": "BHR",
"iso_cc_2": "BH",
"un_sdg_region": "NORTHERN AFRICA AND WESTERN ASIA",
"un_sub_region": "Western Asia",
"iso6391_language_code": null
},
{
"url": "http://www.the-datagarden.io/country/bangladesh/",
"name": "Bangladesh",
"parent_region": "Asia",
"iso_cc_3": "BGD",
"iso_cc_2": "BD",
"un_sdg_region": "CENTRAL AND SOUTHERN ASIA",
"un_sub_region": "Southern Asia",
"iso6391_language_code": null
},
{
"url": "http://www.the-datagarden.io/country/barbados/",
"name": "Barbados",
"parent_region": "Latin America and the Caribbean",
"iso_cc_3": "BRB",
"iso_cc_2": "BB",
"un_sdg_region": "LATIN AMERICA AND THE CARIBBEAN",
"un_sub_region": "Caribbean",
"iso6391_language_code": null
},
{
"url": "http://www.the-datagarden.io/country/belarus/",
"name": "Belarus",
"parent_region": "Europe",
"iso_cc_3": "BLR",
"iso_cc_2": "BY",
"un_sdg_region": "EUROPE AND NORTHERN AMERICA",
"un_sub_region": "Eastern Europe",
"iso6391_language_code": null
},
{
"url": "http://www.the-datagarden.io/country/belgium/",
"name": "Belgium",
"parent_region": "Europe",
"iso_cc_3": "BEL",
"iso_cc_2": "BE",
"un_sdg_region": "EUROPE AND NORTHERN AMERICA",
"un_sub_region": "Western Europe",
"iso6391_language_code": null
},
{
"url": "http://www.the-datagarden.io/country/belize/",
"name": "Belize",
"parent_region": "Latin America and the Caribbean",
"iso_cc_3": "BLZ",
"iso_cc_2": "BZ",
"un_sdg_region": "LATIN AMERICA AND THE CARIBBEAN",
"un_sub_region": "Central America",
"iso6391_language_code": null
},
{
"url": "http://www.the-datagarden.io/country/benin/",
"name": "Benin",
"parent_region": "Africa",
"iso_cc_3": "BEN",
"iso_cc_2": "BJ",
"un_sdg_region": "SUB-SAHARAN AFRICA",
"un_sub_region": "Western Africa",
"iso6391_language_code": null
},
{
"url": "http://www.the-datagarden.io/country/bhutan/",
"name": "Bhutan",
"parent_region": "Asia",
"iso_cc_3": "BTN",
"iso_cc_2": "BT",
"un_sdg_region": "CENTRAL AND SOUTHERN ASIA",
"un_sub_region": "Southern Asia",
"iso6391_language_code": null
},
{
"url": "http://www.the-datagarden.io/country/bolivia-plurinational-state-of/",
"name": "Bolivia (Plurinational State of)",
"parent_region": "Latin America and the Caribbean",
"iso_cc_3": "BOL",
"iso_cc_2": "BO",
"un_sdg_region": "LATIN AMERICA AND THE CARIBBEAN",
"un_sub_region": "South America",
"iso6391_language_code": null
},
{
"url": "http://www.the-datagarden.io/country/bosnia-and-herzegovina/",
"name": "Bosnia and Herzegovina",
"parent_region": "Europe",
"iso_cc_3": "BIH",
"iso_cc_2": "BA",
"un_sdg_region": "EUROPE AND NORTHERN AMERICA",
"un_sub_region": "Southern Europe",
"iso6391_language_code": null
},
{
"url": "http://www.the-datagarden.io/country/botswana/",
"name": "Botswana",
"parent_region": "Africa",
"iso_cc_3": "BWA",
"iso_cc_2": "BW",
"un_sdg_region": "SUB-SAHARAN AFRICA",
"un_sub_region": "Southern Africa",
"iso6391_language_code": null
},
{
"url": "http://www.the-datagarden.io/country/brazil/",
"name": "Brazil",
"parent_region": "Latin America and the Caribbean",
"iso_cc_3": "BRA",
"iso_cc_2": "BR",
"un_sdg_region": "LATIN AMERICA AND THE CARIBBEAN",
"un_sub_region": "South America",
"iso6391_language_code": null
},
{
"url": "http://www.the-datagarden.io/country/brunei-darussalam/",
"name": "Brunei Darussalam",
"parent_region": "Asia",
"iso_cc_3": "BRN",
"iso_cc_2": "BN",
"un_sdg_region": "EASTERN AND SOUTH-EASTERN ASIA",
"un_sub_region": "South-Eastern Asia",
"iso6391_language_code": null
},
}
The basic country object can be retrieved using the GET method. It provides basic info for the country including the urls for the first level of subregions.
# retrieve Country resource
>>> url = "https://www.the-datagarden.io/country/netherlands/"
>>> headers = {'Content-Type': 'application/json', 'Authorization': 'Bearer <access_token>'}
>>>
>>> response = requests.request("GET", url, headers=headers)
The response json on this request should give you the details of the requested country.
{
"name": "Netherlands",
"parent_region": "Europe",
"iso_cc_2": "NL",
"un_sdg_region": "EUROPE AND NORTHERN AMERICA",
"un_sub_region": "Western Europe",
"iso6391_language_code": null,
} See for more details on the fields in this response the country section in the data models documentation.
You can easily include the geojson in the resposne by adding a url parameter.
# retrieve Country resource with geojson
>>> url = "https://www.the-datagarden.io/country/netherlands/subregions/"
>>> headers = {'Content-Type': 'application/json', 'Authorization': 'Bearer <access_token>'}
>>>
>>> response = requests.request("GET", url, headers=headers)
>>> print(response.json())
The response on this request should now include a geojson entry.
# Retrieving the subregions of a country
{
"subregions": [
{
"name": "Noord-Nederland",
"iso6391_language_code": "nl",
"iso_cc_2": "NL",
"region_level": 1,
"region_type": "region",
"local_region_code": "NL1",
"local_region_code_type": "nuts_code",
"url": "http://www.the-datagarden.io/subregion/d7ce0357-c511-462d-90d3-5a9e68dfc77b/",
"iso3116_region_code": null
},
{
"name": "Oost-Nederland",
"iso6391_language_code": "nl",
"iso_cc_2": "NL",
"region_level": 1,
"region_type": "region",
"local_region_code": "NL2",
"local_region_code_type": "nuts_code",
"url": "http://www.the-datagarden.io/subregion/c66f4d6e-c8aa-4fef-a201-c986a7e976a5/",
"iso3116_region_code": null
},
{
"name": "West-Nederland",
"iso6391_language_code": "nl",
"iso_cc_2": "NL",
"region_level": 1,
"region_type": "region",
"local_region_code": "NL3",
"local_region_code_type": "nuts_code",
"url": "http://www.the-datagarden.io/subregion/59088d5c-95e8-4c0d-9456-ee3506a28798/",
"iso3116_region_code": null
},
{
"name": "Zuid-Nederland",
"iso6391_language_code": "nl",
"iso_cc_2": "NL",
"region_level": 1,
"region_type": "region",
"local_region_code": "NL4",
"local_region_code_type": "nuts_code",
"url": "http://www.the-datagarden.io/subregion/dda1af3c-8d5c-4952-b8b8-ac89037e0729/",
"iso3116_region_code": null
}
]
} You can easily include the geojson in the resposne by adding a url parameter.
# retrieve Country resource with geojson
>>> url = "https://www.the-datagarden.io/country/netherlands/?include_geojson=y"
>>> headers = {'Content-Type': 'application/json', 'Authorization': 'Bearer <access_token>'}
>>>
>>> response = requests.request("GET", url, headers=headers)
>>> print(response.json())
The response on this request should now include a geojson entry.
{
"geojson": {
"type": "MultiPolygon",
"coordinates": [
[
[
[
7.194591,
53.245022
],
...
]
]
]
}
}
Finding out which data points are available for a specific country is simple with The DataGarden API. Add the query parameter `include_statistics=y` to your request to retrieve detailed information.
# retrieve Country resource
>>> url = "https://www.the-datagarden.io/country/netherlands/regional_data/?include_statistics=y"
>>> headers = {'Content-Type': 'application/json', 'Authorization': 'Bearer <access_token>'}
>>>
>>> response = requests.request("GET§", url, headers=headers, payload=payload)
>>> print(response.json())
The response includes information about the types of data available for the requested country and the structure of its subregions. This is broken into two key sections:
{
"name": "Netherlands",
"parent_region": "http://www.the-datagarden.io/continent/europe/",
"iso_cc_2": "NL",
"un_sdg_region": "EUROPE AND NORTHERN AMERICA",
"un_sub_region": "Western Europe",
"iso6391_language_code": null,
"country_statistics": {
"country_hierarchy": {
"country": {
"count": 1,
"region_level": 0,
"with_geojson": 1
},
"region": {
"count": 4,
"region_level": 1,
"with_geojson": 4
},
"province": {
"count": 12,
"region_level": 2,
"with_geojson": 12
},
"corop region": {
"count": 40,
"region_level": 3,
"with_geojson": 40
},
"city": {
"count": 355,
"region_level": 4,
"with_geojson": 355
},
"postcode-4": {
"count": 3964,
"region_level": 5,
"with_geojson": 3963
}
},
"available_data_on_country_level": {
"Health": {
"count": 11,
"sources": [
"Eurostat"
],
"to_period": "2021-01-01T00:00:00Z",
"from_period": "2011-01-01T00:00:00Z",
"period_type": [
"Y"
]
},
"Economics": {
"count": 103,
"sources": [
"UNCTAD",
"Eurostat"
],
"to_period": "2023-01-01T00:00:00Z",
"from_period": "1975-01-01T00:00:00Z",
"period_type": [
"Y"
]
},
"Demographics": {
"count": 108,
"sources": [
"Eurostat",
"United Nations"
],
"to_period": "2023-01-01T00:00:00Z",
"from_period": "1950-01-01T00:00:00Z",
"period_type": [
"Y"
]
}
}
}
}