Smart Cambridge APIs

This API provides programmatic access to information maintained by the Smart Cambridge project.

Currently available:

API Endpoints

There is a seperate reference page documenting the API endpoints.

The API operates over HTTP using REST-like conventions with parameters encoded in URL paths and query parameters. It can be accessed by any tool capable of making HTTP requests and interpreting the results. The reference page promotes the use of the CoreAPI toolset but the API is in no way restricted to CoreAPI-aware tools.

Authentication

All API calls must be authenticated by someone who has agreed to the platform's Terms and Conditions. You make authenticated calls either:

  • by signing in (and agreeing the terms and conditions if you haven't already)
  • by including an API token with the call. Beware that API calls made from browsers, for example from JavaScript, will always succeed for as long as you are logged in to this website even if you are not successfully supplying a token.

To call the API using the 'Interact' links on the reference page you can also authenticate using the 'Authentication' menu at the bottom-left of that page providing you have already agreed to the terms and conditions.

Tokens

You can create and subsequently manage as many API tokens as you want.

To use a token for authentication, include it in an Authorization HTTP header in your requests, proceeded by the word Token and a single space:

Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

For example:

curl -H 'Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b' https://smartambridge.org/api/v1/aq/ 

Tokens used by JavaScript applications are of necessity exposed. To minimise the impact of this you can associate any token with a list of 'referer' patterns. Access using that token will then be rejected if the 'Referer' header provided by a browser don't match any of the patterns. While this is easily subverted in server-side scripts and by using custom proxies it does make it slightly harder to misuse tokens that are exposed in this way.

You can setup referer restrictions on tokens from the token management page.

Rate limiting

Access to the API is rate-limited to 1200 requests per minute and 12000 requests per hour per token for token-based access, or per user otherwise. These are intended as back-stops to avoid accidents - please aim to keep you use of the API well below these rates. These limits may be reduced in the future.

Results format

Results are normally returned in JSON with Content-Type: application/json. However if a response is explicitly requested in HTML by including an Accept: text/html header in the request (as happens if the API is accessed directly from a browser) then results are returned in human-friendly HTML.

Successful responses have HTTP status codes of 200 OK. Other status codes (at least 400 Bad Request, 401 Authorization Required, and 404 Not Found) indicate an error. Most errors include an application/json body containing further information. Some errors, in particular any that generate bogus URLs, generate generic HTML 404 Not found pages with Content-Type: text/html.

Individual output formats are not documented, but should be self-explanatory. Some API calls that return lists of data items will return 200 OK responses with empty lists, rather than 404 Not found, if called with a valid request for which there happens to be no data available (e.g because of the chosen date range).