Skip to main content

nyc311calendar

Python library for asynchronously fetching data for NYC school closures, trash collection holidays, and alternate side parking suspensions.


GitHub

Uses the NYC 311 Public API. Built to drive the Home Assistant NYC 311 Public Services Calendar add-in.

Warning

This is an alpha release. Expect breaking changes.

I take no responsibility for parking tickets, overflowing trash cans, kids stranded at bus stops or missing exams, etc. 🤷🏼‍♂️

Use at your own risk.

Usage

First, install via pip

pip install nyc311calendar

Then, get an API key

An NYC API Portal developer account is required to use this library.

  1. Sign up at https://api-portal.nyc.gov/signup/.
  2. Log in, then subscribe to the "NYC 311 Public Developers" product at https://api-portal.nyc.gov/products?api=nyc-311-public-api. This subscription unlocks the calendar product.
  3. Get your API key at https://api-portal.nyc.gov/developer. Either key (primary/secondary) will work.

Finally, get data

# Import modules
from nyc311calendar import CalendarType, NYC311API

# Instantiate class
calendar = NYC311API(session, API_KEY)

# Fetch calendar
resp = await calendar.get_calendar()

There's more to this. You'll need to provide an aiohttp ClientSession object. See the examples folder for guidance.

Constants

This library converts strings in the source API to constants wherever sensible and uses these constants everywhere (even as dictionary keys). That is, "status": "CLOSED" in the source API is represented as 'status_id': <Status.CLOSED: 7>} in this library, where Status is an enum in the CivCalNYC class.

Constants are defined for:

  1. Public services in services.ServiceType.
  2. Service statuses in services.StandardizedStatusTypes. The source API is a mess of poorly named statuses. The StandardizedStatusTypes attempts to make sense of the underlying statuses.
  3. Calendar types in CalendarType. See below for more info on calendar types.

Calendar Day Entries

Data for each calendar day is returned in a CalendarDayEntry dataclass.

Calendar Types

nyc311calendar can return data in several formats, each defined in the CalendarType enum:

Quarter Ahead

The Quarter Ahead calendar type returns all statuses for all services for 90 days starting on the day before the API request was made. The response dict has two sub-dicts keyed by calendar date and service. This is essentially a constant-ized dump from the source API. The example below is truncated to save space, showing two of 90 days.

async with aiohttp.ClientSession() as session:
    calendar = NYC311API(session, API_KEY)
    resp = await calendar.get_calendar(
        calendars=[CalendarType.QUARTER_AHEAD], scrub=True
    )
{
    <CalendarType.QUARTER_AHEAD: 1>: {
        <GroupBy.DATE: "date">: {
            datetime.date(2021, 12, 31): {
                <ServiceType.PARKING: "Alternate Side Parking">: CalendarDayEntry(...),
                <ServiceType.SCHOOL: "Schools">: CalendarDayEntry(...),
                <ServiceType.SANITATION: "Collections">: CalendarDayEntry(...)
            },
            datetime.date(2022, 1, 1): {
                <ServiceType.PARKING: "Alternate Side Parking">: CalendarDayEntry(...),
                <ServiceType.SCHOOL: "Schools">: CalendarDayEntry(...),
                <ServiceType.SANITATION: "Collections">: CalendarDayEntry(...)
            }
        },
        <GroupBy.SERVICE: "service">: {
            <ServiceType.PARKING: "Alternate Side Parking">: {
                datetime.date(2021, 12, 31): CalendarDayEntry(...),
                datetime.date(2022, 1, 1): CalendarDayEntry(...)
            },
            <ServiceType.SCHOOL: "Schools">: {
                datetime.date(2021, 12, 31): CalendarDayEntry(...),
                datetime.date(2022, 1, 1): CalendarDayEntry(...)
            },
            <ServiceType.SANITATION: "Collections">: {
                datetime.date(2021, 12, 31): CalendarDayEntry(...),
                datetime.date(2022, 1, 1): CalendarDayEntry(...)
            }
        }
    }
}

Week Ahead

The Week Ahead calendar type returns all statuses for all services for 8 days starting on the day before the API request was made. The response dict is keyed by number of days relative to today. This is useful for showing a calendar of the week ahead (and yesterday, just in case you forgot to move your car). The example below is truncated to save space, showing three of 90 days.

async with aiohttp.ClientSession() as session:
    calendar = NYC311API(session, API_KEY)
    resp = await calendar.get_calendar(
        calendars=[CalendarType.WEEK_AHEAD], scrub=True
    )
{
    <CalendarTypes.WEEK_AHEAD: 2>: {
        -1: {
            'date': datetime.date(2021, 12, 23),
            'services': {
                <ServiceType.PARKING: "Alternate Side Parking">: CalendarDayEntry(...),
                <ServiceType.SCHOOL: "Schools">: CalendarDayEntry(...),
                <ServiceType.SANITATION: "Collections">: CalendarDayEntry(...)
        },
        0: {
            'date': datetime.date(2021, 12, 24),
            'services': {
                <ServiceType.PARKING: "Alternate Side Parking">: CalendarDayEntry(...),
                <ServiceType.SCHOOL: "Schools">: CalendarDayEntry(...),
                <ServiceType.SANITATION: "Collections">: CalendarDayEntry(...)
        },
        1: {
            'date': datetime.date(2021, 12, 25),
            'services': {
                <ServiceType.PARKING: "Alternate Side Parking">: CalendarDayEntry(...),
                <ServiceType.SCHOOL: "Schools">: CalendarDayEntry(...),
                <ServiceType.SANITATION: "Collections">: CalendarDayEntry(...)
        }
    }
}

Next Exceptions

The Next Exceptions calendar type returns the next date on which there is a service exception for either of the three covered services. The response dict is keyed by service type. This is useful when you're not interested in normal operations and only want to know, say, when the next school closure is. The example below shows the full response.

Note that exceptions include things like holidays, snow days, half days, and winter break.

async with aiohttp.ClientSession() as session:
    calendar = NYC311API(session, API_KEY)
    resp = await calendar.get_calendar(
        calendars=[CalendarType.NEXT_EXCEPTIONS], scrub=True
    )
{
    <CalendarTypes.NEXT_EXCEPTIONS: 3>: {
        <ServiceType.PARKING: "Alternate Side Parking">: CalendarDayEntry(...),
        <ServiceType.SCHOOL: "Schools">: CalendarDayEntry(...),
        <ServiceType.SANITATION: "Collections">: CalendarDayEntry(...)
    }
}

Metadata

Release files for nyc311calendar 0.4.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for nyc311calendar 0.4.1
File Size Uploaded Provenance Actions
nyc311calendar-0.4.1.tar.gz 13.4 kB Without provenance Details for nyc311calendar-0.4.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for nyc311calendar 0.4.1
File Interpreter ABI Platform Actions
nyc311calendar-0.4.1-py3-none-any.whl Python 3 none any Details for nyc311calendar-0.4.1-py3-none-any.whl

Total release size: 24.9 kB

Release files / nyc311calendar-0.4.1.tar.gz

Download URL nyc311calendar-0.4.1.tar.gz
Size 13.4 kB
Tags Source
SHA-256 checksum
How to use checksums
a9cfa2ca893124f314e7449f87ee72e0215ad93691d5701d5cf7469d2405250b
BLAKE2b-256 checksum
How to use checksums
5db2cd884aa56e77e08df3897409b2a44017f763c49ff4fb27c1c38f92f69bb5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/4.0.2 CPython/3.9.16

Release files / nyc311calendar-0.4.1-py3-none-any.whl

Download URL nyc311calendar-0.4.1-py3-none-any.whl
Size 11.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ca8173e6721297a0bd340241c4cf1fbaf67766325d9127841e5a1a41446902a2
BLAKE2b-256 checksum
How to use checksums
a98a27eb5012aca3faee41fad112dea6d3ab88d680da959316c3dd3315705de0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/4.0.2 CPython/3.9.16

Security for nyc311calendar 0.4.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page