Taking a break...

FixMyStreet is going offline shortly, probably permanently. The software is old and needs a complete rewrite, the site is being bombarded by spammers, and it is debatable whether councils are receiving and/or acting on FixMyStreet reports.

As of now, it is not possible to post new issues, or updates to published issues.

If you have submitted on FixMyStreet, thank you for playing a part in one of Aotearoa/New Zealand's early civic tech projects.

How to interact with FixMyStreet via code

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

At the moment the API is limited, only sufficient for councils to add updates to issues they have received. Watch this space (or follow @fixmystreetnz) to receive notification of expanded API capabilties.

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 https://fixmystreet.org.nz/api/v2/

Include the API key in all requests, e.g. https://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: https://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: https://fixmystreet.org.nz/api/v2/update.xml or https://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"