> ## 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.

# Well-Known Locations (wkls)

> Well-Known Locations, or `wkls` is a Python library designed to help you find geographic boundaries for any location in the world.

`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](https://overturemaps.org/). It comes pre-installed in WherobotsDB and is also available via `pip`.

For the latest updates, see the [wkls GitHub repository](https://github.com/wherobots/wkls).

## Installation

<Tip>
  `wkls` comes **pre-installed in WherobotsDB**, so you do not need to install it separately if you're using [Wherobots Cloud](https://cloud.wherobots.com). Just add `import wkls` to your notebook.
</Tip>

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

```bash theme={"system"}
pip install wkls
```

## Quick start

```python theme={"system"}
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()
```

<Tip>
  The WKT for the US boundary is over 3 million characters. With `wkls`, it's just `wkls.us.wkt()`.
</Tip>

## Geometry formats

Every location exposes three output formats:

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

## Hierarchy navigation

Use chainable dot access with ISO codes or English names:

```python theme={"system"}
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.

```python theme={"system"}
# 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:

```python theme={"system"}
wkls.fk.cities()  # cities in the Falkland Islands
```

## Collection protocol

Location collections support standard Python protocols:

```python theme={"system"}
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:

```python theme={"system"}
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:

```python theme={"system"}
# 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:

```python theme={"system"}
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:

```bash theme={"system"}
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:

<AccordionGroup>
  <Accordion title="SedonaError: Can't infer Parquet schema for zero objects" icon="circle-question">
    **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`.
  </Accordion>

  <Accordion title="NameError: name 'wkls' is not defined" icon="circle-question">
    **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.
  </Accordion>
</AccordionGroup>

## How it works

For a full explanation, see [How it works](https://github.com/wherobots/wkls/tree/main?tab=readme-ov-file#how-it-works) in the [wkls GitHub repository](https://github.com/wherobots/wkls).

## How to contribute

Contributions are welcome. See [Contributing](https://github.com/wherobots/wkls?tab=readme-ov-file#contributing) in the wkls GitHub repository.