Skip to main content
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. With wkls, you can create spatial boundaries for any country, region, or city in the world with a few lines of code and export them in multiple formats. For the latest updates, see the wkls GitHub repository.

​
Benefits

wkls replaces the need to find datasets, download large files, and manage complex data pipelines to find geographic boundaries for your areas of interest. For example, the Well-Known Text representation for the geographic boundary of the United States is 3,358,747 characters long! Inputting that manually would be a nightmare. With wkls, all you have to do is type wkls.us.wkt() to retrieve it.
Don’t believe us? Try it yourself! Run print(str(len(wkls.us.wkt()))) to see the actual character count.

​
Key features

  • Readable Syntax: Uses a chainable, “dot-notation” syntax to access locations (e.g., wkls.us.ca.sanfrancisco).
  • Direct Data Access: Fetches GeoParquet data directly from the Overture Maps Foundation, eliminating the need for manual downloads or data management.
  • Multiple Formats: Can export geometries in several standard formats, including:
    • WKT (Well-Known Text)
    • WKB (Well-Known Binary)
    • HexWKB (Hexadecimal Well-Known Binary)
    • GeoJSON
    • SVG (Scalable Vector Graphics)
  • Exploration Helpers: Includes helper methods to list available countries, dependencies, regions, and cities (e.g., wkls.us.regions()).

​
Example usage

# Get the Well-Known Text (WKT) for the United States
usa_wkt = wkls.us.wkt()

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

# Get SVG for San Francisco
sf_svg = wkls.us.ca.sanfrancisco.svg()

​
Helper functions

The following methods return Pandas DataFrames for easy exploration:
MethodDescription
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

​
Countries without regions

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. For example, to list all the cities in the Falkland Islands, run the following: 
import wkls
wkls.fk.cities()

​
Installation

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

​
How it works

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

​
How to contribute

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