# 🌐 `wkls`: Well-Known Locations
[](https://opensource.org/licenses/Apache-2.0)
`wkls` makes it easy to explore global administrative boundaries — from countries to cities — using clean, chainable Python syntax. It reads directly from [Overture Maps Foundation](https://overturemaps.org/) GeoParquet data (version 2025-05-21.0) hosted on the AWS Open Data Registry.
You can instantly get geometries in formats like WKT, WKB, HexWKB, GeoJSON, and SVG:
```python
import wkls
print(wkls.us.ca.sanfrancisco.wkt()) # => "MULTIPOLYGON (((-122.9915659 37.7672733...)))"
print(wkls.overture_version()) # => "2025-05-21.0"
```
## Installation
```bash
pip install wkls
```
> Requires DuckDB with the spatial extension (loaded automatically). The package is self-contained and lightweight.
## Quick Start
```python
import wkls
# Get country geometry
usa_wkt = wkls.us.wkt()
print(f"USA geometry: {usa_wkt[:50]}...")
# Get state/region geometry
california_geojson = wkls.us.ca.geojson()
# Get city geometry
sf_svg = wkls.us.ca.sanfrancisco.svg()
# Check dataset version
print(f"Using Overture Maps data: {wkls.overture_version()}")
# Explore available data
print(f"Countries: {len(wkls.countries())}")
print(f"US regions: {len(wkls.us.regions())}")
print(f"CA counties: {len(wkls.us.ca.counties())}")
```
## Usage
### Accessing geometry
WKLS supports **up to 3 chained attributes**:
1. **Country** (required) – must be a 2-letter ISO 3166-1 alpha-2 code (e.g. `us`, `de`, `fr`)
2. **Region** (optional) – must be a valid region ISO code suffix (e.g. `ca` for `US-CA`, `ny` for `US-NY`)
3. **Place** (optional) – a **name** match against subtypes: `county`, `locality`, or `neighborhood`
Examples:
```python
wkls.us.wkt() # country: United States
wkls.us.ca.wkt() # region: California
wkls.us.ca.sanfrancisco.wkt() # city/county: San Francisco
wkls["us"]["ca"]["sanfrancisco"].wkt() # dictionary-style access
```
Supported formats:
- `.wkt()` – Well-Known Text
- `.wkb()` – Raw binary WKB
- `.hexwkb()` – Hex-encoded WKB
- `.geojson()` – GeoJSON string
- `.svg()` – SVG path string
### What does `wkls.us.ca.sanfrancisco` return?
Chained expressions like wkls.us.ca.sanfrancisco return a Wkl object. Internally, this holds a Pandas DataFrame containing one or more rows that match the given chain.
```python
id country region subtype name division_id
0 085718963fffff... US US-CA county San Francisco 085718963fffff...
```
In most cases, it resolves to a single administrative boundary. But if there are name collisions (e.g., both a county and a locality called “San Francisco”), multiple rows may be returned.
By default, geometry methods like `.wkt()` will use the first matching row.
### Helper methods
The following methods return Pandas DataFrames for easy exploration:
| Method | Description |
|----------------------------|------------------------------------|
| `wkls.countries()` | List all countries |
| `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 |
### Dataset information
You can check which version of the Overture Maps dataset is being used:
```python
print(wkls.overture_version()) # => "2025-05-21.0"
```
> **Note**: The `overture_version()` method is only available at the root level, not on chained objects like `wkls.us.overture_version()`.
## How It Works
WKLS works in two stages:
### 1. In-memory GERS ID resolution
Your chained attributes — up to 3 levels — are parsed in this order:
1. `country` → matched by ISO 2-letter code (e.g. `"us"`)
2. `region` → matched using region ISO code suffix (e.g. `"ca"` → `"US-CA"`)
3. `place` → fuzzy-matched against names in subtypes: `county`, `locality`, or `neighborhood`
This resolves to a Pandas DataFrame containing one or more rows from the in-memory wkls metadata table. At this stage, no geometry is loaded yet — only metadata (like id, name, region, subtype, etc.).
### 2. 📡 Geometry lookup using DuckDB
The geometry lookup is triggered only when you call one of the geometry methods:
- `.wkt()`
- `.wkb()`
- `.hexwkb()`
- `.geojson()`
- `.svg()`
At that point, WKLS uses the previously resolved **GERS ID** to query the Overture **division_area** GeoParquet directly from S3.
The current Overture Maps dataset version can be checked with `wkls.overture_version()`.
## Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on how to get started, development setup, and submission guidelines.
## License
This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENCE) file for details.
## Acknowledgments
- [Overture Maps Foundation](https://overturemaps.org/) for providing high-quality, open geospatial data
- [DuckDB](https://duckdb.org/) for fast analytical queries with spatial support
- [AWS Open Data Registry](https://registry.opendata.aws/) for hosting the dataset
Raw data
{
"_id": null,
"home_page": null,
"name": "wkls",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "gis, geography, boundaries, geospatial, overture-maps, wkt, geometry, admin boundaries, geojson, spatial",
"author": null,
"author_email": "Matthew Powers <mpowers@wherobots.com>, Pranav Toggi <pranav@wherobots.com>, Maxime Petazzoni <max@wherobots.com>",
"download_url": "https://files.pythonhosted.org/packages/68/f3/33a1254f769fc0fb3c4bab69cf502e7d0e0f2a382a61193969a702f7776f/wkls-0.2.0.tar.gz",
"platform": null,
"description": "# \ud83c\udf10 `wkls`: Well-Known Locations\n\n[](https://opensource.org/licenses/Apache-2.0)\n\n`wkls` makes it easy to explore global administrative boundaries \u2014 from countries to cities \u2014 using clean, chainable Python syntax. It reads directly from [Overture Maps Foundation](https://overturemaps.org/) GeoParquet data (version 2025-05-21.0) hosted on the AWS Open Data Registry.\n\nYou can instantly get geometries in formats like WKT, WKB, HexWKB, GeoJSON, and SVG:\n\n```python\nimport wkls\nprint(wkls.us.ca.sanfrancisco.wkt()) # => \"MULTIPOLYGON (((-122.9915659 37.7672733...)))\"\nprint(wkls.overture_version()) # => \"2025-05-21.0\"\n```\n\n## Installation\n\n```bash\npip install wkls\n```\n\n> Requires DuckDB with the spatial extension (loaded automatically). The package is self-contained and lightweight.\n\n## Quick Start\n\n```python\nimport wkls\n\n# Get country geometry\nusa_wkt = wkls.us.wkt()\nprint(f\"USA geometry: {usa_wkt[:50]}...\")\n\n# Get state/region geometry \ncalifornia_geojson = wkls.us.ca.geojson()\n\n# Get city geometry\nsf_svg = wkls.us.ca.sanfrancisco.svg()\n\n# Check dataset version\nprint(f\"Using Overture Maps data: {wkls.overture_version()}\")\n\n# Explore available data\nprint(f\"Countries: {len(wkls.countries())}\")\nprint(f\"US regions: {len(wkls.us.regions())}\")\nprint(f\"CA counties: {len(wkls.us.ca.counties())}\")\n```\n\n## Usage\n\n### Accessing geometry\n\nWKLS supports **up to 3 chained attributes**:\n1. **Country** (required) \u2013 must be a 2-letter ISO 3166-1 alpha-2 code (e.g. `us`, `de`, `fr`)\n2. **Region** (optional) \u2013 must be a valid region ISO code suffix (e.g. `ca` for `US-CA`, `ny` for `US-NY`)\n3. **Place** (optional) \u2013 a **name** match against subtypes: `county`, `locality`, or `neighborhood`\n\nExamples:\n```python\nwkls.us.wkt() # country: United States\nwkls.us.ca.wkt() # region: California\nwkls.us.ca.sanfrancisco.wkt() # city/county: San Francisco\nwkls[\"us\"][\"ca\"][\"sanfrancisco\"].wkt() # dictionary-style access\n```\n\nSupported formats:\n- `.wkt()` \u2013 Well-Known Text\n- `.wkb()` \u2013 Raw binary WKB\n- `.hexwkb()` \u2013 Hex-encoded WKB\n- `.geojson()` \u2013 GeoJSON string\n- `.svg()` \u2013 SVG path string\n\n### What does `wkls.us.ca.sanfrancisco` return?\n\nChained expressions like wkls.us.ca.sanfrancisco return a Wkl object. Internally, this holds a Pandas DataFrame containing one or more rows that match the given chain.\n\n```python\n id country region subtype name division_id\n0 085718963fffff... US US-CA county San Francisco 085718963fffff...\n```\n\nIn most cases, it resolves to a single administrative boundary. But if there are name collisions (e.g., both a county and a locality called \u201cSan Francisco\u201d), multiple rows may be returned.\n\nBy default, geometry methods like `.wkt()` will use the first matching row.\n\n### Helper methods\n\nThe following methods return Pandas DataFrames for easy exploration:\n\n| Method | Description |\n|----------------------------|------------------------------------|\n| `wkls.countries()` | List all countries |\n| `wkls.us.regions()` | List regions in the US |\n| `wkls.us.ca.counties()` | List counties in California |\n| `wkls.us.ca.cities()` | List cities in California |\n| `wkls.subtypes()` | Show all distinct division subtypes |\n\n### Dataset information\n\nYou can check which version of the Overture Maps dataset is being used:\n\n```python\nprint(wkls.overture_version()) # => \"2025-05-21.0\"\n```\n\n> **Note**: The `overture_version()` method is only available at the root level, not on chained objects like `wkls.us.overture_version()`.\n\n## How It Works\n\nWKLS works in two stages:\n\n### 1. In-memory GERS ID resolution\n\nYour chained attributes \u2014 up to 3 levels \u2014 are parsed in this order:\n\n1. `country` \u2192 matched by ISO 2-letter code (e.g. `\"us\"`)\n2. `region` \u2192 matched using region ISO code suffix (e.g. `\"ca\"` \u2192 `\"US-CA\"`)\n3. `place` \u2192 fuzzy-matched against names in subtypes: `county`, `locality`, or `neighborhood`\n\nThis resolves to a Pandas DataFrame containing one or more rows from the in-memory wkls metadata table. At this stage, no geometry is loaded yet \u2014 only metadata (like id, name, region, subtype, etc.).\n\n### 2. \ud83d\udce1 Geometry lookup using DuckDB\n\nThe geometry lookup is triggered only when you call one of the geometry methods:\n- `.wkt()`\n- `.wkb()`\n- `.hexwkb()`\n- `.geojson()`\n- `.svg()`\n\nAt that point, WKLS uses the previously resolved **GERS ID** to query the Overture **division_area** GeoParquet directly from S3.\n\nThe current Overture Maps dataset version can be checked with `wkls.overture_version()`.\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on how to get started, development setup, and submission guidelines.\n\n## License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENCE) file for details.\n\n## Acknowledgments\n\n- [Overture Maps Foundation](https://overturemaps.org/) for providing high-quality, open geospatial data\n- [DuckDB](https://duckdb.org/) for fast analytical queries with spatial support\n- [AWS Open Data Registry](https://registry.opendata.aws/) for hosting the dataset\n",
"bugtrack_url": null,
"license": null,
"summary": "Easy access to global administrative boundaries and geometries via Overture Maps data",
"version": "0.2.0",
"project_urls": {
"Changelog": "https://github.com/wherobots/wkls/releases",
"Documentation": "https://github.com/wherobots/wkls#readme",
"Homepage": "https://github.com/wherobots/wkls",
"Issues": "https://github.com/wherobots/wkls/issues",
"Repository": "https://github.com/wherobots/wkls.git"
},
"split_keywords": [
"gis",
" geography",
" boundaries",
" geospatial",
" overture-maps",
" wkt",
" geometry",
" admin boundaries",
" geojson",
" spatial"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "88f2c66826d7f4280a381ad6d4ea5b56e3b6089e56847a428268bd4bacea34e3",
"md5": "a6fe5e139618bd54c0e0cd2e495cbeed",
"sha256": "56a43525c5261ea9423e9fe8897dff5fee5989704092b7df8c8801dbe21414de"
},
"downloads": -1,
"filename": "wkls-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a6fe5e139618bd54c0e0cd2e495cbeed",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 10804,
"upload_time": "2025-08-26T18:11:06",
"upload_time_iso_8601": "2025-08-26T18:11:06.760426Z",
"url": "https://files.pythonhosted.org/packages/88/f2/c66826d7f4280a381ad6d4ea5b56e3b6089e56847a428268bd4bacea34e3/wkls-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "68f333a1254f769fc0fb3c4bab69cf502e7d0e0f2a382a61193969a702f7776f",
"md5": "e3e946ef32579d94d6d3fd206c064301",
"sha256": "8da661d922908125c156c019472df9f704fde9ed0b24fd62f50a2275090a51bc"
},
"downloads": -1,
"filename": "wkls-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "e3e946ef32579d94d6d3fd206c064301",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 14469,
"upload_time": "2025-08-26T18:11:08",
"upload_time_iso_8601": "2025-08-26T18:11:08.180368Z",
"url": "https://files.pythonhosted.org/packages/68/f3/33a1254f769fc0fb3c4bab69cf502e7d0e0f2a382a61193969a702f7776f/wkls-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-26 18:11:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "wherobots",
"github_project": "wkls",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "wkls"
}
JSON
