{"id":25817284,"url":"https://github.com/landscapegeoinformatics/pydggsapi","last_synced_at":"2026-03-11T13:12:23.291Z","repository":{"id":266690865,"uuid":"896104632","full_name":"LandscapeGeoinformatics/pydggsapi","owner":"LandscapeGeoinformatics","description":"A python FastAPI OGC DGGS API implementation","archived":false,"fork":false,"pushed_at":"2025-02-17T21:56:30.000Z","size":360,"stargazers_count":2,"open_issues_count":4,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-17T22:32:25.486Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LandscapeGeoinformatics.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-11-29T14:54:26.000Z","updated_at":"2025-02-17T21:56:33.000Z","dependencies_parsed_at":null,"dependency_job_id":"3a6cb290-d379-4317-aa4a-78c5672d2ab4","html_url":"https://github.com/LandscapeGeoinformatics/pydggsapi","commit_stats":null,"previous_names":["landscapegeoinformatics/pydggsapi"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LandscapeGeoinformatics%2Fpydggsapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LandscapeGeoinformatics%2Fpydggsapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LandscapeGeoinformatics%2Fpydggsapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LandscapeGeoinformatics%2Fpydggsapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LandscapeGeoinformatics","download_url":"https://codeload.github.com/LandscapeGeoinformatics/pydggsapi/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241112440,"owners_count":19911689,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-02-28T06:33:45.742Z","updated_at":"2026-03-11T13:12:23.284Z","avatar_url":"https://github.com/LandscapeGeoinformatics.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pydggsapi\n\n![Version](https://img.shields.io/badge/version-0.1.5-blue)\n\nA python FastAPI OGC DGGS API implementation\n\nhttps://pydggsapi.readthedocs.io/en/latest/\n\n## OGC API - Discrete Global Grid Systems\n\nhttps://ogcapi.ogc.org/dggs/\n\nOGC API - DGGS specifies an API for accessing data organised according to a Discrete Global Grid Reference System (DGGRS). A DGGRS is a spatial reference system combining a discrete global grid hierarchy (DGGH, a hierarchical tessellation of zones to partition) with a zone indexing reference system (ZIRS) to address the globe. Aditionally, to enable DGGS-optimized data encodings, a DGGRS defines a deterministic for sub-zones whose geometry is at least partially contained within a parent zone of a lower refinement level. A Discrete Global Grid System (DGGS) is an integrated system implementing one or more DGGRS together with functionality for quantization, zonal query, and interoperability. DGGS are characterized by the properties of the zone structure of their DGGHs, geo-encoding, quantization strategy and associated mathematical functions.\n\n![](bids25_fig1.png)\n## Setup and Dependencies\n\n1. setup virtual environment with micromamba file and active it. \n\n```\nmicromamba create -n \u003cname\u003e  -f micromamba_env.yaml\nmircomamba activate \u003cname\u003e\n```\n\nIn order to use DGGRID, the dggrid executable needs to be available. You can compile it yourself, or install into the conda/micromamba environment from conda-forge:\n\n```\nmicromamba install -c conda-forge dggrid\n```\n\n2. run poetry to install dependencies\n   \n   ```\n   poetry install\n   ```\n\n3. create local .env file from env.sample \n\n```\ndggs_api_config=\u003cPath to TinyDB\u003e\nDGGRID_PATH=\u003cPath to dggrid executable\u003e\n```\n\n4. Start the server for development: \n   \n   ```\n   export POETRY_DOTENV_LOCATION=.env \u0026\u0026 poetry run python pydggsapi/main.py \n   ```\n\n## Mini Howto\n\n### Collections, Collection Providers and DGGRS providers\n\nThe are two parts of configurations. \n\nUser Configurations:\n\n- Collections : to define a collection with meta data, how to access the data (collection provider) and which dggrs it support (dggrs provider).\n\nSystem configurations:\n\n- Collection Providers : Implementation to access the data.\n- DGGRS  providers :  Implementation to support API endpoint operations for DGGS\n\nEach data collection must be already formatted  in one of the supported DGGRS implementation (ie. at least one columns to represent the zone ID)\n\n#### An example for Collections definition (in TinyDB):\n\nThe below example shows how a collection is defined : \n\n1. The collections ID (suitability_hytruck),  it is the key of the collection.\n\n2. meta data (title, description) \n\n3. collection provider : \n   \n   - providerId          : the collection provider id that defined in [collection_providers section](#collection_provider_id)\n   - dggrsId               : the dggrs ID that defined in [dggrs section](#dggrs_provider_id). It indicate the dggrs that comes with the data.\n   - maxzonelevel    : the maximum refinement level that is support by the data with the dggrs defined above.\n   - getdata_params :  it is collections provider specific, It use to provide details parameters for the get_data function implemented by collection providers.\n     \n     ```\n     \"collections\": {\"1\": \n              {\"suitability_hytruck\": \n                  {\"title\": \"Suitability Modelling for Hytruck\",\n                    \"description\": \"Desc\", \n                    \"collection_provider\": {\n                            \"providerId\": \"clickhouse\", \n                            \"dggrsId\": \"igeo7\",\n                             \"maxzonelevel\": 9,\n                             \"getdata_params\": \n                                 { \"table\": \"testing_suitability_IGEO7\", \n                                    \"zoneId_cols\": {\"9\":\"res_9_id\", \"8\":\"res_8_id\", \"7\":\"res_7_id\", \"6\":\"res_6_id\", \"5\":\"res_5_id\"},\n                                    \"data_cols\" [\"modelled_fuel_stations\",\"modelled_seashore\",\"modelled_solar_wind\",\n                                    \"modelled_urban_nodes\", \"modelled_water_bodies\", \"modelled_gas_pipelines\",\n                                    \"modelled_hydrogen_pipelines\", \"modelled_corridor_points\",  \"modelled_powerlines\", \n                                    \"modelled_transport_nodes\", \"modelled_residential_areas\",  \"modelled_rest_areas\", \n                                    \"modelled_slope\"]\n                                  }\n                        }\n                    }\n              } \n          }\n     ```\n\n#### An example for Collection Providers definition (in TinyDB):\n\nThe below example shows how a collection provider is defined : \n\n\u003ca name=\"collection_provider_id\"\u003e\u003c/a\u003e\n\n1. collection provider ID : clickhouse (this will be used in the collections config under the collection_provider section)\n\n2. classname : [\"clickhouse_collection_provider\\.ClickhouseCollectionProvider\"](pydggsapi/dependencies/collections_providers/clickhouse_collection_provider.py) the implementation of the class (under [dependencies/collections_providers folder](pydggsapi/dependencies/collections_providers))\n\n3. initial_params : parameters to initializing the class\n\n```\n\"collection_providers\": {\"1\": \n        {\"clickhouse\": \n            {\"classname\": \"clickhouse_collection_provider.ClickhouseCollectionProvider\", \n              \"initial_params\": \n                      {\"host\": \"127.0.0.1\", \n                       \"user\": \"user\",\n                       \"password\": \"password\", \n                       \"port\": 9000, \n                       \"database\": \"DevelopmentTesting\"} \n              }\n        }\n}\n```\n\n**Collection provider - Zarr**\n\nCollection provider to support Zarr data format with Xarray DataTree.\n\n- The Zarr collection provider uses xarray to support Zarr data format\n- Each refinement level (resolution) is treated as a group in Zarr\n- It will return all data variables\n- It holds a dictionary to the xarray object for each data source.\n- Data sources (folder path) can be specified in either:\n  - initial_params will load the data source at the start.\n\nData source defined in init_params\n\n```\n\"collection_providers\": {\"2\": \n        {\"zarr\": \n            {\"classname\": \"zarr_collection_provider.ZarrCollectionProvider\", \n              \"initial_params\": { \n                          \"datasources\": {\n                                      \"my_zarr_data\": {\n                                                    \"filepath\": \"\u003cpath to zarr folder\u003e\",\n                                                   \"zones_grps\" : { \"4\": \"res4\", \"5\": \"res5\"}\n                                        } \n                           } \n                       }\n              }\n        }\n}\n```\n\nData source defined in Collections\n\n- The datasource_id `my_zarr_data` must match with the id that defined in above ZarrCollectionProvider.\n\n```\n\"collections\": {\"2\": \n                {\"suitability_hytruck_zarr\": \n                    {\"title\": \"Suitability Modelling for Hytruck for Zarr Data format\",\n                      \"description\": \"Desc\", \n                      \"collection_provider\": {\n                              \"providerId\": \"zarr\", \n                              \"dggrsId\": \"igeo7\",\n                               \"maxzonelevel\": 9,\n                               \"getdata_params\": { \n                                       datasource_id: \"my_zarr_data\",\n                                      \"filepath\": \"\u003cpath to zarr folder\u003e\",\n                                      \"zones_grps\" : { \"4\": \"res4\", \"5\": \"res5\"}\n                                  } \n                               }\n                          }\n                      }\n                } \n            }\n```\n\n#### An example for DGGRS providers definition (in TinyDB):\n\nThe following configuration defines a dggrs provider with : \n\n\u003ca name=\"dggrs_provider_id\"\u003e\u003c/a\u003e\n\n1. dggrs provider ID : igeo7 and h3 (this will be used in the collections config under the collection_provider section)\n\n2. ogc dggs API required descriptions for dggrs. (ex. title, shapeType etc.)\n\n3. classname : \"igeo7_dggrs_provider\\.IGEO7Provider\", \"h3_dggrs_provider\\.H3Provider\" the implementation class info (under [dependencies/dggrs_providers folder](pydggsapi/dependencies/dggrs_providers))\n\n```\n\"dggrs\": {\"1\": \n        {\"igeo7\": \n            {\"title\": \"ISEA7H z7string\",\n             \"description\": \"desc\", \n             \"crs\": \"wgs84\", \n             \"shapeType\": \"hexagon\", \n             \"definition_link\": \"http://testing\", \n             \"defaultDepth\": 5, \n             \"classname\": \"igeo7_dggrs_provider.IGEO7Provider\" }\n        },\n        \"2\": \n        {\"h3\": \n            {\"title\": \"h3\", \n            \"description\": \"desc\", \n            \"crs\": \"wgs84\", \n            \"shapeType\": \"hexagon\", \n            \"definition_link\": \"http://h3test\", \n            \"defaultDepth\": 5, \n            \"classname\": \"h3_dggrs_provider.H3Provider\"}\n        }\n}\n```\n\n## Acknowledgments\n\nThis software is being developed by the [Landscape Geoinformatics Lab](https://landscape-geoinformatics.ut.ee/expertise/dggs/) of the University of Tartu, Estonia.\n\nThis work was funded by the Estonian Research Agency (grant number PRG1764, PSG841), Estonian Ministry of Education and Research (Centre of Excellence for Sustainable Land Use (TK232)), and by the European Union (ERC, [WaterSmartLand](https://water-smart-land.eu/), 101125476 and Interreg-BSR, [HyTruck](https://interreg-baltic.eu/project/hytruck/), #C031).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flandscapegeoinformatics%2Fpydggsapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flandscapegeoinformatics%2Fpydggsapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flandscapegeoinformatics%2Fpydggsapi/lists"}