API Documentation

Formats and encoding

The API only supports JSON for data serialisation and all requests and responses should be UTF-8 encoded.

Making a request

All API calls are made against the API root: https://api.crowd.fm/v1/ (SSL only). Append the resource you require to the end of this URL.

Authentication

API V1 uses key-based authentication. crowd.fm users must first enable API access to obtain their API key. This can be done on the API access page.

The API key can be specified directly in requests as a URL parameter, for example:

curl https://api.crowd.fm/v1/events.json?api_key=1:1c52de06e74fc

Alternatively, it can be specified using the X-CROWDFM-API-KEY request header:

curl -H "X-CROWDFM-API-KEY: 1:1c52de06e74fc" \
https://api.crowd.fm/v1/events.json

Identifying your app

You should also specify a User-Agent header with the name and URL of your application so we can get in touch with you should we need to. For example:

User-Agent: BandApp (http://bandapp.com)

Rate limiting & fair use

All API requests are monitored, and whilst we do not have explicit limits on the number of requests you can make, we do ask that you refrain from making excessive or unnecessary requests, and that you make full use of the caching headers we return. We reserve the right to rate-limit or block requests from any IP address making excessive requests.

Caching

Most request responses will generally include an ETag or Last-Modified header, so for the benefit of our server load and the speed of your application, please make use of them. When you first make a request for a given resource, store the value and then submit them back to us on subsequent requests as If-None-Match and If-Modified-Since headers. If the resource hasn’t changed, you will get a 304 NOT Modified response back, which saves you the time and bandwidth of requesting and processing a payload you will have already received.

Resources

Events

GET /events.json will return all the accounts forthcoming, published events i.e. no unpublished or cancelled events will be included, neither will events from the past.

Example response payload:

[
 {
  "id":1566,
  "name": "Mr. Scruff in Edinburgh",
  "description": "Another quality session in Potterrow...",
  "price": "\u00a312.50 advance, \u00a315 door",
  "link": "nhttp://www.mrscruff.com",
  "event_type": "Club night",
  "created_at": "2012-08-01T23:13:08+01:00",
  "start_date_and_time": "2012-09-27T22:00:00+01:00",
  "end_date_and_time": "2012-09-28T03:00:00+01:00",
  "state": "published",
  "image_url": "/system/event/image/000/001/566/large_mr-scruff-in-edinburgh.jpg",
  "thumbnail_url": "/system/event/image/000/001/566/thumb_mr-scruff-in-edinburgh.jpg",
  "listings": [
    {
     "id":6134,
     "site_name": "soundcloud",
     "url": "http://soundcloud.com/mr-scruff"
    },{
     "id":6133,
     "site_name": "songkick",
     "url": "http://www.songkick.com/concerts/13584819"
    },{
     "id":6132,
     "site_name": "lastfm",
     "url": "http://www.last.fm/event/3350934"
    },{
     "id":6130,
     "site_name": "eventful",
     "url": "http://eventful.com/events/E0-001-050047782-6"
    }
  ],
  "venue": {
   "id": 1034703023,
   "name": "Potterrow",
   "address_line_1": "Bristo Square",
   "address_line_2": "",
   "city": "Edinburgh",
   "postcode": "EH8 9AL",
   "country_code": "GB"
  }
 }
]

Contact

If you have any questions or suggestions for improvements, please contact us at [email protected]. We’d also love to hear from you if you’ve used the API for something novel or interesting.