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
- Testing
- URL Format
- Data Format
- Responses
- Parameters
- Pagination
- Blank Fields
- Time Formats
- Error Responses
- HTTP Redirects
- HTTP Verbs
- User Agent Required
- Conditional requests
- Geography
- Locales
- Data License
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
.
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:
-
lat=:latitude&lng=:longitude
- The latitude and longitude of the point of interest. -
address=:address
- (deprecated) Geocode the address and use the resulting latitude/longitude as a point.
area
attributes can be submitted in the following forms:
lat=:latitude&lng=:longitude&zoom=:zoom
-
address=:address&zoom=:zoom
- (deprecated) -
place_url=:url_name
- See the places documentation for more information. -
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 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