pygeokit

Offline geo features from latitude / longitude for tabular ML: country, nearest and main city, capitals, city types and sizes, distances, density of neighbours, ring / sector / multi-core city structure, grids, and a few urban-economics formulas (Reilly, Huff, Zipf). The city data is bundled, so nothing is downloaded at run time.

pip install pygeokit

Depends only on numpy, pandas, scipy, scikit-learn. h3 is optional (hex_cell).

Quick start

import pygeokit as gk

gk.help()                                   # cheat sheet (in Russian)

X, cat = gk.make_X(df, "lat", "lon")        # ready matrix + categorical columns
model = CatBoostRegressor(cat_features=cat).fit(X, y)

feats = gk.get_features(df, lat_col="lat", lon_col="lon")   # reference features only

gk.get_country(55.75, 37.62)                # 'RU'
gk.get_capital("RU")                        # {'name': 'Moscow', 'lat': ..., ...}
gk.get_main_city(lat, lon)                  # biggest city within 60 km
gk.get_city_type(lat, lon)                  # capital / region_center / ... + size class
gk.haversine(lat1, lon1, lat2, lon2)        # km

What is inside

city_type comes from the GeoNames feature code: PPLC capital, PPLA region center, PPLA2 district center, PPLA3/4/5 local center, PPLX city section, everything else settlement. size_class: tiny < 10k, small < 50k, medium < 100k, big < 250k, large < 1M, million.

get_country returns the country of the nearest city, so points right on a border or far out at sea can get the neighbouring country.

Leak-free neighbour target features

tr_f = gk.oof_neighbor_features(train.lat, train.lon, y)                 # train rows
te_f = gk.neighbor_features(test.lat, test.lon, train.lat, train.lon, values=y)

Building from source

The data files are not stored in the repository. Build them once:

python tools/build_data.py      # downloads GeoNames dumps (~12 MB)
python -m pytest tests          # tests use a tiny fake data set
python -m build

Set PYGEOKIT_DATA_DIR to use your own data directory.

Urban models

get_city_model(lat, lon) matches each point to the nearest activity center of a GHSL urban area (9,293 areas, centers detected from night lights and POI by Pang et al., arXiv:2503.06445) and returns soft scores p_ring, p_sector, p_multi_core (sum to 1), model and models (several types joined with +), plus measured values: number of centers, spread, elongation, distances to the main / nearest center. The scores are a heuristic: more centers -> multi_core, a stretched footprint -> sector. Large agglomerations have many centers and score as multi_core.

Data and license

Code: MIT. City and country data: GeoNames, licensed under CC BY 4.0. Urban centers: Pang, Zhang, Liu, Dong, arXiv:2503.06445, https://github.com/urbansci/city-centers.