Getting Zones
This API endpoint facilitates the selection of zones within a ISEA3H Discrete Global Grid System (DGGS) using various input methods. The DGGS provides a framework for breaking down the Earth's surface into a grid of zones, which can be queried using different parameters. There are three main methods to select zones:
- By using a lower resolution zone
- By an Area of Interest (AOI)
- By using a GeoJSON
Required parameters
Go with one of the three options to select zones.
by Zone
Global Identifier (_gid):
This parameter allows you to select the zone using the Global Identifier (gid). This will return all the zones that fall within that zone.
Resolution of Global Identifier (_gid_res):
This parameter must go along with the _gid to specify the resolution of that cell. Make sure that this number is lower than the one specified in _res.
by AOI
Area of Interest (AOI) (_aoi):
This parameter allows you to select zones within the DGGS based on predefined Areas of Interest(AOI), such as regions or administrative boundaries (e.g., us_ca for California). The AOI is selected using an autocomplete feature that pulls from a list of available areas, making it easy to choose the desired region.
by GeoJSON
GeoJSON (_geojson):
This parameter allows you to use your own GeoJSON to select zones. As this is a spatial query the time it takes to get a response may be significantly longer than e.g. using an AOI. The query time depends on the complexity of the polygon and the area it covers. If the response does not cover the entire GeoJSON that you posted, than you probably hit the _limit of zones to be returned.
Optional parameters
Resolution Level (_res):
The DGGS grid can be queried at various resolution levels, ranging from 1 to 16. Higher resolutions correspond to smaller zones, providing more detailed spatial data. This field allows users to specify the desired resolution, with validation ensuring the input falls within the valid range.
Geometry Selection (_geometry):
Users can specify the type of geometry they want to include in the response. Options include:
- none: No geometry is included.
- center: The response includes the center point of each selected zone.
- region: The polygon geometry of the selected zone is included.
Data Table (_data):
This field allows users to specify which data table they want to query within the DGGS framework. It could be any dataset that is spatially enabled and linked to the DGGS, such as wildfire incidents (cal_fire). Checkout the endpoint /rpc/isea3h_data_dst for a list of available datasets.
Date Range (_startdate, _enddate):
Users can filter the data based on a specific date range. The start and end dates define the temporal boundaries for the data to be queried, which is particularly useful for time-sensitive data like environmental monitoring. It is important to note that all datasets in the system are in UTC+00:00 (opens in a new tab).
Feature Collection (_fc):
You can choose whether the output should be a GeoJSON Feature Collection (a single object containing multiple features) or an array of individual GeoJSON features. This option is useful for different use cases, such as visualizing data on a map or performing further analysis.
Children Zones (_children):
This option allows you to retrieve the identifiers (gid) of all child zones within the selected area. It is useful when working with this hierarchical grid systems where zones can be subdivided into smaller cells.
Neighbor Zones (_neighbor):
This field enables you to include the neighboring zones of the selected zones. It is particularly useful for edge analysis or understanding spatial relationships between adjacent zones.
Dense Mode (_dense):
This setting controls whether zones with NULL values should be included in the response. It can be useful when users need a complete dataset with all possible zones, regardless of whether they contain data.
Limit the Number of zones (_limit):
To prevent overwhelming responses, this parameter allows you to limit the number of zones returned by the query. It ensures that the output is manageable and relevant to your needs. However it is also limited by your permission rights.