FixMyStreet support for Open311

FixMyStreet supports Open311 both as a client (sending reports made on the site to an external service via the Open311 protocol), and partly as a server (returning reports made on the site when queried via the Open311 protocol).

What is Open311?

In a nutshell, it's an international open standard that allows services to 'talk to' council systems.

As channels of communication diversify, it has become more and more important that council systems can recognise and accept reports from a variety of sources. For example, reports may come in via Twitter, SMS, email, services like FixMyStreet, and the council's own website.

Where can I find out more?

Open311 isn't as widely known as it deserves to be, so we wrote a short series of blog posts to explain the basics. And you can find out lots more at open311.org.

Why does it matter?

If you oversee problem reports at a council, you will of course be concerned about future-proofing your communication channels in an easy and economical way – Open311 gives you that assurance.

You may be interested to know about FixMyStreet Pro, our hosted service which sits seamlessly on your council website.

We can integrate it with any council back-end system, but if you use Open311, we charge less. That's how much we believe it's the sane way forward for council problem-reporting systems.

Any questions?

We're always happy to talk. Just drop us a line.

Open311 API for the mySociety FixMyStreet server

At the moment only searching for and looking at reports work.

This API implementation is work in progress and not yet stabilized. It will change without warnings in the future.

At most 1000 requests are returned in each query. The returned requests are ordered by requested_datetime, so to get all requests, do several searches with rolling start_date and end_date.

The following Open311 v2 attributes are returned for each request: service_request_id, description, lat, long, media_url, status, requested_datetime, updated_datetime, service_code and service_name.

In addition, the following attributes that are not part of the Open311 v2 specification are returned: agency_sent_datetime, title (also returned as part of description), interface_used, comment_count, requestor_name (only present if requestor allowed the name to be shown on this site).

The Open311 v2 attribute agency_responsible is used to list the administrations that received the problem report, which is not quite the way the attribute is defined in the Open311 v2 specification.

With request searches, it is also possible to search for agency_responsible to limit the requests to those sent to a single administration. The search term is the administration ID provided by MaPit.

Examples:

discovery information: XML or JSON
/open311/v2/discovery.format?jurisdiction_id=fixmystreet
list of services provided: XML or JSON
/open311/v2/services.format?jurisdiction_id=fixmystreet
list of services provided for WGS84 coordinate latitude 60 longitude 11: XML or JSON
/open311/v2/services.format?jurisdiction_id=fixmystreet&lat=60&long=11
Request number 1: XML or JSON
/open311/v2/requests/1.format?jurisdiction_id=fixmystreet
All requests with the category 'Car parking': XML or JSON
/open311/v2/requests.format?jurisdiction_id=fixmystreet&service_code=Car%20parking
All closed requests: XML or JSON
/open311/v2/requests.format?jurisdiction_id=fixmystreet&status=closed
All open requests reported before 2011-03-10 to Trondheim (id 1601): XML or JSON
/open311/v2/requests.format?jurisdiction_id=fixmystreet&status=open&agency_responsible=1601&end_date=2011-03-10
All open requests in Asker (id 220) and Bærum (id 219): XML or JSON
/open311/v2/requests.format?jurisdiction_id=fixmystreet&status=open&agency_responsible=219|220

Searching

The following search parameters can be used:

service_request_id: Search for numeric ID of specific request. Using this is identical to asking for a individual request using the /requests/number.format URL.
service_code: Search for the given category / service type string.
status: Search for open or closed (fixed) requests.
start_date
: Only return requests with requested_datetime set after or at the date and time specified. The format is YYYY-MM-DDTHH:MM:SS+TZ:TZ.
end_date
: Only return requests with requested_datetime set before the date and time specified. Same format as start_date.
agency_responsible: ID of government body receiving the request. Several IDs can be specified with | as a separator.
interface_used
: Name / identifier of interface used.
has_photo
: Search for entries with or without photos. Use value 'true' to only get requests created with images, and 'false' to get those created without images.
max_requests: Max number of requests to return from the search. If it is larger than the site specific max_requests value specified in the discovery call, the value provided is ignored.