cf-regions

Experimental Python library for mapping and lookup of CF Standardized Region List names to geometries and region hierarchy. The CF Standardized Region List is a controlled vocabulary of region names for Earth science data. It is part of the CF Conventions and based on the NASA GCMD keyword list for locations.

Features

• Offline coordinate-to-region lookup
• CF Standardized Region Lists 1 through 5
• Simple name results or detailed, provenance-rich matches
• Region metadata, hierarchy, and low/high-detail GeoJSON shapes
• Versioned spatial interpretation profiles
• A typed Python API and shell-friendly CLI

The package includes all required vocabulary and geometry resources and does not download data during lookup.

Installation

Install from PyPI:

python -m pip install cf-regions

To work on the current source checkout instead:

git clone https://github.com/ysorge/cf-regions.git
cd cf-regions
python -m pip install -e ".[dev]"

Quick start

For a simple lookup of region names covering a coordinate, run:

cfregions lookup --lonlat "-90.0, 25.0"

In Python:

import cfregions
names = cfregions.match_region_names(longitude=-90.0, latitude=25.0)
names

Understanding the results

A point can match several valid regions. Direct geometry matches, proximity to diagnostic sections, and semantic hierarchy ancestors are kept distinguishable in detailed results. The selected CF vocabulary version and spatial interpretation profile are independent and are both included in provenance.

For the scientific meaning of the mapping, its upstream sources, and known limitations, read Data sources and mapping method. The Mapping guidelines explain why these shapes are explicit, versioned interpretations rather than official CF boundaries.

Spatial interpretation profiles

cf-regions uses spatial interpretation profiles to map CF region names to geometries and region hierarchy. This allows the same CF vocabulary to be interpreted differently for different scientific purposes or domains, while retaining the same stable region names and descriptions. Each profile is self-contained and immutable, with its own declared geometry sources, hierarchy, and lookup semantics. The built-in default profile is cfregions-default. It is the only profile bundled with the package.

Documentation

• API usage — lookups, functions, return values, profiles, geometry, hierarchy, and errors
• CLI usage — commands, formats, pipelines, and exports
• Data sources and mapping method — how matches are produced
• Spatial interpretation profiles — profile architecture and extension model
• Spatial profile file format — authoring profile data
• Mapping guidelines — design and scientific rules
• Dataset maintenance — updating bundled CF and mapping data
• Data licenses — source terms and attribution

Development and support

For a development checkout:

git clone https://github.com/ysorge/cf-regions.git
cd cf-regions
python -m pip install -e ".[dev]"
pytest

Report bugs and request features through GitHub Issues. Report security vulnerabilities privately as described in the security policy.

Contributing

Contributions are welcome through issues and pull requests. Please open an issue first for substantial features, API changes, or new spatial interpretations. Small fixes and documentation improvements may be submitted directly. See the contribution guide and Code of conduct.

Authors and maintainership

cf-regions was initiated and originally developed by Yves Sorge during the CF Conventions Community Workshop 2026 at ECMWF in Bonn, Germany. The project is currently maintained by its original author.

Additional contributors are recorded in AUTHORS.md and the repository history. Maintainer responsibility may move to another person or organization without replacing the authorship of existing contributions.

License

The cf-regions source code is licensed under the Apache License 2.0 (Apache-2.0). Bundled data retains the separate terms documented in Data licenses. Downstream users must preserve applicable source notices and attributions.