Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Open311 FMS Proposed differences to Open311

struan edited this page · 2 revisions

NB: this page is currently a work in progress.

There will be a blog post along shortly to explain the full context for this but the brief version is that while Open311 does a lot of the things that FixMyStreet requires it's lacking in a few places. This is a proposal to fill those holes.

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

The changes to Open311 in this document are as follows:

  • All POSTs should be over HTTPS
  • Add a GET Service Request Updates
  • Add a POST Service Request Update

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

Purpose Fetch a list of recent updates to Requests
URL http://[API endpoint]/servicerequestupdates.[format]
Sample URL http://api.city.gov/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
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
description
The message associated with the update

Optional Parameters

Field Name Description Notes & Requirements
email
The email address 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

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
Something went wrong with that request. Please try again.