Open311: Explained

In the previous blog post we explained why we think Open311 is a good idea. In this post we’ll explain what it actually does.

Open311 is very simple, but because it’s fundamentally a technical thing it’s usually explained from a technical point of view. So this post describes what Open311 does without the nerdy language (but with some nerdy references for good measure). At the end there’s a round-up of the terms so you can see how it fits in with the actual specification.

We’re using an unusual example here — a blue cat stuck up a tree — to show how applicable Open311 is to a wide range of problems. Or, to put it another way, this is not just about potholes.

Cat up a tree and an Open311 robot

So… someone has a problem they want to report (for this discussion, she’s using a service like FixMyStreet).

There’s one place where that report needs to be sent (in the UK, that’s your council). That administrative body (the council) almost certainly has a database full of problems which only their staff can access.

I have a problem :–(

the “client”

I fix problems!

the “server”

In this example, FixMyStreet is an Open311 client and the council is an Open311 server. The server is available over HTTP(S), so the client can access it, and the server itself connects to the council’s database. In reality it’s a little bit more complicated than that (for now we’ll ignore clients that implement only part of Open311, multiple servers, and decent security around these connections), but that is the gist of it.

Although it’s not technically correct to confuse the client with the user, or the server with the council, it makes things a lot easier to see it this way, so we’ll use those terms throughout.

Service discovery

To start things off, the client can ask the server: what services do you provide?

Until the client has asked the server what problems it can fix, it can’t sensibly request any of them.

What services do you offer?

I can:
POT: fix potholes
TELE: clean public teleports
PET: get pets down from trees
JET: renew jetpack licenses …

FixMyStreet can use the response it gets from such a service discovery to offer different categories to people reporting problems. We actually put them into the drop-down menu that appears on the report-a-problem page.

In the Open311 API, this is handled by GET Service List. Each service has its own service_code which the client must use when requesting it. Note that these services and their codes are decided by the server; they are not defined by the Open311 specification. This means that service discovery can easily fit around whatever services the council already offers. The list of services can (and does) vary widely from one council to the next.

Service definitions

Some services require specific information when they are requested. For example, it might be important to know how deep a pothole is, but it’s not relevant for a streetlight repair.

Tell me more about the PET service!

I can get pets down from trees, but when you request the service, you *must* tell me what kind of animal the pet is, OK?

In the Open311 API, this is handled by the GET Service Definition method. It’s not necessary for a simple Open311 implementation. In fact, it only makes sense if the service discovery explicitly told the client to ask about the extra details, which the server does by adding metadata="true" to its response for a given service.

Requesting a service

This is where it gets useful. The client can request a service: this really means they can report a problem to the server for the body to deal with. Some submissions can be automatically rejected:

My hoverboots are broken :–( I need BOOT service!

404: Bzzzt error! I don’t fix hoverboots (use service discovery to see what I *do* fix)

Hey! Blueblue is up a tree! I need PET service (for cats)!

400: error! You forgot to tell me where it is.

If the report is in good order, it will be accepted into the system. Open311 insists that every problem has a location. In practice this is usually the exact position, coordinates on planet Earth, of the pin that the reporter placed on the map in the client application (in this case FixMyStreet.com).

I need PET service (for cats)! Blueblue is stuck up the biggest tree in the park :–(

200: OK, got it… the unique ID for your request is now 981276

In the Open311 API, this is handled by POST Service Request. You need an API key to do this, which simply means the server needs to know which client this is. Sometimes it makes sense for the server to have additional security such as IP address restriction, and login criteria that’s handled by the machines (not the user).

Listing known requests

The server doesn’t keep its reports secret: if asked, it will list them out. The client can ask for a specific report (using the ID that the server gave when the report was submitted, for example) or for a range of dates.

Did anyone ask you for help yesterday?

Yes, I got two requests:

request 981299: TELE dirty teleport at the cantina (I’m waiting for a new brush)

request 971723: POT pothole at the junction of Kirk and Solo (I filled it in)

In the Open311 API this is handled by GET Service Request(s). The client can indicate which requests should be listed by specifying the required service request id, service code, start date, end date or status.

Does Open311 work?

Oh yes. On the Open311 website, you can see the growing list of places, organisations, and suppliers who are using it.

The technical bit

In a nutshell: Open311 responds to HTTP requests with XML data (and JSON, if it’s wanted). There’s no messing around with SOAP and failures are reported as the HTTP status code with details provided in the content body.

You can see the specification for Open311 (GeoReport v2). It doesn’t feature blue cats, but if you look at the XML examples you’ll be able to recognise the same interaction described here. And remember the specification is an open standard, which means anyone can (and, we think, should) implement it when connecting a client and server in order to request civic services.

Coming next…

In the next blog post we’ll look at how FixMyStreet uses Open311 to integrate with local council systems, and explain why we’re proposing, and utilising, some additions to the Open311 specification.

Illustrated especially for us by René Carbonell.

1 Comment

  1. Jaakko Rajaniemi

    Thanks for the great, funny and very useful tutorial!

    I’m involved in CitySDK project (http://www.citysdk.eu/) and we are also recommending the use of Open311. I’m also working for the City of Helsinki and we are soon launching our Open311 interface. It’s great to have mySociety supporting the standard too.