boston311.api API documentation
Description: Interacting with the Boston 311 API.

# Module `boston311.api`

Interacting with the Boston 311 API.

Expand source code

    """Interacting with the Boston 311 API."""
    from datetime import datetime
    from typing import Optional

    import requests

    from .constants import BOSTON_API_ENDPOINT
    from .datamodels import ServiceRequest, ServiceRequests, Services, Status
    from .exceptions import UnexpectedNumberOfResultsError
    from .service_requests_parameters import ServiceRequestsParameters

    def get_services() -> Services:
        """Retrieve the acceptable 311 service request types and their service codes.

        Raises:
            requests.HTTPError: Raised if the API request is unsuccessful.

        Returns:
            Services: Collection of all available services.
        """
        res = requests.get(BOSTON_API_ENDPOINT + "services.json")
        if res.status_code != 200:
            raise requests.HTTPError(res)
        return Services(services=res.json())

    def get_service_request(service_request_id: str) -> Optional[ServiceRequest]:
        """Query the current status of an individual request.

        Args:
            service_request_id (str): Service request ID.

        Returns:
            ServiceRequest: The service request information.
        """
        res = requests.get(BOSTON_API_ENDPOINT + f"requests/{service_request_id}.json")
        if res.status_code != 200:
            raise requests.HTTPError(res)
        results = res.json()
        if len(results) == 0:
            return None
        elif len(results) > 1:
            raise UnexpectedNumberOfResultsError(n_expected=1, n_received=len(results))
        return ServiceRequest(**results[0])

    def get_service_requests(
        service_code: Optional[str] = None,
        start_date: Optional[datetime] = None,
        end_date: Optional[datetime] = None,
        status: Optional[Status] = None,
    ) -> ServiceRequests:
        """Query the current status of multiple requests.

        All dates should be supplied with timezone information or they will be assumed to be
        in UTC.

        Args:
            service_code (Optional[str], optional): Specify the service type by calling the
            unique ID of the service_code. Defaults to `None` to request all service codes.
            start_date (Optional[datetime], optional): Earliest datetime to include in
            search. When not specified, the range defaults to most recent 90 days.
            Defaults to `None`.
            end_date (Optional[datetime], optional): Latest datetime to include in search.
            When not specified (`None`), the current date time is used. Defaults to `None`.
            status (Optional[Status], optional): Search for requests which have a specific
            status. Defaults to `None` to include all statuses.

        Raises:
            requests.HTTPError: Raised if the API request is unsuccessful.

        Returns:
            ServiceRequests: Collection of all service requests based on any provided
            criteria.
        """
        params = ServiceRequestsParameters(
            service_code=service_code,
            start_date=start_date,
            end_date=end_date,
            status=status,
        ).get_params()

        res = requests.get(BOSTON_API_ENDPOINT + "requests.json", params=params)
        if res.status_code != 200:
            raise requests.HTTPError(res)
        return ServiceRequests(service_requests=res.json())

## Functions

`def get_service_request(service_request_id: str) ‑> Optional[ServiceRequest]`

  Query the current status of an individual request.

  ## Args

  `service_request_id` :`str`
    Service request ID.

  ## Returns

  `ServiceRequest`
    The service request information.
  Expand source code

      def get_service_request(service_request_id: str) -> Optional[ServiceRequest]:
          """Query the current status of an individual request.

          Args:
              service_request_id (str): Service request ID.

          Returns:
              ServiceRequest: The service request information.
          """
          res = requests.get(BOSTON_API_ENDPOINT + f"requests/{service_request_id}.json")
          if res.status_code != 200:
              raise requests.HTTPError(res)
          results = res.json()
          if len(results) == 0:
              return None
          elif len(results) > 1:
              raise UnexpectedNumberOfResultsError(n_expected=1, n_received=len(results))
          return ServiceRequest(**results[0])

`def get_service_requests(service_code: Optional[str] = None, start_date: Optional[datetime.datetime] = None, end_date: Optional[datetime.datetime] = None, status: Optional[Status] = None) ‑> ServiceRequests`

  Query the current status of multiple requests.

  All dates should be supplied with timezone information or they will be assumed to be in UTC.

  ## Args

  `service_code` :`Optional[str]`, optional
    Specify the service type by calling the
  unique ID of the service_code. Defaults to `None` to request all service codes.
  `start_date` :`Optional[datetime]`, optional
    Earliest datetime to include in
  search. When not specified, the range defaults to most recent 90 days.
  Defaults to `None`.
  `end_date` :`Optional[datetime]`, optional
    Latest datetime to include in search.
  When not specified (`None`), the current date time is used. Defaults to `None`.
  `status` :`Optional[Status]`, optional
    Search for requests which have a specific

  status. Defaults to `None` to include all statuses.

  ## Raises

  `requests.HTTPError`
    Raised if the API request is unsuccessful.

  ## Returns

  `ServiceRequests`
    Collection of all service requests based on any provided

  criteria.

  Expand source code

      def get_service_requests(
          service_code: Optional[str] = None,
          start_date: Optional[datetime] = None,
          end_date: Optional[datetime] = None,
          status: Optional[Status] = None,
      ) -> ServiceRequests:
          """Query the current status of multiple requests.

          All dates should be supplied with timezone information or they will be assumed to be
          in UTC.

          Args:
              service_code (Optional[str], optional): Specify the service type by calling the
              unique ID of the service_code. Defaults to `None` to request all service codes.
              start_date (Optional[datetime], optional): Earliest datetime to include in
              search. When not specified, the range defaults to most recent 90 days.
              Defaults to `None`.
              end_date (Optional[datetime], optional): Latest datetime to include in search.
              When not specified (`None`), the current date time is used. Defaults to `None`.
              status (Optional[Status], optional): Search for requests which have a specific
              status. Defaults to `None` to include all statuses.

          Raises:
              requests.HTTPError: Raised if the API request is unsuccessful.

          Returns:
              ServiceRequests: Collection of all service requests based on any provided
              criteria.
          """
          params = ServiceRequestsParameters(
              service_code=service_code,
              start_date=start_date,
              end_date=end_date,
              status=status,
          ).get_params()

          res = requests.get(BOSTON_API_ENDPOINT + "requests.json", params=params)
          if res.status_code != 200:
              raise requests.HTTPError(res)
          return ServiceRequests(service_requests=res.json())

`def get_services() ‑> Services`

  Retrieve the acceptable 311 service request types and their service codes.

  ## Raises

  `requests.HTTPError`
    Raised if the API request is unsuccessful.

  ## Returns

  `Services`
    Collection of all available services.
  Expand source code

      def get_services() -> Services:
          """Retrieve the acceptable 311 service request types and their service codes.

          Raises:
              requests.HTTPError: Raised if the API request is unsuccessful.

          Returns:
              Services: Collection of all available services.
          """
          res = requests.get(BOSTON_API_ENDPOINT + "services.json")
          if res.status_code != 200:
              raise requests.HTTPError(res)
          return Services(services=res.json())