How to interact with FixMyStreet via code

FixMyStreet offers a beta API modelled on the emerging Open311 GeoReport v2 standard.

XML in email notifications to councils

When an Issue is confirmed by submitter, an email notification is sent to the designated council email address. The email includes XML similar to the following:


<request>
  <jurisdiction_id>taupodc.govt.nz</jurisdiction_id>
  <fixmystreet_issue_id>123</fixmystreet_issue_id>
  <service_name>Street lighting</service_name>
  <service_code><!--empty--></service_code>
  <lat>-43.543266</lat>
  <long>172.68926</long>
  <address_string>190 Cashel St</address_string>
  <email>foo@example.com</email>
  <device_id><!--empty--></device_id>
  <account_id><!--empty--></account_id>
  <first_name>Jim</first_name>
  <last_name>Citizen</last_name>
  <phone>12 987 6543</phone>
  <description>Street light pole damaged: Looks like it was hit by a car.</description>
  <media_url>http://fixmystreet.org.nz/sites/fixmystreet.org.nz/files/imagecache/preview/photos/Photo0038_0.jpg</media_url>
  <attribute><url>http://fixmystreet.org.nz/issue/123</url></attribute>
  <!-- sent from fixmystreet.org.nz -->
</request>

Access to API

To access the API, first request an API key.

We'll send you an API key to use in requests to the API. Please keep it private.

The API endpoint is http://fixmystreet.org.nz/api/v2/

Include the API key in all requests, e.g. http://fixmystreet.org.nz/api/v2/update.xml?api_key=12345678901234567890123456789012.

Update resource

Indicate acceptance of a service request or subsequent status changes for a service request using the Update resource: http://fixmystreet.org.nz/api/v2/update. Issue an HTTP POST request containing XML to the update resource. This resource is outside the Open311 GeoReport v2 standard.

Specify XML or JSON as the response format by adding .xml or .json to the resource: http://fixmystreet.org.nz/api/v2/update.xml or http://fixmystreet.org.nz/api/v2/update.json.

Request

<update>
  <jurisdiction_id>taupodc.govt.nz</jurisdiction_id>
  <fixmystreet_issue_id>612</fixmystreet_issue_id>
  <service_request_id>123</service_request_id>
  <status>open</status>
  <comment>The service request id for this issue is 123.</comment>
  <email>test@taupo.govt.nz</email>
  <name>Taupo DC Customer Services</name>
  <url>http://www.taupo.govt.nz</url>
</update>

Response

A successful response will return HTTP 201 Created and a message with the URL of the update:

<result>
  <api_version>v2</api_version>
  <update>
    <url>http://dev.fixmystreet.org.nz/issue/612#comment-95</url>
  </update>
</result>

A missing or invalid API key will result in HTTP 401 Access denied.

If the fixmystreet_issue_id can't be matched, HTTP 404 Not found will be returned.

If required parameters are missng, the response will be HTTP 400 Bad request.

jurisdiction_id
Explanation: Main website root domain (without www). Must match jurisdiction of Issue being updated. Required.
fixmystreet_issue_id
Explanation: Id of Issue on FixMyStreet, per XML payload in notification email, or per URL http://fixmystreet.org.nz/issue/NNN. Required.
service_request_id
Explanation: Council's internal tracking Id for this Service Request. Required.
status
Options: open, closed
Explanation: The current status of the service request. Open means that it has been reported. Closed means that it has been resolved. For FixMyStreet, closed will be marked as fixed, so if the Issue isn't fixed, please explain further in the comment. Optional, though one of status or comment is required.
comment
Explanation: Free text field explaining actions taken to date, or describing status. Include service request id for human reference. Optional, though one of status or comment is required.
email
Explanation: Email address for follow up on this service request. (Not shown publicly.) Required.
name
Explanation: Name of person or group handling the service request. Required.
url
Explanation: URL for more information about the service request. Optional.

Updates are not currently forwarded to the submitter. You will need to contact them directly.

Please note that this API is subject to change.

Test using curl

curl -v --basic -u fixmystreet:fixmystreet -X POST -H "Content-type: application/xml" -d "<update><jurisdiction_id>taupodc.govt.nz</jurisdiction_id><fixmystreet_issue_id>731</fixmystreet_issue_id><service_request_id>123</service_request_id><comment>The service request id is #123.</comment><email>test@taupo.govt.nz</email><name>Taupo DC Customer Services</name><url>http://www.taupo.govt.nz</url><status>open</status></update>" "http://test.fixmystreet.org.nz/api/v2/update.xml?api_key=12345678901234567890123456789012"
This site is a beta version.