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

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](https://github.com/wherobots/wkls).

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

<Tip>
  Don't believe us? Try it yourself! <Icon icon="face-grin-squint" />

  Run `print(str(len(wkls.us.wkt())))` to see the actual character count.
</Tip>

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

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

| Method                  | Description                                                                                 |
| ----------------------- | ------------------------------------------------------------------------------------------- |
| `wkls.countries()`      | List all countries                                                                          |
| `wkls.dependencies()`   | List all [dependencies](https://docs.overturemaps.org/schema/reference/divisions/division/) |
| `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:

```python theme={"system"}
import wkls
wkls.fk.cities()
```

## Installation

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

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

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

## How it works

For a full explanation of how `wkls` works, 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.