nyc-geo-toolkit

Reusable NYC geography resources, normalization helpers, and boundary loaders for Python tools.

Authored by Blaise Albis-Burdige.

Why this exists

Every NYC data project needs borough boundaries, ZIP lookups, and district normalization. nyc-geo-toolkit ships canonical boundary GeoJSON and a stable Python API so downstream tools don't duplicate that work. Install the base package for zero-dependency boundary loading, or add optional extras for pandas, geopandas, and basemap helpers.

What this package provides

• Packaged boundary layers for boroughs, community districts, council districts, NTAs, ZCTAs, and census tracts -- no runtime network dependency
• Normalization helpers that turn messy user input ("bk", "01 Brooklyn", "zip code") into canonical values
• Geodesy helpers for great-circle distance, walk-radius circles, and bounding boxes -- dependency-free
• Typed models (BoundaryCollection, BoundaryFeature) for safe, inspectable boundary data
• GeoJSON, DataFrame, and GeoDataFrame conversion with optional pandas and geopandas extras
• Basemap and spatial helpers for Web Mercator reprojection, OSM tile overlays, and bbox clipping

Ecosystem

nyc-geo-toolkit is the shared geography core for a family of NYC data packages:

All three depend on the stable nyc_geo_toolkit namespace for boundary data, normalization, and spatial primitives.

Install

pip install nyc-geo-toolkit              # zero-dependency base
pip install "nyc-geo-toolkit[dataframes]" # + pandas helpers
pip install "nyc-geo-toolkit[spatial]"    # + geopandas, shapely, contextily
pip install "nyc-geo-toolkit[all]"        # everything

Quick start

Load and inspect boundaries

from nyc_geo_toolkit import list_boundary_layers, load_nyc_boundaries

print(list_boundary_layers())
# ('borough', 'community_district', 'council_district', ...)

queens = load_nyc_boundaries("borough", values="Queens")
print(queens.features[0].geography_value)  # "QUEENS"

Normalize messy input

from nyc_geo_toolkit import normalize_borough_name, normalize_boundary_value

normalize_borough_name("bk")  # "BROOKLYN"
normalize_boundary_value("community_district", "01 Brooklyn")  # "BROOKLYN 01"

Plot a boundary layer

from nyc_geo_toolkit import (
    load_nyc_boundaries_geodataframe,
    to_web_mercator,
    add_osm_basemap,
)

gdf = to_web_mercator(load_nyc_boundaries_geodataframe("borough"))
ax = gdf.plot(figsize=(8, 8), edgecolor="white", alpha=0.7, column="geography_value")
add_osm_basemap(ax)

Use geodesy helpers

from nyc_geo_toolkit import (
    haversine_distance_meters,
    walk_radius_meters,
    build_circle_polygon,
)

walk_radius_meters(10)  # 800.0 meters
haversine_distance_meters(40.7580, -73.9855, 40.7128, -74.006)  # ~5.2 km
polygon = build_circle_polygon(40.7128, -74.006, 800)  # 24-sided circle

API overview

Full reference: API docs

Examples

The repo ships self-contained examples under examples/:

• examples/about-the-data/ -- kitchen-sink visualization of every boundary layer and spatial helper (generates the cover figure above)
• examples/boundary-quickstart/ -- basic boundary loading and GeoJSON export
• examples/normalization-demo/ -- input normalization showcase
• examples/boundary-explorer-tearsheet/ -- interop showcase with factor-factory and jellycell: loads community districts, fits a synthetic DiD, and renders a jellycell findings tearsheet (the canonical pattern downstream packages can copy)

Documentation

Home | Getting Started | Examples | API Reference | Architecture

License

MIT.