Metadata-Version: 2.4
Name: nyc-geo-toolkit
Version: 0.1.7
Summary: Reusable NYC geography resources, normalization helpers, and boundary loaders for Python tools.
Project-URL: Homepage, https://github.com/random-walks/nyc-geo-toolkit
Project-URL: Documentation, https://nyc-geo-toolkit.readthedocs.io/
Project-URL: Portfolio, https://blaiseab.com/
Project-URL: Bug Tracker, https://github.com/random-walks/nyc-geo-toolkit/issues
Project-URL: Discussions, https://github.com/random-walks/nyc-geo-toolkit/discussions
Project-URL: Changelog, https://github.com/random-walks/nyc-geo-toolkit/releases
Author: Blaise Albis-Burdige
License-Expression: MIT
License-File: LICENSE
Keywords: boundaries,civic-tech,geography,geojson,geospatial,nyc,open-data
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: all
Requires-Dist: contextily>=1.6; extra == 'all'
Requires-Dist: geopandas>=1.1; extra == 'all'
Requires-Dist: pandas>=2.3.3; extra == 'all'
Requires-Dist: shapely>=2.1; extra == 'all'
Provides-Extra: dataframes
Requires-Dist: pandas>=2.3.3; extra == 'dataframes'
Provides-Extra: spatial
Requires-Dist: contextily>=1.6; extra == 'spatial'
Requires-Dist: geopandas>=1.1; extra == 'spatial'
Requires-Dist: shapely>=2.1; extra == 'spatial'
Description-Content-Type: text/markdown

# nyc-geo-toolkit

[![Actions Status][actions-badge]][actions-link]
[![Documentation Status][rtd-badge]][rtd-link]
[![PyPI version][pypi-version]][pypi-link]
[![PyPI platforms][pypi-platforms]][pypi-link]

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

Authored by [Blaise Albis-Burdige](https://blaiseab.com/).

## What this package provides

`nyc-geo-toolkit` packages canonical NYC boundary layers and the stable helper
API needed to discover, normalize, load, subset, and convert them.

It is designed to stay small, typed, and reusable across NYC data packages.

The package currently provides:

- packaged boundary layers for boroughs, community districts, council districts,
  NTAs, ZCTAs, and census tracts
- canonical normalization helpers for layer names and boundary values
- typed boundary models for boundary collections and features
- GeoJSON and optional DataFrame / GeoDataFrame helpers
- bbox clipping for typed boundary collections

## Ecosystem

`nyc-geo-toolkit` is the shared geography core for the NYC package ecosystem. It
already powers the geography layer in
[`nyc311`](https://github.com/random-walks/nyc311) and is intended to support
additional consumer packages without forcing each project to duplicate boundary
data or normalization rules.

## Install

Base install:

```bash
pip install nyc-geo-toolkit
```

With pandas helpers:

```bash
pip install "nyc-geo-toolkit[dataframes]"
```

With geopandas + shapely helpers:

```bash
pip install "nyc-geo-toolkit[spatial]"
```

With all optional helpers:

```bash
pip install "nyc-geo-toolkit[all]"
```

## Quick example

```python
from nyc_geo_toolkit import list_boundary_layers, load_nyc_boundaries

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

## Examples

The repo now also ships self-contained consumer examples under `examples/`:

- `examples/boundary-quickstart/`
- `examples/normalization-demo/`

## Public surface

The stable public API is the top-level `nyc_geo_toolkit` namespace.

Discovery and loading:

- `list_boundary_layers()`
- `list_boundary_values()`
- `load_boundaries()`
- `load_nyc_boundaries()`
- `load_nyc_boundaries_geodataframe()`
- `load_nyc_census_tracts()`
- `load_nyc_council_districts()`
- `load_nyc_neighborhood_tabulation_areas()`

Normalization:

- `normalize_borough_name()`
- `normalize_boundary_layer()`
- `normalize_boundary_value()`
- `normalize_boundary_values()`

Conversion and spatial helpers:

- `boundaries_to_geojson()`
- `boundaries_to_dataframe()`
- `clip_boundaries_to_bbox()`

Models and constants:

- `BoundaryCollection`
- `BoundaryFeature`
- `BoundaryLayerSpec`
- `BOROUGH_*`
- `SUPPORTED_BOROUGHS`
- `SUPPORTED_BOUNDARY_GEOGRAPHIES`

Private underscore-prefixed modules are implementation details and may change
without notice.

## Documentation

Docs: [Home](https://nyc-geo-toolkit.readthedocs.io/en/latest/),
[Getting Started](https://nyc-geo-toolkit.readthedocs.io/en/latest/getting-started/),
[API Reference](https://nyc-geo-toolkit.readthedocs.io/en/latest/api/),
[Architecture](https://nyc-geo-toolkit.readthedocs.io/en/latest/architecture/),
[Contributing](https://nyc-geo-toolkit.readthedocs.io/en/latest/contributing/),
[Releasing](https://nyc-geo-toolkit.readthedocs.io/en/latest/releasing/),
[Changelog](https://nyc-geo-toolkit.readthedocs.io/en/latest/changelog/)

## License

MIT.

<!-- prettier-ignore-start -->
[actions-badge]:            https://github.com/random-walks/nyc-geo-toolkit/actions/workflows/ci.yml/badge.svg
[actions-link]:             https://github.com/random-walks/nyc-geo-toolkit/actions
[pypi-link]:                https://pypi.org/project/nyc-geo-toolkit/
[pypi-platforms]:           https://img.shields.io/pypi/pyversions/nyc-geo-toolkit
[pypi-version]:             https://img.shields.io/pypi/v/nyc-geo-toolkit
[rtd-badge]:                https://readthedocs.org/projects/nyc-geo-toolkit/badge/?version=latest
[rtd-link]:                 https://nyc-geo-toolkit.readthedocs.io/en/latest/?badge=latest
<!-- prettier-ignore-end -->
