wkls: Well-Known Locations

wkls gives you administrative boundaries — countries, regions, counties, and cities — in one line of Python.

import wkls

wkls.us.ca.sanfrancisco.wkt()
# "MULTIPOLYGON (((-122.5279985 37.8155806...)))"

• Chainable attribute access to countries, states, counties, and cities
• Precise geometries from Overture Maps Foundation — no bounding boxes, no shapefiles
• Currently, wkls outputs boundaries in WKT or WKB
• Support for GeoJSON, HexWKB, and SVG planned
• Zero configuration — no API keys, no downloads, no setup
• Automatically uses the latest Overture Maps release

Installation

pip install wkls

Usage

Countries, regions, counties, and cities

Chain up to 3 levels: country → region → county or city.

import wkls

wkls.us.wkt()                  # United States
wkls.us.ca.wkt()               # California
wkls.us.ca.sanfrancisco.wkt()  # San Francisco

Countries and dependencies use ISO 3166-1 alpha-2 codes. Regions use the code suffix from Overture (e.g. ca for US-CA). Counties and cities match by name against the Overture dataset.

Geometry formats

wkls.de.wkt()  # Well-Known Text string
wkls.de.wkb()  # Well-Known Binary bytes

Exploring the dataset

wkls.countries()       # all countries
wkls.dependencies()    # all dependencies
wkls.us.regions()      # regions in the US
wkls.us.ca.counties()  # counties in California
wkls.us.ca.cities()    # cities in California
wkls.fk.cities()       # countries without regions work too

Wildcard search

Use % for pattern matching when you're not sure of the exact name:

wkls.us.ca["%francis%"]  # matches "San Francisco"

Pinning an Overture version

wkls auto-detects the latest Overture Maps release. To pin a specific version:

wkls.configure(overture_version="2025-12-17.0")

wkls.overture_version()   # current version
wkls.overture_releases()  # available versions

Or set the WKLS_OVERTURE_VERSION environment variable:

export WKLS_OVERTURE_VERSION=2025-12-17.0

Priority: configure() > environment variable > auto-detect.

Bracket access

Some names collide with Python keywords or DataFrame methods. Use bracket syntax when attribute access doesn't work:

wkls["us"]["ne"].wkt()  # Nebraska (wkls.us.ne would call DataFrame.ne)
wkls["at"]["1"].regions()  # Austria's region "1"

You can mix attribute and bracket access freely.

How it works

wkls resolves locations in two stages:

1. Metadata resolution — your chained attributes are matched against a bundled metadata table (country by ISO code, region by code suffix, county or city by name). No geometry is loaded at this stage.

2. Geometry fetch — when you call .wkt() or .wkb(), the geometry is fetched from Overture Maps GeoParquet on S3 via Apache SedonaDB.

Contributing

We welcome contributions! Please see our Contributing Guide for details on how to get started, development setup, and submission guidelines.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details. wkls includes, references, and leverages data from the "Divisions" theme of Overture, from Overture Maps Foundation:

• © OpenStreetMap contributors. Available under the Open Database License.
• geoBoundaries. Available under CC BY 4.0.
• Esri Community Maps contributors. Available under CC BY 4.0.
• Land Information New Zealand (LINZ). Available under CC BY 4.0.

Acknowledgments

• Overture Maps Foundation for providing high-quality, open geospatial data.
• AWS Open Data Registry for hosting the dataset.
• Apache SedonaDB for the high-performance, single-node spatial query and analytics engine.