nyc311 0.2.1

Python toolkit for reproducible NYC 311 complaint analysis via a typed SDK and CLI.

nyc311

Python toolkit for reproducible NYC 311 complaint analysis via a typed SDK and CLI.

Status

nyc311 is now on the stable 0.2 line with a tested toolkit for loading, analyzing, and exporting NYC 311 complaint data.

The first public stable release shipped in 0.2.0, and the 0.2.x line focuses on packaging polish, developer ergonomics, and incremental workflow improvements on top of the current analysis surface.

What ships in the stable 0.2 line

• load filtered NYC 311-style records from local CSV extracts or the live Socrata API
• stage reproducible local CSV snapshots from live fetches
• derive deterministic first-pass topic labels for supported complaint types
• aggregate complaint topics by borough or community district
• measure topic-rule coverage and summarize resolution gaps
• score anomalies over aggregated topic summaries
• export CSV tables, boundary-backed GeoJSON, and markdown report cards
• run the workflow through both a thin CLI and a composable functional SDK

Install

Choose the dependency footprint that matches your workflow:

pip install nyc311

For the full turnkey experience:

pip install "nyc311[all]"

For pandas-backed conversion helpers:

pip install "nyc311[dataframes]"

For plotting and exploratory analysis without the geospatial stack:

pip install "nyc311[science]"

Why this exists

NYC 311 data is one of the richest public records of neighborhood quality-of-life complaints in the country, but much of the useful signal is locked inside short text fields such as complaint descriptors.

This project aims to turn those records into reusable outputs for civic analysis, journalism, and research while staying honest about what is truly implemented today.

Core workflow

The stable 0.2 line focuses on a deterministic, testable workflow:

1. load records from a local CSV extract or a filtered Socrata slice
2. filter by date, geography, and complaint type
3. assign a first-pass topic label using explicit keyword rules
4. aggregate counts by borough or community district
5. export a CSV summary table or boundary-backed GeoJSON artifact

Supported topic extraction

The current rules-based topic extractor is implemented only for:

• Blocked Driveway
• Illegal Parking
• Noise - Residential
• Rodent

This is intentionally described as first-pass topic extraction, not clustering or advanced NLP.

Quick links

Docs: Home, Getting Started, CLI Reference, SDK Guide, Examples, Architecture, Contributing

Example

from datetime import date
from pathlib import Path

from nyc311 import analysis, export, models, pipeline

records = pipeline.fetch_service_requests(
    filters=models.ServiceRequestFilter(
        start_date=date(2025, 1, 1),
        end_date=date(2025, 1, 31),
        geography=models.GeographyFilter("borough", models.BOROUGH_BROOKLYN),
        complaint_types=("Noise - Residential",),
    ),
    socrata_config=models.SocrataConfig(page_size=250, max_pages=1),
)

export.export_service_requests_csv(
    records,
    models.ExportTarget("csv", Path("brooklyn-noise-snapshot.csv")),
)

assignments = analysis.extract_topics(records, models.TopicQuery("Noise - Residential"))
summary = analysis.aggregate_by_geography(assignments, geography="community_district")
export.export_topic_table(
    summary,
    models.ExportTarget("csv", Path("brooklyn-noise-topics.csv")),
)

CLI equivalent:

nyc311 fetch \
  --output brooklyn-noise-snapshot.csv \
  --complaint-type "Noise - Residential" \
  --geography borough \
  --geography-value BROOKLYN \
  --start-date 2025-01-01 \
  --end-date 2025-01-31 \
  --page-size 250 \
  --max-pages 1

nyc311 topics \
  --source brooklyn-noise-snapshot.csv \
  --complaint-type "Noise - Residential" \
  --geography community_district \
  --output brooklyn-noise-topics.csv

Live-data snapshot workflow:

nyc311 fetch \
  --output brooklyn-rodent-snapshot.csv \
  --complaint-type "Rodent" \
  --geography borough \
  --geography-value BROOKLYN \
  --start-date 2025-01-01 \
  --end-date 2025-01-31 \
  --page-size 500 \
  --max-pages 1

Data assumptions

load_service_requests() currently supports:

• local CSV files
• live Socrata loading via SocrataConfig

CSV inputs use these columns:

• unique_key
• created_date
• complaint_type
• descriptor
• borough
• community_district or community_board

resolution_description is optional and loaded when present. It is currently used by the resolution-gap and report-card helpers, while topic extraction remains descriptor-driven.

Public package surface

The current public package surface is organized around explicit namespaces:

• nyc311.models for dataclasses, constants, and configs
• nyc311.io for CSV and Socrata loading
• nyc311.analysis for topic extraction, coverage, gaps, and anomalies
• nyc311.geographies for packaged boundary layers and geometry helpers
• nyc311.samples for packaged sample records and sample-aligned boundaries
• nyc311.export for CSV, GeoJSON, and report exports
• nyc311.pipeline for one-call workflow helpers
• nyc311.dataframes for optional pandas conversions
• nyc311.spatial for optional geopandas helpers
• nyc311.plotting for optional plotting helpers
• nyc311.presets for reusable filter and Socrata config builders
• nyc311.cli with the topics and fetch subcommands

Documentation

The hosted docs site is the canonical reference: nyc311.readthedocs.io.

If you are browsing in GitHub, the source docs live in docs/, including index.md, getting-started.md, cli.md, sdk.md, examples.md, api.md, architecture.md, and contributing.md.

Runnable examples live in examples/ as self-contained consumer projects.

For local preview:

make docs
make docs-build

Development

uv sync
uv sync --all-groups --all-extras
uv run --all-extras pytest -m "not integration"
uv run ruff check .
uv run ruff format --check .
uv run mypy
uv run mkdocs serve
uv run mkdocs build --strict
uv run python scripts/audit_public_api.py
uv run pytest -m "fetch and not integration"

License

MIT.