Install ckanext-gztr

Activate your virtual environment and navigate to your CKAN extensions installation directory

Ensure your terminal is running in your instance's virtual environment before continuing and that you're in the /usr/lib/ckan/default/src directory so that we may install extensions here.

cd /usr/lib/ckan/default/src
. ../bin/activate

Install ckanext-scheming

The ckanext-gztr extension relies on ckanext-scheming to add the interactive gazetteer to the new dataset form.

Run the following in /usr/lib/ckan/default/src to install the ckanext-scheming extension:

pip install -e "ckanext-scheming@git+https://github.com/ckan/ckanext-scheming.git"

Then in your CKAN config file (e.g., /etc/ckan/default/ckan.ini) for ckan.plugins add scheming_datasets. For example:

ckan.plugins = activity scheming_datasets

Add the preset ckanext.gztr:schemas/presets.yaml to the end of your scheming.presets config value:

scheming.presets = ckanext.scheming:presets.json ckanext.gztr:schemas/presets.yaml

If you already have a running CKAN instance with ckanext-scheming installed and a custom dataset schema then you'll want to add the following fields to your schema YAML file for the dataset publisher gazetteer to appear in the dataset metadata form:

# ckanext-gztr fields
# Interactive React gazetteer widget
- field_name: gazetteer
  label: Indicate Spatial Coverage
  form_snippet: gazetteer_widget.html
  display_snippet: null
  validators: ignore_missing gazetteer_validator
  output_validators: scheming_load_json
# Full GeoJSON (without geometries for selected features)
# as a STAC ItemCollection (based on GeoJSON FeatureCollection)
# from user's selection in data publisher gazetteer
- field_name: spatial_full
  label: Geospatial metadata
  display_snippet: gazetteer_preview.html
  form_snippet: text.html
  form_placeholder: Filled in automatically as you select areas above.

If you do not have an existing dataset schema configured for your CKAN instance, then you can add the following dataset schema to try out the gazetteer (e.g. right below the line with ckan.plugins) in the dataset metadata form:

scheming.dataset_schemas = ckanext.gztr:schemas/dataset.yaml

Install ckanext-gztr

Install ckanext-gztr and its dependencies in your activated virtual environment:

cd /usr/lib/ckan/default/src
git clone https://github.com/dathere/ckanext-gztr.git
cd ckanext-gztr
pip install -e .
pip install -r requirements.txt

Then add gztr to your ckan.plugins in your /etc/ckan/default/ckan.ini file:

ckan.plugins = activity scheming_datasets gztr

Install JTS and update the Solr schema file

Brief overview of why we're going to install JTS and update schema.xml

With ckanext-gztr, one of the main features for public usage is geospatial search on the /dataset page of a CKAN web app by drawing a bounding box over a region.

CKAN uses the open-source Apache Solr for multi-modal search. With Apache Solr there are various ways to run a spatial search. ckanext-gztr uses a similar approach to ckanext-spatial for spatial search, attempting to run a geospatial intersection filter by intersecting the user's drawn bounding box against each dataset's simplified spatial geometry field which is indexed. This spatial field is a geometry, often a Polygon or MultiPolygon, and is necessary to have the dataset searchable by location by having it indexed in Solr.

The dataset's spatial_full field is transformed into WKT geometry using the shapely Python library and named as spatial_geom in Solr as an indexed field. Then a geospatial search query is ran through the following Intersects operation against spatial_geom and the bounds of the user's drawn bounding box (mimicing the filter used by ckanext-spatial):

{{!field f=spatial_geom}}Intersects(ENVELOPE({minx}, {maxx}, {maxy}, {miny}))

Installation

However to run this geospatial search against polygons we need to install the JTS library for Solr and to configure it properly.

It may be a bit tricky to get JTS running with CKAN and Solr as intended. The CKAN development team provides preconfigured Solr Docker images for CKAN which you can refer to as an example.

To install JTS, follow the steps listed in the following admonition.

For additional information see the Solr documentation for the latest documentation on how to install JTS here.

Now you'll need to update your Solr schema file. Find the relevant sections as shown in the top-level tags below and add the sub-level content to them:

<!-- ... -->

<types>
  <!-- ... -->
  <!-- RPT field type for searching polygons with ckanext-gztr -->
  <fieldType 
      name="location_rpt" class="solr.SpatialRecursivePrefixTreeFieldType"
      spatialContextFactory="JTS"
      autoIndex="true"
      validationRule="repairBuffer0"
      distErrPct="0.025" 
      maxDistErr="0.001"  
      distanceUnits="kilometers">
  </fieldType>
</types>

<fields>
  <!-- ... -->
  <!-- Allow ckanext-gztr to index simplified geometry and place keywords -->
  <field name="spatial_geom"  type="location_rpt" indexed="true" stored="true" multiValued="true" />
  <field name="place_keywords" type="string" indexed="true" stored="true" multiValued="true"/>
  <!-- ... -->
</fields>
<!-- ... -->
<!-- Allows for searching by place keywords in the dataset search page by ckanext-gztr -->
<copyField source="place_keywords" dest="text" />

Set ckan.search.solr_allowed_query_parsers to field in your CKAN config

First check if ckan.search.solr_allowed_query_parsers exists in your CKAN config file (e.g. /etc/ckan/default/ckan.ini). Update or add it with field as the value.

ckan.search.solr_allowed_query_parsers = field

This is necessary to ensure the public bounding box spatial search works. Otherwise you may get the following error:

Dataset search error: ("Local parameters are not supported in param 'fq'.",)

Set up the gztr storage

With CKAN 2.12 there are now configurable storages, which are objects that can store files in a local filesystem, cloud, database, or elsewhere. This allows you to customize where you want to store GeoParquet files that are used throughout your installation of ckanext-gztr.

Add the following lines to your CKAN configuration file and customize it as needed:

ckan.files.storage.gztr.type = ckan:fs
ckan.files.storage.gztr.path = /var/ckan/storage/uploads/gztr
ckan.files.storage.gztr.initialize = true # Creates the `gztr` directory if it doesn't exist

The new gztr directory should be made in your filesystem at /var/ckan/storage/uploads/gztr once you run your CKAN instance. This is where the GeoParquet files will be stored, along with the catalog.json and collections.json files we'll set up soon.

Prepare your STAC and GeoJSON files

SpatioTemporal Asset Catalogs (STAC) with ckanext-gztr

The STAC specification is a common language to describe geospatial information, which can help make geospatial data easier to use, index, and discover.

We make use of the STAC specification throughout ckanext-gztr, including both how data models are organized and for the STAC API endpoints that get added to your CKAN instance.

Upload your preset GeoJSON FeatureCollection files

As a sysadmin you'll provide GeoJSON files that are used throughout ckanext-gztr including for the public search gazetteer, the dataset publisher gazetteer, and the place keywords search functionality.

The GeoJSON files must be in a specific format so that ckanext-gztr can properly use them. Here are the conditions followed by an example GeoJSON file:

• A GeoJSON file must be a FeatureCollection using WGS84 as its geographic coordinate reference system.
• Each Feature must have a unique id entry. The value of the id entry is unique across all Features in the FeatureCollection. Therefore we do not recommend using a label such as a name for the ID, but rather a unique string or number such as basing the id on an existing unique ID system for the FeatureCollection.
• Each Feature must also have a title entry in its properties dictionary where the value of title is a human-readable name for the Feature, such as a county name.

Here we provide a truncated part of a GeoJSON file Public_Water_Systems.geojson for NMWDC with data provided by Geoconnex (we omit the value for coordinates here as it would be too long):

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "pws_id": "063500110",
        "title": "JEMEZ PUEBLO", 
        "source_url": "https://www.hydroshare.org/resource/b11b8982eebd4843833932f085f71d92/data/contents/temm.geojson",
        "data_source": "SimpleLab",
        "geoconnex_uri": "https://geoconnex.us/ref/pws/063500110"
      },
      "id": "063500110", 
      "geometry": {
        "type": "MultiPolygon",
        "coordinates": [...]
      }
    },
    ...
  ]
}

Notice that the ID is based on an existing ID system for public water systems in the USA provided by the EPA as described in collections.json. We also have title in the properties of the Feature which is a human-readable name describing the feature. You can add other common metadata such as a description and geoconnex_uri as described in the Geoconnex integration documentation.

You'll now need to upload the GeoJSON file to your gztr storage through the gztr_collection_create custom CKAN API Action endpoint which converts your GeoJSON file into a GeoParquet file. Since we're using the CKAN API, you should ensure your CKAN instance is running.

Here is an example of uploading a GeoJSON file NM_HUC8_Sub_Basins.geojson through the CKAN API using curl in a Bash shell:

read -p 'CKAN sysadmin API Token: ' api_token
curl -H "Authorization: $api_token" -X POST -F upload=@./NM_HUC8_Sub_Basins.geojson -F storage=gztr http://localhost:5000/api/3/action/gztr_collection_create

Here is the output that is returned:

{
  "help": "http://localhost:5000/api/3/action/help_show?name=gztr_collection_create",
  "success": true,
  "result": {
    "name": "nm_huc8_sub_basins.parquet",
    "location": "nm_huc8_sub_basins.parquet", 
    "storage": "gztr",
    "content_type": "application/octet-stream",
    "size": 6394247,
    "hash": "91437835777a3e23633d36a0021c004e",
    "algorithm": "md5",
    "created": "2026-08-18T09:32:52.751045+00:00",
    "storage_data": {},
    "id": "a13a09bc-8694-40f8-a082-bc6bca0c21a7",
    "owner_type": "user",
    "owner_id": "255d924c-f5fc-4dc1-9204-1e9bfa899219",
    "pinned": false
  }
}

Now copy the location stem that is returned after uploading because we will use it for later, for example nm_huc8_sub_basins (case-sensitive! notice the file name is not exactly the same as the original GeoJSON file). Do this for each file you upload, as you'll need the value for when you define your STAC Catalog and STAC Collections in the next steps.

STAC Catalog (catalog.json)

You'll need to define a catalog.json file which is a top-level description of your the geospatial data available from your CKAN instance using STAC. Here is a truncated example of a STAC Catalog defined in the catalog.json file for the New Mexico Water Data Catalog.

{
  "id": "nmwdc",
  "stac_version": "1.1.0",
  "type": "Catalog",
  "title": "New Mexico Water Data Catalog STAC API",
  "description": "Geospatial collections and features used for dataset publishing and search by the New Mexico Water Data Catalog, organized through the SpatioTemporal Asset Catalogs (STAC) specification.",
  "links": [
    {
      "href": "https://catalog.newmexicowaterdata.org/gztr/stac",
      "rel": "self",
      "type": "application/json"
    },
    {
      "href": "https://catalog.newmexicowaterdata.org/gztr/stac",
      "rel": "root",
      "type": "application/json"
    },
    {
      "href": "https://catalog.newmexicowaterdata.org/gztr/stac/collections",
      "rel": "collections",
      "type": "application/json"
    },
    {
      "href": "https://catalog.newmexicowaterdata.org/gztr/stac/collections/public_water_systems",
      "rel": "child",
      "type": "application/json",
      "title": "Public Water Systems"
    }
  ]
}

Notice that the returned ID value public_water_systems is used as one of the child links as a STAC Collection at the end in the href URL value. If we were using the HUC8 Sub basins file from the previous example, then the value would be nm_huc8_sub_basins.

STAC Collections (collections.json)

Next you'll need to define your geospatial collections as a STAC Collection in a collections.json file. Here's a truncated example for NMWDC:

[
  {
    "id": "public_water_systems",
    "type": "Collection",
    "stac_version": "1.1.0",
    "title": "Public Water Systems",
    "description": "Public Water Systems as defined by the U.S. Environmental Protection Agency (EPA) which intersect with New Mexico.",
    "providers": [
      {
        "name": "U.S. Environmental Protection Agency (EPA)",
        "description": "Independent agency of the United States government focused on environmental protection concerns.",
        "roles": [
          "producer"
        ],
        "url": "https://epa.gov"
      },
      {
        "name": "Geoconnex",
        "description": "Geoconex Reference API hosting the public water systems geospatial data. The public water systems for New Mexico are a subset of the data hosted by Geoconnex.",
        "roles": [
          "host"
        ],
        "url": "https://reference.geoconnex.us/collections/pws"
      }
    ],
    "extent": {
      "spatial": {
        "bbox": [
          [
            -180.0,
            -90.0,
            180.0,
            90.0
          ]
        ]
      },
      "temporal": {
        "interval": [
          [
            null,
            null
          ]
        ]
      }
    },
    "license": "proprietary",
    "links": [
      {
        "href": "https://catalog.newmexicowaterdata.org/gztr/stac/collections/public_water_systems",
        "rel": "self",
        "type": "application/json"
      },
      {
        "href": "https://catalog.newmexicowaterdata.org/gztr/stac/collections",
        "rel": "parent",
        "type": "application/json"
      },
      {
        "href": "https://catalog.newmexicowaterdata.org/gztr/stac",
        "rel": "root",
        "type": "application/json"
      },
      {
        "href": "https://catalog.newmexicowaterdata.org/gztr/stac/collections/public_water_systems/items",
        "rel": "items",
        "type": "application/geo+json"
      }
    ]
  }
]

Notice that the id value public_water_systems for the Public Water Systems collection is from the previous upload step. If we were using the HUC8 Sub basins file from a previous example, then the value would be nm_huc8_sub_basins.

Upload catalog.json and collections.json to the gztr storage

Now that you have your STAC Catalog and STAC Collections files prepared, you'll need to upload them to the gztr storage.

Here is an example of uploading the catalog.json and collections.json files through the CKAN API using curl in a Bash shell (make sure you use a sysadmin's API token):

read -p 'CKAN sysadmin API Token: ' api_token
curl -H "Authorization: $api_token" -X POST -F upload=@./catalog.json -F storage=gztr http://localhost:5000/api/3/action/file_create
curl -H "Authorization: $api_token" -X POST -F upload=@./collections.json -F storage=gztr http://localhost:5000/api/3/action/file_create

Verify ckanext-gztr works as expected

Now the interactive gazetteer should be available on the form for adding and editing a dataset along with a public search map gazetteer.

For example you can run a local CKAN instance by running the following in your activated virtual environment:

cd /usr/lib/ckan/default/src/ckan
ckan -c /etc/ckan/default/ckan.ini run

Then you should have your local CKAN instance running which you can open in your web browser at http://localhost:5000. If you visit the Datasets page at http://localhost:5000/dataset then you should see an interactive search gazetteer to search by bounding box intersections and a dataset publisher gazetteer in the new dataset form.

If you visit http://localhost:5000/api/3/action/status_show then there should be a JSON response where gztr is present in the result.extensions array.

You can also now explore your STAC API at http://localhost:5000/gztr/stac.