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:

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

Status: 400 Bad Request

{ "request": "Unable to parse JSON" }

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.

JSON-P Callbacks

You can send a ?callback parameter to any GET call to have the results
wrapped in a JSON function. This is typically used when browsers want
to embed SeeClickFix content in web pages by getting around cross domain
issues. The response includes the same data output as the regular API,
plus the relevant HTTP Header information.

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.

Points can be defined in one of two forms:

lat=:latitude&lng=:longitude - The latitude and longitude of the point of interest.

address=:address - Geocode the address and use the resulting latitude/longitude as a point.

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.

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 team@seeclickfix.com. We are very interested in working with researchers and/or agencies to ensure that this data is put to good use!