The SubRegion Resource

Subregion detail Subregions Geojson

The SubRegion resource is a core component of The DataGarden framework, structuring geographical entities into a nested hierarchy. It facilitates seamless navigation by querying parent resources to retrieve associated child regions while maintaining clarity through distinct region types at each level.

Hierarchical Structure

The SubRegion resource categorizes geographical entities into tiers, each defined by specific region types, ensuring a clear and logical progression through the hierarchy. This hierarchy is unique to each country and is typically based on the country’s economic regions.

For example, the hierarchy for the United States is as follows:

This tiered and type-based structure allows for precise and intuitive navigation within the geographical hierarchy.

See in Country resource documentation in the `available_data` section how you can use the `include_statistics` query parameter to get the overview of the regional hierarchy.

Functionality and Metadata

The SubRegion resource provides both hierarchical organization and informational insights:

The SubRegion resource combines hierarchical organization with rich metadata, serving as a foundational element of The DataGarden ecosystem for managing and exploring geographical data.

Retrieving a subregion resource.

Authentication Required - Subregion Plan

Subsciption plan needed depends on subregion level being accessed. See Subregion Access Levels for more details.


A subregion resource can be retrieved with a simple GET request using the uuid of the subregion. The uuid can be retrieved from the parent region resource using the `subregions` url extension.

# retrieve World resource
>>> url = "https://www.the-datagarden.io/subregion/d7ce0357-c511-462d-90d3-5a9e68dfc77b/"
>>> 
>>> 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 give you the details of the world resource.

# Subregion details
{
	"name": "Noord-Nederland",
	"parent_region": 204,
	"local_region_code": "NL1",
	"local_region_code_type": "nuts_code",
	"iso3116_region_code": null,
	"iso6391_language_code": "nl",
	"iso_cc_2": "NL",
	"region_level": 1,
	"region_type": "region",
	"parent_url": "http://www.the-datagarden.io/country/netherlands/",
	"center_point": null
}

See for more details on the fields in this resposne the models section op this documentation.

Retrieving the subregions from a subregion.

Adding the `subregions` url extension to the subregion resource will return all the subregions for that subregion.

# retrieve World resource
>>> url = "https://www.the-datagarden.io/subregion/d7ce0357-c511-462d-90d3-5a9e68dfc77b/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 contains all the subregions for the subregion including their resource urls.

# Subregions for subregion
{
	"subregions": [
		{
			"name": "Drenthe",
			"iso6391_language_code": "",
			"iso_cc_2": "NL",
			"region_level": 2,
			"region_type": "province",
			"local_region_code": "NL13",
			"local_region_code_type": "nuts_code",
			"url": "http://www.the-datagarden.io/subregion/7032581f-aa95-48dc-b0a8-92f02f9811db/",
			"iso3116_region_code": null
		},
		{
			"name": "Friesland",
			"iso6391_language_code": "",
			"iso_cc_2": "NL",
			"region_level": 2,
			"region_type": "province",
			"local_region_code": "NL12",
			"local_region_code_type": "nuts_code",
			"url": "http://www.the-datagarden.io/subregion/5f92d380-47b1-4d23-abe0-26c94e35039f/",
			"iso3116_region_code": null
		},
		{
			"name": "Groningen",
			"iso6391_language_code": "",
			"iso_cc_2": "NL",
			"region_level": 2,
			"region_type": "province",
			"local_region_code": "NL11",
			"local_region_code_type": "nuts_code",
			"url": "http://www.the-datagarden.io/subregion/7df3ab59-26e5-4754-b4ee-69daa9be478d/",
			"iso3116_region_code": null
		}
	]
}

See for more details on the fields in this resposne the models section op this documentation.

Retrieving the geojson for a subregion.

As with the country resource, adding the `include_geojson=y` url parameter to the subregion resource will include the geojson for that subregion.

# retrieve World resource
>>> url = "https://www.the-datagarden.io/subregion/d7ce0357-c511-462d-90d3-5a9e68dfc77b/subregions/?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 contains all the subregions for the subregion including their resource urls.

# Subregions for subregion
				{
					"name": "Noord-Nederland",
					"parent_region": 204,
					"local_region_code": "NL1",
					"local_region_code_type": "nuts_code",
					"iso3116_region_code": null,
					"iso6391_language_code": "nl",
					"iso_cc_2": "NL",
					"region_level": 1,
					"region_type": "region",
					"parent_url": "http://www.the-datagarden.io/country/netherlands/",
					"center_point": null,
					"geojson": {
						"type": "MultiPolygon",
						"coordinates": [
							[
								[
									[
										6.874905,
										53.408013
									],
									[
										6.887685,
										53.394759
									],
									...
								]
							]
						]
					}
				}