Skip to content

Note

This page mirrors the repository README.

Thereabouts

Thereabouts adds geographic context to a place reference without a network call or an API key. Give it a coordinate, an H3 cell, a town name, a postal code, an airport code, a UN/LOCODE, a phone number, an IP address or a vehicle plate. It returns the country, subdivision, city and timezone it belongs to, with an explicit status when there is no answer or several. Queries run offline against data you install once. One Rust core serves the Python and Node libraries, the command line and an MCP server, and the same data is published as an open Parquet dataset.

What you can look up

You have Call Data pack
latitude and longitude reverse core
an H3 cell (resolution 0 to 8) h3 / from_h3 / fromH3 core
a town or city name geocode core
a postal code and its country postal postal
an airport code (IATA, ICAO, GPS, local) airport airports
a UN/LOCODE locode locode
an international phone number phone phone
an IPv4 or IPv6 address ip ip
a vehicle registration plate plate plates

Geocoding finds towns and cities, not street addresses. A phone result is a calling-code prefix, an IP result is the provider's location for the range, and a plate result is format evidence, not a vehicle register.

Install

pip install thereabouts            # Python 3.11+, installs the thereabouts command
pip install "thereabouts[mcp]"     # adds the MCP server
npm install thereabouts            # Node 22 or 24, ESM, WebAssembly, no compiler needed

The npm package also provides npx thereabouts, the same command line. Nothing is bundled: you install data explicitly, and no lookup ever downloads anything.

Install data

thereabouts data install core postal airports
thereabouts data list

Packs download from this repository's GitHub Releases, are checked by SHA-256 and are activated atomically. While the repository is private, set THEREABOUTS_RELEASE_TOKEN (or GITHUB_TOKEN) to a token with read access to it. --from DIR_OR_URL installs from a local directory or another URL, and --data-dir or THEREABOUTS_DATA chooses the store. See data installation.

Pack Answers Download Unpacked
core reverse, H3 cells, city names, timezones 460 MB 2.9 GB
postal postal codes 31 MB 42 MB
ip IPv4 and IPv6 addresses 34 MB 42 MB
airports airport codes 3.3 MB 6.4 MB
locode UN/LOCODE 3.3 MB 6.5 MB
phone phone calling-code prefixes 1.2 MB 4.4 MB
plates vehicle plate formats 1.2 MB 3.8 MB

Sizes are from the world build of release 2026.10. Forward packs work alone; with core installed they also return the canonical city and timezone.

Quick start

Python:

from thereabouts import Geocoder

with Geocoder() as geo:
    r = geo.reverse(lat=48.8566, lon=2.3522)
    print(r.status, r.city.name, r.country.code, r.timezone)
    print(geo.geocode("Paris", country="FR").to_dict())
    print(geo.postal("75001", country="FR").to_dict())
    print(geo.airport("CDG").to_dict())

Node:

import { Geocoder } from "thereabouts";

const geo = await Geocoder.open();
try {
  const r = await geo.reverse({ lat: 48.8566, lon: 2.3522 });
  console.log(r.status, r.city?.name, r.country?.code, r.timezone);
  console.log(await geo.geocode("Paris", { country: "FR" }));
  console.log(await geo.airport("CDG"));
} finally {
  await geo.close();
}

Command line:

thereabouts reverse --lat 48.8566 --lon 2.3522 --json
thereabouts geocode "Paris" --country FR
thereabouts airport CDG
thereabouts reverse points.csv --csv      # batch: input columns kept, results appended

Results use the same fields in every client. Check status first: matched, ambiguous (ranked candidates), not_found, invalid_input or unsupported_granularity. Add evidence to see why an answer or a miss happened. Guides: Python, Node, command line.

MCP server and agent skill

thereabouts mcp runs a read-only MCP server on stdio with one tool per lookup plus describe for the dataset tables; setup for Claude Desktop, Claude Code and other clients is in the MCP guide. The skill in skills/thereabouts teaches an agent to pick the right tool, read statuses correctly and answer questions about many places with DuckDB over the dataset.

Dataset

The same data is available as versioned Parquet tables (places, cells, names, postal codes, airports, IP ranges and more) with provenance and licence notices, restored by thereabouts data install dataset or read straight from the release. See the dataset guide and the data dictionary.

Licences

Code is MIT, see LICENSE. Data carries its own notices: the dataset is ODbL 1.0 with per-source attribution, and the plates data derives from CC BY-SA sources. Details are in docs/licenses.md.

Status

Clients 0.1.0 are on PyPI and npm. Dataset and packs release 2026.10 is published on this repository's GitHub Releases, where thereabouts data install finds it. Releases are monthly. To build from source, see the contributing guide.

Roadmap

Native coordinate frames (UTM/MGRS, geohash, plus codes, ECEF, NMEA and WKT) are developed on a branch for a later release.

More