Skip to content

Open311 FMS Proposed differences to Open311

Jump to bottom Edit New page
M Somerville edited this page Mar 21, 2024 · 10 revisions

Open311 does a lot of the things that FixMyStreet requires but it's lacking in a few places. This is a proposal to fill those holes.

This page should be read in conjunction with the Open311 specification.

The changes to Open311 in this document and wiki are as follows:

POSTs over HTTPS

Because the POST requests usually pass at least some sensitive user details such as email address of phone number these should use HTTPS in order to protect users data.

This means that the following methods should now always use HTTPS:

  • POST Service Request
  • POST Service Request Updates

This is not required for GET requests as it is assumed that the information contained in those is public information.

Get Service Request Updates

FixMyStreet can also receive updates POSTed to it; the same format as would be returned below, posted as if we were the Open311 server receiving an update.

Purpose Fetch a list of recent updates to Requests
URL https://[API endpoint]/servicerequestupdates.[format]
Sample URL https://api.city.example.com/dev/v2.1/servicerequestupdates?start_date=2010-05-24T00:00:00Z&end_date=2010-06-24T00:00:00Z&jurisdiction_id=city.gov
Formats XML (JSON available if denoted by Service Discovery)
HTTP Method GET
Requires API Key No

Required arguments

Field Name Description Notes & Requirements
jurisdiction_id
 This is only required if the endpoint serves multiple jurisdictions

Optional arguments

Field Name Description Notes & Requirements
start_date
 Earliest update to include in returned results In W3 format
end_date
 Latest update to include in returned results In W3 format

Response

Field Name Description Notes & Requirements
service_request_updates ⇊
request_update ↴
update_id
 The ID of the service request update.
service_request_id
 The ID of the service request that the update is for.
status
 The status of the service request after the update. Possible values: OPEN, CLOSED (though see our extension)
updated_datetime
 The datetime of the update. In W3 format
description
 The text of the update.
media_url
 The URL of any associated media, e.g an image

Response Volume

The default query limit is a span of 24 hours or the first thousand requests, whichever is smallest.

Possible Errors

The numbers represent the HTTP status code returned for each error type:

  • 404 - jurisdiction_id not found
  • 400 - jurisdiction_id was not provided
  • 400 - General service error

Example response

<?xml version="1.0" encoding="utf-8"?>
<service_request_updates>
    <request_update>
        <update_id>20474</update_id>
        <service_request_id>2934</service_request_id>
        <status>OPEN</status>
        <updated_datetime>2010-04-14T10:37:38-01:00</updated_datetime>
        <description>This problem has been scheduled for inspection</description>
    </request_update>
    <request_update>
        <update_id>20473</update_id>
        <service_request_id>2937</service_request_id>
        <status>OPEN</status>
        <updated_datetime>2010-04-14T10:23:54-01:00</updated_datetime>
        <description>An engineering team will be starting work shortly</description>
    </request_update>
    <request_update>
        <update_id>20472</update_id>
        <service_request_id>2930</service_request_id>
        <status>CLOSED</status>
        <updated_datetime>2010-04-14T10:07:45-01:00</updated_datetime>
        <description>This pothole has been repaired.</description>
    </request_update>
    <request_update>
        <update_id>20471</update_id>
        <service_request_id>2934</service_request_id>
        <status>OPEN</status>
        <updated_datetime>2010-04-14T09:52:21-01:00</updated_datetime>
        <description>Awaiting shceduling of inspection team.</description>
    </request_update>
</service_request_updates>

POST Service Request Update

Purpose Post an update to a service request
URL https://[API endpoint]/servicerequestupdates.[format]
Sample URL https://api.city.gov/dev/v2/servicerequestupdates.xml
Formats XML (JSON available if denoted by Service Discovery)
HTTP Method POST
Requires API Key Yes

Required Parameters

Field Name Description Notes & Requirements
jurisdiction_id
 This is only required if the endpoint serves multiple jurisdictions
update_id
 The id of the update
service_request_id
 The ID of the service request the update is for This should be the service_request_id returned from a previous POST ServiceRequest call
updated_datetime
 The date and time of the update In W3 format
status
 The status of the service request after the update Possible values: OPEN or CLOSED (though see our extension)
description
 The message associated with the update

Optional Parameters

Field Name Description Notes & Requirements
email
 The email address of the person leaving the update
phone
 The phone number of the person leaving the update
last_name
 The last name of the person leaving the update
first_name
 The first name of the person leaving the update
title
 The title of the person leaving the report
media_url
 The URL of any associated media, e.g a photograph
account_id
 The unique ID for the user account of the person submitting the update

One user of this extension is slightly custom: It uses update_id_ext for the update ID, and adds service_request_id_ext (this end's report ID), public_anonymity_required (did the user ask for anonymity), and email_alerts_requested (did they ask to be alerted).

Response

Field Name Description Notes & Requirements
service_request_updates ⇊
request_update ↴
update_id
 The ID of the service request update. This should not be returned if token is returned
token
 If returned use this to call GET update_id from a token. This should not be returned if service_request_id is returned
account_id
 The unique ID for the user account of the person submitting the request May not be returned

Possible Errors

The numbers represent the HTTP status code returned for each error type:

  • 404 - jurisdiction_id or service_request_id not found (specified in error message)
  • 400 - Required argument was not provided (specified in error message)
  • 400 - General service error

Example Request

POST /v2.1/servicerequestupdates.xml
HOST api.city.gov
Content-Tpe: application/x-www-form-urlencoded; charset=utf-8

api_key=xyz&jurisdiction_id=city.gov&update_id=13456&service_request_id=1934&status=OPEN&description=The+pothole+has+got+much+larger&updated_datetime=2010-04-14T10:33:11-01:00&email=user%40example.com&last_name=User&first_name=A

Example Response

<?xml version="1.0" encoding="utf-8"?>
<service_request_updates>
    <request_update>
        <update_id>392732</update_id>
    </request_update>
</service_request_updates>

GET update_id from a token

Conditional Yes - This call is only necessary if the response from POST Service Request Update contains a token
Purpose Get the update_id from a temporary token. This is unnecessary if the response from creating a service request update does not contain a token.
URL https://[API endpoint]/update_tokens/[token id].[format]
Sample URL https://api.city.gov/dev/v2.1/update_tokens/123456.xml?jurisdiction_id=city.gov
Formats XML (JSON available if denoted by Service Discovery)
HTTP Method GET
Requires API Key No

Required arguments

Field Name Description Notes & Requirements
jurisdiction_id
 This is only required if the endpoint serves multiple jurisdictions
token
 This is obtained from the POST Service Request Update method

Response

Possible Errors

The numbers represent the HTTP status code returned for each error type:

  • 404 - jurisdiction_id or token not found (specified in error message)
  • 400 - jurisdiction_id or token was not provided (specified in error message)
  • 400 - General service error

Example Response

<?xml version="1.0" encoding="utf-8"?>
<service_request_updates>
    <request_update>
        <update_id>392732</update_id>
        <token>10393383</update_id>
    </request_update>
</service_request_updates>
Field Name Description Notes & Requirements
service_request_updates ⇊
request_update ↴
update_id
 The ID of the service request update.
token
 The token used to make this call

See http://fixmystreet.org/ for documentation

Add a custom sidebar
Clone this wiki locally