This documentation applies to the API version 1.

Introduction

The Gatekrash API provides programmatic access to the data contained on gatekrash.com. You may use it on the understanding that it is in perpetual beta, may become unavailable with no warning (temporarily or permanently), may not produce entirely accurate results, and you provide a link back to Gatekrash (e.g. 'powered by Gatekrash').

There is no rate limiting on the API at the moment. Nor is authentication required (seems a waste of time for a site like this).

Request URL

Requests are made using a RESTful URL, including the appropriate parameters. The server will process these requests and return results as JSON.

To make a request, all you need to do is use the following URL and include the appropriate parameters.

http://gatekrash.com/api/v1

Type is the only parameter required in all requests, with other parameters being either optional or required depending on the type (see parameters). To protect against future changes to the API breaking anything that uses them, versioning has been included (v1).

Parameters

type

Required, for all requests

Accepted values: soon, now, popular, place, venue, event, search, placelookup, geolocate

No default value

Defines the type of request to be performed. As you can see from the list of accepted values above, they roughly correspond with the various pages on Gatekrash.

page

Optional

Accepted values: numerical value of 1 or more

Default: 0

Defines which page of results are being requested.

number

Optional

Accepted values: numerical value of between 1 and 100

Default: 30

Defines the number of results per page.

scope

Required, for soon, now, search only

Accepted values: local, nearby, national

Default: national

Defines the scope of the results requested. 'Local' will provide listings only within a certain place, 'nearby' will provide listings within a certain place and nearby places, and 'national' will return all listings if available.

query

Required, for search and placelookup only

Accepted values: any string (query is sanitised when processed)

No default value

Defines the query string of a search or placelookup.

place

Required, for place only. Also required if scope is set to local or nearby

Accepted values: a Gatekrash place ID, e.g. 16647 for London

No default value

Defines the place of the request.

venue

Required, for venue only

Accepted values: a Gatekrash venue ID, e.g. 114 for Fabric

No default value

Defines the venue of the request.

event

Required, for event only

Accepted values: a Gatekrash event ID

No default value

Defines the event of the request.

start

Optional, for search, place, venue only

Accepted values: a numeric datetime stamp in the format of YYYYMMDDHHMMSS, no spaces

Default: current date and time

Defines minimum start date and time for events in the request. Usage depends on the function requested. This parameter may not affect results in some cases.

end

Optional, for search, place, venue only

Accepted values: a numeric datetime stamp in the format of YYYYMMDDHHMMSS, no spaces

Default: current date and time

Defines minimum end date and time for events in the request. Usage depends on the function requested. This parameter may not affect results in some cases.

split

Optional, for soon, now, venue, place, venue only

Accepted values: true, false

Default: true

Specified whether or not to split the response into 'more human' readable lists (grouping events into similar start times or end times, e.g. starting in 5 minutes, starting in 3 hours etc.)

callback

Optional, for all requests

Accepted values: alphanumeric string

No default value

If specified, this parameter will cause the return JSON to be formatted in the form of a javascript callback function.

alsooccurring

Optional, for event requests only

Accepted values: true or empty

No default value

If specified, this parameter will cause the request to list all future occurrances of a specific event based on the event's title.

lat

Required, for geolocate requests only

Accepted values: latitude or empty

No default value

A valid latitude value (within the UK) to determine the closest place to the user's current location. Please note, if the latitude/longitude value is outside the UK, this request will return a default value of London.

lon

Required, for geolocate requests only

Accepted values: longitude or empty

No default value

A valid longitude value (within the UK) to determine the closest place to the user's current location. Please note, if the latitude/longitude value is outside the UK, this request will return a default value of London.

Response Format

Responses are returned in JSON format. Below is an example request, in this case requesting events happening soon, near London, and split into human readable groups:

http://beta.gatekrash.com/api/v1?t=soon&s=nearby&place=16647&p=1&n=5&split=false

This would result in a response which looks like this:

[
   {
      "id": "322",
      "title": "Fluid Nation",
      "type": null,
      "start": "2011-02-03 19:00:00",
      "end": "2011-02-04 00:00:00",
      "venue": {
         "id": "122",
         "name": "Big Chill House"
      },
      "place": {
         "id": "16647",
         "name": "London"
      },
      "source_count": "1",
      "performers": ""
   },
   {
      "id": "335",
      "title": "Quirky",
      "type": null,
      "start": "2011-02-03 19:00:00",
      "end": "2011-02-04 02:00:00",
      "venue": {
         "id": "209",
         "name": "Inigo Bar"
      },
      "place": {
         "id": "16647",
         "name": "London"
      },
      "source_count": "1",
      "performers": ""
   },
   {
      "id": "521",
      "title": "UBDJ Presents",
      "type": null,
      "start": "2011-02-03 19:00:00",
      "end": "2011-02-03 23:00:00",
      "venue": {
         "id": "159",
         "name": "93 Feet East"
      },
      "place": {
         "id": "16647",
         "name": "London"
      },
      "source_count": "1",
      "performers": ""
   },
   {
      "id": "557",
      "title": "Escape",
      "type": null,
      "start": "2011-02-03 19:00:00",
      "end": "2011-02-04 01:00:00",
      "venue": {
         "id": "257",
         "name": "Bar Soho"
      },
      "place": {
         "id": "16647",
         "name": "London"
      },
      "source_count": "1",
      "performers": ""
   },
   {
      "id": "691",
      "title": "Glamorous & Groovy",
      "type": null,
      "start": "2011-02-03 19:00:00",
      "end": "2011-02-04 02:00:00",
      "venue": {
         "id": "198",
         "name": "Tiger Tiger London"
      },
      "place": {
         "id": "16647",
         "name": "London"
      },
      "source_count": "1",
      "performers": ""
   }
]

Errors

Examples