Features
Learn about the various features available in the ckanext-gztr CKAN extension.
Brief overview of the primary purpose of ckanext-gztr
The current primary purpose of ckanext-gztr is to provide geospatial and mapping capabilities for CKAN instances to associate datasets with geospatial features. This association allows for enhanced geospatial capabilities related to CKAN such as geospatial mapping and search in addition to existing text-based metadata updates and search that CKAN provides by default. There is also a STAC API for your geospatial collections and an opt-in Geoconnex integration for contributing your water data to the Geoconnex global knowledge graph.
Why is it important to define the purpose?
The purpose helps organize what's expected for the ckanext-gztr CKAN extension to include. For features that do not exist within ckanext-gztr, they can be requested on the issues page on GitHub or found in alternative extensions such as:
- ckanext-spatial - Official CKAN extension for adding geospatial capabilities to CKAN
- ckanext-geoview - Official extension to display geospatial files and services in CKAN
Now let's explore the features for your CKAN instance added by ckanext-gztr!
Note
Public dataset search gazetteer
Commonly, CKAN data catalogs have a search box where users may type their query for datasets they'd like to find. However, this can be cumbersome when it comes to geographic data, when there is no visual method to search and identify relevant regions. The public gazetteer helps resolve this issue by providing an interactive map where users can draw a bounding box to search for datasets that have geospatial features which intersect with their drawn bounding box.
Here are things you can do with the public search gazetteer:
- Search for datasets by drawing a bounding box region on an interactive map
- Identify various named places as features on a map (e.g. cities, counties, etc.)
- View datasets with geographic data using interactive thumbnails
- Explore an interactive map of a preset region
- Filter between excluding and including statewide datasets
- Search for an address using the Nominatim API
- Filter datasets by a named place keyword
Dataset publisher gazetteer
Similar to the public gazetteer, the data curator gazetteer provides data curators a visual and interactive way to specify a dataset's relevant geographic features. Users can either select pre-loaded features or draw custom polygons. The selection is then saved and can be searched from the public dataset search page, either by drawing a bounding box using the public gazetteer or by searching a pre-loaded location's name, which is indexed as a “place keyword”.
- Selecting a named place using the category and place selectors.
- Jumping to a selected place and drawing/editing a custom polygon.
Dataset minimaps and previews
Once a dataset publisher associates a dataset with geospatial data using the data publisher gazetteer, a minimap can be displayed on the CKAN instance's dataset search page along with a map on each dataset's individual page.
For example here is a datasets page, where there is a minimap depicting the selected geospatial region by the data publisher on the left of each dataset that appears in the search results:
Here's a closer look at a single dataset search result:
The minimap can help with visually identifying datasets that have specific geospatial features as a public user.
A minimap can also be added on dataset landing pages (e.g. when clicking on a dataset in the search results). For example here is a dataset's landing page, where there is a minimap in the metadata section at the bottom:
Place keywords search
When a sysadmin of a CKAN instance provides preset feature categories for associating datasets with geospatial features, users can query by the feature names (if configured by the sysadmin).
For example if a dataset publisher selects the "Counties" geospatial feature collection and then selects "County A" and "County B", then the the user can search for those counties by name in the default CKAN dataset search page.
STAC API
ckanext-gztr is being built with the SpatioTemporal Assets Catalog (STAC) specification in mind regarding its geospatial data organization. This allows for better interoperability such as being able to explore your CKAN instance's geospatial collections through the STAC Browser while also supporting long-term extension usage and customizability.
| Endpoint | Summary |
|---|---|
/gztr/stac | Returns the STAC Catalog (catalog.json in the gztr storage) as JSON |
/gztr/stac/collections | Returns a list of STAC Collection metadata as JSON |
/gztr/stac/collections/{collection_id} | Returns a specific STAC Collection's metadata as JSON |
/gztr/stac/collections/{collection_id}/items | Returns an ItemCollection (based on GeoJSON FeatureCollection) for a specific STAC Collection as GeoJSON |
/gztr/stac/collections/{collection_id}/items/{item_id} | Returns an Item (based on GeoJSON Feature) for a specific STAC Item as GeoJSON |
Currently the STAC API /search endpoint and validation are not implemented with ckanext-gztr.
Note
Convenience Action API endpoint gztr_collection_create
The custom /api/3/action/gztr_collection_create CKAN Action API endpoint is provided for convenience and is used as documented in the installation section. This endpoint is based on the CKAN /api/3/action/file_create CKAN API Action but also adds a conversion step as it expects a GeoJSON file storing a FeatureCollection as input and then converts the data to GeoParquet and stores it in the gztr storage.
Geoconnex integration
For CKAN instances storing water data, you can sync your water data with the Geoconnex knowledge graph.
Read the Geoconnex integration section to learn more.
Get started with ckanext-gztr for your CKAN instance
Ready to add geospatial capabilities to your CKAN instance? Get started by installing ckanext-gztr.