Access service request data from the Boston 311 API.

Boston's 311 Service API

Python package for interfacing with Boston 311 API.

I recently made a request to have some graffiti removed by the city of Boston and used their 311 service for reporting non-emergency crimes. I found it an interesting service and decided to look closer into it. They provide an free API for the service, so I decided to make this Python package to interface with the API.

Quick start

Installation

Install the boston311 package through PyPI.

pip install boston311

Features

Below are features of this package:

1. Get a collection of all services offered by Boston 311.
2. Get a collection of all service requests with some useful filters.
3. Get information for a specific service request.

All underlying data models were parsed and validated with 'pydantic' so there is increased type safety and helpful hints for your IDE.

Examples

Collection of available services

Use the get_services() function to get a collection of all of the available services offered through the 311 service. The returned object contains a field services which is a list of the services.

In the example below, I make the request, show how many services are available, and print out the third service in the list. Finally, I demonstrate a convenience method I added to make a list of the names of the services.

import boston311

available_services = boston311.get_services()

print(available_services)
#> 22 available services
type(available_services)
#> <class 'boston311.datamodels.Services'>
len(available_services)
#> 22
print(available_services[2])
#> {
#>      'description': 'Graffiti Removal Request',
#>      'group': 'Illegal Graffiti',
#>      'metadata': 'True',
#>      'service_code': '4f38920fe75084437f0001b3',
#>      'service_name': 'Illegal Graffiti',
#>      'type': 'batch',
#>      'version': 1
#> }
print(available_services.list_service_names())
#> ['Residential Trash out Illegally', 'Broken Sidewalk', ..., 'Abandoned Vehicle']

Collection of service requests

It is easy to get a collection of all service requests made in the last 90 days (the default date range). There are also some useful filters for indicating types of service requests, date ranges, and the status of the request.

import boston311

service_requests = boston311.get_service_requests()
print(service_requests)
#> 50 service requests

Information for a known service request

Finally, it is very fast to get the information for a single known service request. Below is an example of a random request I found on the website.

import boston311

service_request = boston311.get_service_request("101003914012")
print(service_request)
#> {
#>    'address': '335 Gallivan Blvd, 1, Dorchester',
#>    'address_id': None,
#>    'agency_responsible': None,
#>    'description': 'Dead cat',
#>    'expected_datetime': None,
#>    'lat': 42.28033447265625,
#>    'long': -71.06434967989543,
#>    'media_url': None,
#>    'requested_datetime': datetime.datetime(2021, 8, 14, 12, 19, 13, tzinfo=datetime.timezone(datetime.timedelta(days=-1, seconds=72000))),
#>    'service_code': '4f389210e75084437f0001c4',
#>    'service_name': 'Dead Animal Pick-up',
#>    'service_notice': None,
#>    'service_request_id': '101003914012',
#>    'status': <Status.OPEN: 'open'>,
#>    'status_notes': None,
#>    'updated_datetime': datetime.datetime(2021, 8, 14, 12, 19, tzinfo=datetime.timezone(datetime.timedelta(days=-1, seconds=72000))),
#>    'version': 1,
#>    'zipcode': None
#>}

Limitations

There are some parts of the API that I have not included in this package (e.g. the ability to make a new service request submission) because I do not currently need them. However, they are likely simple enough to add, so if you want them, either implement them yourself and submit a PR or open and Issue and I will eventually take care of it.

API Documentation

Below are links to the documentation for the original API.

• API website
• API docs

"""Access service request data from the Boston 311 API.

.. include:: ../README.md
"""

from .api import get_service_request, get_service_requests, get_services  # noqa: F401

__version__ = "0.1.1"

Sub-modules

boston311.api

Interacting with the Boston 311 API.

boston311.constants

Constants used throughout the project.

boston311.datamodels

Data models.

boston311.exceptions

Custom error types.

boston311.formatting

Formatters and formatting.

boston311.service_requests_parameters

Data model for handling logic in parameters of a 'service requests' request.