Python library for asynchronously fetching data for NYC school closures, trash collection holidays, and alternate side parking suspensions.
Uses the NYC 311 Public API. Built to drive the Home Assistant NYC 311 Public Services Calendar add-in.
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.
pip install nyc311calendarAn NYC API Portal developer account is required to use this library.
- Sign up at https://api-portal.nyc.gov/signup/.
- 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.
- Get your API key at https://api-portal.nyc.gov/developer. Either key (primary/secondary) will work.
# 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.
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:
- Public services in
services.ServiceType. - 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. - Calendar types in
CalendarType. See below for more info on calendar types.
Data for each calendar day is returned in a CalendarDayEntry dataclass.
nyc311calendar can return data in several formats, each defined in the CalendarType enum:
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(...)
}
}
}
}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(...)
}
}
}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(...)
}
}