Well-Known Locations (wkls)

wkls is an open-source library maintained by Wherobots that provides easy, programmatic access to global administrative boundaries—countries, regions, cities, and more—using data from the Overture Maps Foundation. It comes pre-installed in WherobotsDB and is also available via pip. For the latest updates, see the wkls GitHub repository.

Installation

wkls comes pre-installed in WherobotsDB, so you do not need to install it separately if you’re using Wherobots Cloud. Just add import wkls to your notebook.

If you’re not using Wherobots Cloud, install wkls via pip:

pip install wkls

Quick start

import wkls

# Get the WKT geometry for the United States
usa_wkt = wkls.us.wkt()

# Get GeoJSON for California
california_geojson = wkls.us.ca.geojson()

# Get WKB for San Francisco
sf_wkb = wkls.us.ca.sanfrancisco.wkb()

The WKT for the US boundary is over 3 million characters. With wkls, it’s just wkls.us.wkt().

Geometry formats

Every location exposes three output formats:

Method	Returns
`.wkt()`	Well-Known Text (string)
`.wkb()`	Well-Known Binary
`.geojson()`	GeoJSON (string)

Use chainable dot access with ISO codes or English names:

wkls.us.ca.sanfrancisco       # ISO codes + normalized names
wkls.india.maharashtra        # English names work too
wkls.us.ca.sanfrancisco.parent  # returns California
wkls.us.ca.sanfrancisco.path    # "us.ca.sanfrancisco"

Discovery

Explore what’s available at any level of the hierarchy:

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

All discovery methods are scoped to the current chain position.

# Search at any level
wkls.search("francisco")
wkls.us.ca.search("san")

# Tab completion
dir(wkls)       # list all top-level locations
dir(wkls.us)    # list all US subdivisions

Countries without regions

Some countries/dependencies may not have regions. For those, call .counties() or .cities() directly:

wkls.fk.cities()  # cities in the Falkland Islands

Collection protocol

Location collections support standard Python protocols:

cities = wkls.us.ca.cities()
len(cities)        # count
cities[0]          # index
cities[2:5]        # slice
for c in cities:   # iterate
    print(c.path)
bool(wkls.us.ca.cities())     # truthy if non-empty

Arrow escape hatch

For advanced use cases, export the full Overture Maps record as a PyArrow table:

table = wkls.us.ca.sanfrancisco.to_arrow_table()
# Returns pyarrow.Table with columns: id, country, region, subtype,
# names, sources, admin_level, bbox, geometry, etc.
# Geometry is GeoArrow WKB with OGC:CRS84 CRS

Disambiguation

When multiple locations share a name, narrow with the parent hierarchy:

# Franklin township in Adams County, Pennsylvania
wkls.us.pa.adamscounty.franklin

# Or use the Overture ID directly
wkls.by_id("08e23a67-1c49-4857-b049-7c5b638659a3")

Version management

wkls uses Overture Maps releases as its data source. Control which version you use:

wkls.overture_releases()   # list available versions
wkls.overture_version()    # current active version
wkls.configure(overture_version="2025.01.0")  # pin a version

Or set the WKLS_OVERTURE_VERSION environment variable:

export WKLS_OVERTURE_VERSION="2025.01.0"

Troubleshooting

The following are common issues you may encounter when using wkls, along with their causes and solutions:

SedonaError: Can't infer Parquet schema for zero objects

Cause: An outdated wkls install in a local environment. pip install wkls can resolve to an older or cached version that points at an Overture Maps data path that no longer returns records. This does not apply in Wherobots Cloud, where wkls comes pre-installed in WherobotsDB.Solution:

Upgrade to the latest version: pip install --upgrade wkls.
Confirm the installed version with pip show wkls, then restart your Python session or notebook kernel so the new version is loaded.
If the error persists, reinstall without the pip cache: pip install --upgrade --no-cache-dir wkls.

NameError: name 'wkls' is not defined

Cause: wkls is available in your environment, but it has not been imported into the current session.Solution:

Add import wkls to your notebook or script before calling any wkls methods.

How it works

For a full explanation, see How it works in the wkls GitHub repository.

How to contribute

Contributions are welcome. See Contributing in the wkls GitHub repository.

Use Cases

Getting Started

Spatial Queries

WherobotsDB

Data Connections

RasterFlow

Advanced Topics

GeoStats, Map Matching & RasterFlow

Well-Known Locations (wkls)

Installation

Quick start

Geometry formats

Hierarchy navigation

Discovery

Countries without regions

Collection protocol

Arrow escape hatch

Disambiguation

Version management

Troubleshooting

How it works

How to contribute

​Installation

​Quick start

​Geometry formats

​Hierarchy navigation

​Discovery

​Countries without regions

​Collection protocol

​Arrow escape hatch

​Disambiguation

​Version management

​Troubleshooting

​How it works

​How to contribute

Installation

Quick start

Geometry formats

Hierarchy navigation

Discovery

Countries without regions

Collection protocol

Arrow escape hatch

Disambiguation

Version management

Troubleshooting

How it works

How to contribute