SeeClickFix API v2 Overview

Use of the API documented here is subject to the terms of our Data License below.

This describes the resources that make up the official SeeClickFix API v2. If you have any problems or requests please contact Developer Support.

SeeClickFix provides an open311 compatible API at http://seeclickfix.com/open311.

SeeClickFix also provides an organizational API based on the public API described here for its partners.

For recommendations on which API to use, please see this page.

Coordinate System

All coordinates are assumed to be WSG84. Geographic objects are represented as GeoJSON.

Testing

Testing can be done on the test.seeclickfix.com subdomain. This subdomain has data replicated from production. SSL (https) is available on test.seeclickfix.com.

URL Format

URLs follow the following format

https://seeclickfix.com/api/v2/< RESOURCE >

Data Format

All data is sent and received as JSON.

Responses

Responses follow one of two patterns: singular and collection.

singular responses return a single items, such as a user ID #145.

collection responses return a collection of items. Collection responses have two guaranteed attributes metadata and result. The metadata attribute can contain metadata for the consumer about the result, for example pagination information, api limits, or query information. Metadata can be null. The result attribute contains the result of the action.

Parameters

Many API methods take optional parameters. Optional parameters will be identified as optional in the documentation.

For POST requests, parameters not included in the URL should be encoded in the body with a Content-Type of ‘application/x-www-form-urlencoded’. Optionally we accept JSON in the body with a Content-Type of ‘application/json’:

Pagination

Requests that return multiple items will be paginated to 20 items by default unless otherwise noted. You can specify further pages using the ?page parameter. You can also set a custom page size up to 100 with the ?per_page parameter. If you’d like to read more than 100 items you’ll need to construct and query the pages programatically.

$ curl https://seeclickfix.com/api/v2/issues?page=2&per_page=10

Blank Fields

Blank fields are included as null instead of being omitted.

Time Formats

All timestamps are returned in ISO 8601 format:

YYYY-MM-DDTHH:MM:SSZ

Error Responses

Errors

There are two possible types of client errors:

  1. Sending invalid JSON will result in a 400 Bad Request response.

    Status: 400 Bad Request
     { "request": "Unable to parse JSON" }

  2. Sending invalid fields will result in a 422 Unprocessable Entity response.

    Status: 422 Unprocessable Entity
     {
       "email": "Can't be blank.",
       "base": "You have not voted on this issue."
 }

Server Errors

All server errors return 500 Server Error.

Status: 500 Server Error

HTTP Redirects

API v2 uses HTTP redirection where appropriate. Clients should assume that any request may result in a redirection. Receiving an HTTP redirection is not an error and clients should follow that redirect. Redirect responses will have a Location header field which contains the URI of the resource to which the client should repeat the requests.

Status: 301 Moved Permanently

The URI you used to make the request has been superseded by the one specified in the Location header field. This and all future requests to this resource should be directed to the new URI.

Status: 302 Found

The request should be repeated verbatim to the URI specified in the Location header field but clients should continue to use the original URI for future requests.

Other redirection status codes may be used in accordance with the HTTP 1.1 spec.

HTTP Verbs

Where possible, API v2 strives to use appropriate HTTP verbs for each action.

GET
Used for retrieving resources.
POST
Used for creating resources.
PUT
Used for updating resources.
DELETE
Used for deleting resources.

User Agent Required

All API requests MUST include a valid User Agent string. Requests with no User Agent string will be rejected. If you are hitting the API without authentication, we ask that you add some kind of identification to the UA header value. This is so we can contact you if there are problems.

Conditional requests

Most responses return Last-Modified and ETag headers. You can use the values of these headers to make subsequent requests to those resources using the If-Modified-Since and If-None-Match headers, respectively. If the resource has not changed, the server will return a 304 Not Modified.

Geography

At various endpoints SeeClickFix recognizes geography either by a point or area attribute. If multiple points are specified, they will be evaulated in the listed order of precedence.

NOTE: The use of the address parameter to specifiy a location is deprecated on our public endpoints. API clients must handle reverse geocoding locally and use one of the alternate parameter forms to specify a point or area. Queries using address may result in an error response.

Points can be defined in one of two forms:

  1. lat=:latitude&lng=:longitude - The latitude and longitude of the point of interest.
  2. address=:address - (deprecated) Geocode the address and use the resulting latitude/longitude as a point.

area attributes can be submitted in the following forms:

  1. lat=:latitude&lng=:longitude&zoom=:zoom
  2. address=:address&zoom=:zoom - (deprecated)
  3. place_url=:url_name - See the places documentation for more information.
  4. min_lat=:sw_lat&min_lng=:sw_lng&max_lat=:ne_lat&max_lng=:ne_lng - Defines the bounding box of the area of interest.
  5. watcher_token=:watcher_token - The token can be found in the URL of the watch area’s issue map, a link to this can be found on the right hand column of the watch area display page

Locales

All attributes are consistent between locales. Errors may be translated based on the given locale. Objects created will record the locale they were created in and notices based on these objects will be delivered with the proper locale. i.e. if an issue is created with the “es” locale, all email to the creator will be delivered with Spanish translations.

Data License

SeeClickFix data sources, including XML, RSS, KML and JSON, are licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 United States License. Attribution should be to seeclickfix.com.

Persons or organizations wishing to reuse large portions (ie., more than occasional queries ) of data are required to contact us first at support@seeclickfix.com. We are very interested in working with researchers and/or agencies to ensure that this data is put to good use!

API Rate Limits

The rate limit allows for up to 20 requests per minute.

Rate limit is subject to change.

HTTPS Headers and Response Codes

If you go over the rate limits, we will return a HTTP 429 Too Many Requests error, and a Retry-After HTTP header containing the number of seconds until you can retry.

HTTP/1.1 429 Too Many Requests
Cache-Control: private
Content-Length: 23
Content-Type: application/json; charset=utf-8
Retry-After: 10
Server: Microsoft-IIS/10.0
X-AspNetMvc-Version: 5.1
Access-Control-Allow-Origin: *
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
Set-Cookie: ARRAffinity=beec3692492323782378d2f49514e054d865a22ad2951c
Date: Fri, 01 Mar 2019 15:23:13 GMT

{
    "message": "Too Many Requests",
    "documentation_url": "http://dev.seeclickfix.com"
}

Blacklisting

If an application abuses the rate limits, we will return a HTTP 403 Forbidden error.

HTTP/1.1 403 Forbidden
Cache-Control: private
Content-Length: 15
Content-Type: application/json; charset=utf-8
Server: Microsoft-IIS/10.0
X-AspNetMvc-Version: 5.1
Access-Control-Allow-Origin: *
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
Set-Cookie: ARRAffinity=beec3692492323782378d2f49514e054d865a22ad2951c
Date: Fri, 01 Mar 2019 16:11:07 GMT

{
    "message": "Request forbidden by administrative rules.",
    "documentation_url": "http://dev.seeclickfix.com"
}

If you or your application has been blacklisted and you think there has been a mistake, please contact us at support@seeclickfix.com