Open311

App · 6 actions

Read and file 311 service requests with any city on Open311 (GeoReport v2): list service types and their questions, find and read requests by type, status and date, file new ones, and run when a request comes in or is closed.

Actions

ActionWhat it does
File a service requestFile a new service request (a 311 report) with the city, at an address or a point, with answers to the service type's questions and a photo.
Get service requestGet one service request: its status and the city's notes, the address and when it was filed and updated.
Get service request ID from tokenLook up the id of a request filed with a token.
Get service type questionsGet the extra questions a service type asks when a request is filed, with the answers each allows and which are required.
List service requestsList the city's service requests, newest first, by type, status and when they were filed.
List service typesList every type of request the city takes (potholes, graffiti, missed pickups and so on) with its code, group and whether it asks extra questions.

File a service request

File a new service request (a 311 report) with the city, at an address or a point, with answers to the service type's questions and a photo. Needs the city's API key.

Inputs

Service typeservice_codetextRequired
The type of request, such as a pothole or missed trash pickup.
Descriptiondescriptiontext
What the problem is, in the reporter's words.
Addressaddresstext
Where the problem is, such as 1 City Hall Square. Give an address, or a latitude and longitude, or both.
Latitudelatitudenumber
The latitude of the problem, such as 42.3601.From -90 to 90.
Longitudelongitudenumber
The longitude of the problem, such as -71.0589.From -180 to 180.
Answers to the service type's questionsattributesobject
The extra questions the chosen service type asks, filled in for you once a service type is picked.
Photo addressmedia_urltext
The https:// address of a photo of the problem.
Reporter emailemailtext
The reporter's email address, for the city's updates.
Reporter first namefirst_nametext
The reporter's first name.
Reporter last namelast_nametext
The reporter's last name.
Reporter phonephonetext
The reporter's phone number.

Outputs

account_idtext
The reporter's account with the city, if any
filedtrue/false
True once the city gave an id or a token
service_noticetext
What the city says to expect
service_request_idtext
The new request's id, empty while the city is still filing it
tokentext
A token to look the id up with later
Example output
{
  "account_id": "",
  "filed": true,
  "service_notice": "The city will review this within 2 business days.",
  "service_request_id": "",
  "token": "9a4805cb-45e7-46d8-b8b7-04613bd57f3b"
}

Get service request

Get one service request: its status and the city's notes, the address and when it was filed and updated.

Inputs

Service request IDservice_request_idtextRequired
The request's id, from 'List service requests' or an earlier step.

Outputs

requestobject
The request
Example output
{
  "request": {
    "address": "60 Paul Sullivan Way, Boston, MA 02118",
    "address_id": "",
    "agency_responsible": "",
    "description": "Litter in the bushes by the front door.",
    "expected_datetime": "",
    "lat": 42.342921,
    "long": -71.0643375,
    "media_url": "",
    "requested_datetime": "2026-10-30T21:18:12Z",
    "service_code": "155a5e9b-8c3a-4279-bbab-f6bba6ddb0d0",
    "service_name": "Litter & Debris",
    "service_notice": "",
    "service_request_id": "47078e67-964d-4090-b9d2-155ae4d4f094",
    "status": "open",
    "status_notes": "",
    "token": "9a4805cb-45e7-46d8-b8b7-04613bd57f3b",
    "updated_datetime": "2026-10-30T22:45:57Z",
    "zipcode": ""
  }
}

Get service request ID from token

Look up the id of a request filed with a token. Some cities give an id only once the request has been filed in their system; until then the id is empty.

Inputs

TokentokentextRequired
The token from 'File a service request'.

Outputs

readytrue/false
True once the request has an id
service_request_idtext
The request's id, empty until it has one
tokentext
The token looked up
Example output
{
  "ready": true,
  "service_request_id": "47078e67-964d-4090-b9d2-155ae4d4f094",
  "token": "9a4805cb-45e7-46d8-b8b7-04613bd57f3b"
}

Get service type questions

Get the extra questions a service type asks when a request is filed, with the answers each allows and which are required.

Inputs

Service typeservice_codetextRequired
The type of request, such as a pothole or missed trash pickup.

Outputs

attributeslist
The questions, in the order the city asks them
countnumber
How many
required_codeslist
The codes of the questions that need an answer
service_codetext
The service type
Example output
{
  "attributes": [
    {
      "code": "BOSArePeoplePresentId",
      "datatype": "singlevaluelist",
      "datatype_description": "",
      "description": "Are there people present?",
      "order": 1,
      "required": true,
      "values": [
        {
          "key": "801fa657-2584-4ee7-b577-6d87c909d337",
          "name": "Yes"
        },
        {
          "key": "be13e3e4-bf04-4e91-9aa5-b311e3252869",
          "name": "No"
        }
      ],
      "variable": true
    }
  ],
  "count": 1,
  "required_codes": [
    "BOSArePeoplePresentId"
  ],
  "service_code": "8638e79a-2a0a-4d3a-9624-792ec40b0691"
}

List service requests

List the city's service requests, newest first, by type, status and when they were filed.

Inputs

Service typeservice_codetext
Only requests of this type. Leave empty for every type.
Statusstatustext
Only open or only closed requests. Leave empty for both.One of: open, closed.
Filed afterrequested_afterdate and time
Only requests filed at or after this time. Most cities return the last 90 days when no range is given.
Filed beforerequested_beforedate and time
Only requests filed at or before this time.
Most resultsmax_resultsnumber
How many requests to return at most, newest first, 1 to 1,000. Defaults to 100. Cities also cap how many they send at once.From 1 to 1000.

Outputs

countnumber
How many
requestslist
The service requests
total_returnednumber
How many the city sent, before 'Most results'
Example output
{
  "count": 1,
  "requests": [
    {
      "address": "60 Paul Sullivan Way, Boston, MA 02118",
      "address_id": "",
      "agency_responsible": "",
      "description": "Litter in the bushes by the front door.",
      "expected_datetime": "",
      "lat": 42.342921,
      "long": -71.0643375,
      "media_url": "",
      "requested_datetime": "2026-10-30T21:18:12Z",
      "service_code": "155a5e9b-8c3a-4279-bbab-f6bba6ddb0d0",
      "service_name": "Litter & Debris",
      "service_notice": "",
      "service_request_id": "47078e67-964d-4090-b9d2-155ae4d4f094",
      "status": "open",
      "status_notes": "",
      "token": "9a4805cb-45e7-46d8-b8b7-04613bd57f3b",
      "updated_datetime": "2026-10-30T22:45:57Z",
      "zipcode": ""
    }
  ],
  "total_returned": 1
}

List service types

List every type of request the city takes (potholes, graffiti, missed pickups and so on) with its code, group and whether it asks extra questions.

Inputs

None.

Outputs

countnumber
How many
serviceslist
The service types
Example output
{
  "count": 1,
  "services": [
    {
      "description": "",
      "group": "Street Cleaning",
      "keywords": "",
      "metadata": true,
      "service_code": "155a5e9b-8c3a-4279-bbab-f6bba6ddb0d0",
      "service_name": "Litter & Debris",
      "type": "batch"
    }
  ]
}

On this page