wkls makes it easy to find global administrative boundaries — from countries to cities — using readable, chainable Python syntax.
- Chainable Python syntax — Access locations naturally:
wkls.us.ca.sanfrancisco - Global coverage — 219 countries, 53 dependencies, and thousands of regions and cities
- Multiple output formats — WKT and WKB (with GeoJSON, HexWKB, SVG coming soon)
- Zero configuration — Works out of the box with no API keys or setup required
- Powered by Overture Maps — High-quality, open geospatial data from the Overture Maps Foundation
- Fast metadata lookups — Local metadata table for instant resolution; geometry fetched on-demand from S3
- Type hints included — Full type annotations for IDE autocompletion and type checking
wkls fetches geometries from Overture Maps Foundation GeoParquet data hosted on the Registry of Open Data on AWS. It automatically detects the latest available Overture Maps release.
You can instantly get geometries in formats like Well-known Text (WKT) and Well-known Binary (WKB):
import wkls
# Prints "MULTIPOLYGON (((-122.5279985 37.8155806...)))"
print(wkls.us.ca.sanfrancisco.wkt())pip install wklsNote
This command also installs Apache SedonaDB, which is used internally by WKLs.
After installing wkls, run the following commands to get started:
import wkls
# Get country geometry
usa_wkt = wkls.us.wkt()
print(f"USA geometry: {usa_wkt[:50]}...")
# Get state/region geometry (here, in WKB)
california_wkb = wkls.us.ca.wkb()
# Get city geometry (here, in WKT)
sf_wkt = wkls.us.ca.sanfrancisco.wkt()
# Check dataset version
print(f"Using Overture Maps data: {wkls.overture_version()}")
# Explore available data
print(f"Countries: {len(wkls.countries())}")
print(f"Dependencies: {len(wkls.dependencies())}")
print(f"US regions: {len(wkls.us.regions())}")
print(f"CA counties: {len(wkls.us.ca.counties())}")Some region or locality names overlap with sedonadb.dataframe.DataFrame attributes inherited by ChainableDataFrame (for example wkls.us.ne triggers the .ne “not equal” method rather than returning Nebraska). When a name collides with any DataFrame member or even Python keywords, use the already-supported dict-style access to force a lookup:
wkls["us"]["ne"].wkt() # Nebraska (avoids calling DataFrame.ne)
wkls['at']['1'].regions() # Austria's region 1You can mix attribute and dict access freely. Prefer the bracket form whenever you suspect a collision—especially with short names, abbreviations, or words that double as python operations.
wkls supports up to 3 chained attributes:
- Country/Dependencies (required) – must be a 2-letter ISO 3166-1 alpha-2 code (e.g.
us,de,fr) - Region (optional) – must be a valid region code suffix as specified by Overture (e.g.
caforUS-CA,nyforUS-NY) - Place (optional) – a name match against subtypes:
county,locality, orneighborhood
Examples:
wkls.us.wkt() # country: United States
wkls.us.ca.wkt() # region: California
wkls.us.ca.sanfrancisco.wkt() # city/county: San Francisco
wkls["us"]["ca"]["sanfrancisco"].wkt() # dictionary-style accesswkls supports the following formats:
.wkt()– Well-Known Text.wkb()– Raw binary WKB
Support for the following formats will come (back) in future versions once support is implemented in SedonaDB:
.hexwkb()– Hex-encoded WKB.geojson()– GeoJSON string.svg()– SVG path string
Chained expressions like wkls.us.ca.sanfrancisco return a WKL object. Internally, this holds a SedonaDB DataFrame containing one or more rows that match the given chain.
id country region subtype name
0 085718963fffff... US US-CA county San FranciscoIn most cases, wkls resolves to a single administrative boundary. But if there are name collisions (e.g., both a county and a locality called “San Francisco”), multiple rows may be returned.
By default, geometry methods like .wkt() will use the first matching row.
The following methods return SedonaDB DataFrames for easy exploration:
| Method | Description |
|---|---|
wkls.countries() |
List all countries |
wkls.dependencies() |
List all dependencies |
wkls.us.regions() |
List regions in the US |
wkls.us.ca.counties() |
List counties in California |
wkls.us.ca.cities() |
List cities in California |
wkls.subtypes() |
Show all distinct division subtypes |
Some countries/dependencies may not have regions, so for those
countries/dependencies you can directly call either .counties() or
.cities(), to further explore the available data.
wkls.fk.cities()You can check which version of the Overture Maps dataset is being used:
print(wkls.overture_version())
# e.g. "2026-01-21.0"print(wkls.overture_releases())
# e.g. ['2025-12-17.0', '2026-01-21.0']Use configure() to switch to a specific Overture Maps release at runtime:
wkls.configure(overture_version="2025-12-17.0")
print(wkls.overture_version()) # "2025-12-17.0"An invalid version raises a ValueError listing the available releases.
You can also pin a version via the WKLS_OVERTURE_VERSION environment variable, which is useful for CI or Docker environments:
export WKLS_OVERTURE_VERSION=2025-12-17.0Priority order: configure() > WKLS_OVERTURE_VERSION env var > auto-detect latest.
Note
overture_version(), overture_releases(), and configure() are only available at the root level, not on chained objects like wkls.us.overture_version().
You can enable debug mode to print out the underlying SQL queries
executed by SedonaDB by setting the WKLS_DEBUG environment variable to
a truthy-value:
import os
import wkls
os.environ["WKLS_DEBUG"] = "true"
print(wkls.us.ca.sanfrancisco.wkt())wkls works in two stages:
Your chained attributes — up to 3 levels — are parsed in this order:
country/dependency→ matched by ISO 2-letter code (e.g."us")region→ matched using region code suffix as specified by Overture (e.g."ca"→"US-CA")place→ fuzzy-matched against names in subtypes:county,locality, orneighborhood
This resolves to a SedonaDB DataFrame containing one or more rows from the in-memory wkls metadata table. At this stage, no geometry is loaded yet — only metadata (like name, country, region, subtype, etc.).
The geometry lookup is triggered only when you call one of the geometry methods:
.wkt().wkb()
Support for the following formats will come in future versions once implemented in SedonaDB:
.hexwkb().geojson().svg()
At that point, wkls queries the Overture division_area GeoParquet directly from S3 via Apache SedonaDB. The WHERE clause filters on low-cardinality columns (country, subtype, region, is_land) for Parquet predicate pushdown, then disambiguates city/county/localadmin results using (id = '<gers_id>' OR names.primary = '<name>'). This makes lookups resilient to either identifier changing across Overture releases — if GERS IDs stabilize, the ID match is the fast path; if the ID drifts, the name still resolves correctly.
The current Overture Maps dataset version can be checked with wkls.overture_version(). Use wkls.configure(overture_version="...") to pin a specific release, or wkls.overture_releases() to list what's available.
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.