wkls makes it easy to find global administrative boundaries — from countries to cities — using readable, chainable Python syntax.

It reads Overture Maps Foundation GeoParquet data (version 2025-09-24.0) directly from the AWS Open Data Registry.

You can instantly get geometries in formats like Well-known Text (WKT), Well-known Binaries (WKB), HexWKB, GeoJSON, and SVG:

import wkls

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

#prints "2025-09-24.0"
print(wkls.overture_version())

pip install wkls

This command also loads DuckDB with its related spatial extension.

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
california_geojson = wkls.us.ca.geojson()

# Get city geometry
sf_svg = wkls.us.ca.sanfrancisco.svg()

# 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())}")

wkls supports up to 3 chained attributes:

1. Country/Dependencies (required) – must be a 2-letter ISO 3166-1 alpha-2 code (e.g. us, de, fr)
2. Region (optional) – must be a valid region code suffix as specified by Overture (e.g. ca for US-CA, ny for US-NY)
3. Place (optional) – a name match against subtypes: county, locality, or neighborhood

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 access

wkls supports the following formats:

• .wkt() – Well-Known Text
• .wkb() – Raw binary WKB
• .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 Pandas DataFrame containing one or more rows that match the given chain.

        id           country    region   subtype       name     
0  085718963fffff...   US       US-CA    county    San Francisco

In 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 Pandas DataFrames for easy exploration:

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())

> "2025-09-24.0"

Note: The overture_version() method is only available at the root level, not on chained objects like wkls.us.overture_version().

wkls works in two stages:

Your chained attributes — up to 3 levels — are parsed in this order:

1. country/dependency → matched by ISO 2-letter code (e.g. "us")
2. region → matched using region code suffix as specified by Overture (e.g. "ca" → "US-CA")
3. place → fuzzy-matched against names in subtypes: county, locality, or neighborhood

This resolves to a Pandas DataFrame containing one or more rows from the in-memory wkls metadata table. At this stage, no geometry is loaded yet — only metadata (like id, name, region, subtype, etc.).

The geometry lookup is triggered only when you call one of the geometry methods:

• .wkt()
• .wkb()
• .hexwkb()
• .geojson()
• .svg()

At that point, wkls uses the previously resolved GERS ID to query the Overture division_area GeoParquet directly from S3.

The current Overture Maps dataset version can be checked with wkls.overture_version().

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.
• DuckDB for fast analytical queries with spatial support.
• AWS Open Data Registry for hosting the dataset.