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
• Outputs boundaries in WKT, WKB, or GeoJSON
• Support for HexWKB and SVG planned
• Zero configuration — no API keys, no downloads, no setup
• Automatically uses the latest Overture Maps release

pip install wkls

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.

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

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

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

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

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.

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.

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(), .wkb(), or .geojson(), the geometry is fetched from Overture Maps GeoParquet on S3 via Apache SedonaDB.

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

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.

• 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.