Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.wherobots.com/llms.txt

Use this file to discover all available pages before exploring further.

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

wkls comes pre-installed in WherobotsDB, so you do not need to install or import it separately if you’re using Wherobots Cloud.
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.