Backstage Idea Store use our stuff to build your stuff....

Name:

Press Association Going out API (events database)

Licence: Strictly for Non-Commercial Use under the Backstage Licence. Offered to Backstage with permission of Press Association.
Description: Events in and around the UK
Status: Stable
Type: XML/JSON REST API

Introduction

The objective of this API is to allow the A&E database to be queried by remote applications, an external web site for example. This happens over http using XML

Before we get any further, it is of the utmost importance that you understand the relationships between the key components, which make up
an event. An event is merely a relationship between a title and a venue. Each event has unique occurrences.

For the purpose of this API, an event is a group of occurrences (dates and times) for a title (film/play/gig etc.) at a
venue (theatre/cinema etc.)

Figure.1

Demonstrating (amongst other things) that Shrek VI is being shown at two cinemas and Bristol Cinema has two films showing.

Figure.2

An example of a musical fitting into the model.

Figure.3

The Most simple event relationship possible, a one-off event.

Categories

A title often belongs to multiple categories (Figure.4). A group is simply a group of categories.

Figure.4

The seven methods of the API

1. Group

Groups are simply groups of categories. There are no parameters.

http://api.welcomebackstage.com/group/

2. Categories

Title categories. A Title can belong to multiple categories.

http://api.welcomebackstage.com/category/

Parameters

• bitmask
  • Not required
  • Allows comma seperated values
  • Example: http://api.welcomebackstage.com/category/bitmask=91211
• groupId
  • Not required
  • Example: http://api.welcomebackstage.com/category/groupId=1

3. Rank

Top 10 titles. There are no parameters.

http://api.welcomebackstage.com/rank/

4. Search

Paginated search results pertaining to events

http://api.welcomebackstage.com/search/

Parameters

• page
  • Example: http://api.welcomebackstage.com/search/page=2
• postcode
  • Example: http://api.welcomebackstage.com/search/postcode=n14aa
• location
  • Also accepts a comma separated pair of latitude and longitude values
  • Example: http://api.welcomebackstage.com/search/location=leeds
  • Example: http://api.welcomebackstage.com/search/location=53.79963,-1.54882
• distance
  • Units are miles
  • Not required
  • Meaningless without a location or postcode
  • Default = 10
  • Minimum value = 1
  • Maximum value = 100
  • Example: http://api.welcomebackstage.com/search/location=London&distance=30
• titleName
  • Not required
  • Minimum length = 3 characters
  • Maximum length = 25 characters
  • Example: http://api.welcomebackstage.com/search/titleName=eye
• venueName
  • Not required
  • Minimum length = 3
  • Maximum length = 25
  • Example: http://api.welcomebackstage.com/search/venueName=park
• venueId
  • Not required
  • Example: http://api.welcomebackstage.com/search/venueId=abipar
• date
  • Format dd/mm/yyyy or yyyy-mm-dd
  • Not required
  • Defaults to today's date
  • Example: http://api.welcomebackstage.com/search/date=2008-12-29
  • Example: http://api.welcomebackstage.com/search/date=29/01/2008
• days
  • Not required
  • Default = 30
  • Minimum Value = 1
  • Maximum Value = 365
  • Example: http://api.welcomebackstage.com/search/days=60
  • Example: http://api.welcomebackstage.com/search/date=2008-12-29&days=60
• bitmask
  • Not required
  • Allows comma separated values
  • Example: http://api.welcomebackstage.com/search/bitmask=255
  • Example: http://api.welcomebackstage.com/search/bitmask=2048,255
• categoryId
  • Not required
  • Allows comma separated values
  • Example: http://api.welcomebackstage.com/search/categoryId=14
  • Example: http://api.welcomebackstage.com/search/categoryId=14,15,19,16
• groupId
  • Not required
  • Example: http://api.welcomebackstage.com/search/groupId=1
• groupName
  • Not required
  • Example: http://api.welcomebackstage.com/search/groupName=Cinema

5. Event

Event dates and times.

Parameters

• eventId
  • Required
  • Example: http://api.welcomebackstage.com/event/eventId=4079681
• date
  • Not required
  • Default = today's date
  • Example: http://api.welcomebackstage.com/event/eventId=4079681&date=2008-04-15
• days
  • Not required
  • Integer
  • Default Value = 30
  • Minimum Value = 1
  • Maximum Value = 365
  • Example: http://api.welcomebackstage.com/event/eventId=4079681&date=2008-04-15&da...

6. Title

Title information. Such as name and description etc.

Parameters

• titleId
  • Required
  • Example: http://api.welcomebackstage.com/title/titleId=abipar6

7. Venue

Venue information. Such as name, address postcode etc.

Parameters

• venueId
  • Example: http://api.welcomebackstage.com/venue/venueId=bilmar
• postcode
  • Example: http://api.welcomebackstage.com/venue/postcode=n14aa
• location
  • Also accepts a comma separated pair of latitude and longitude values
  • Example: http://api.welcomebackstage.com/venue/location=leeds
  • Example: http://api.welcomebackstage.com/venue/location=53.79963,-1.54882
• distance
  • Units are miles
  • Not required
  • Meaningless without a location or postcode
  • Default = 10
  • Minimum value = 1
  • Maximum value = 100
  • Example: http://api.welcomebackstage.com/venue/location=London&distance=30

Formats

Two formats of output are available to users:

• XML
• JSON

By default XML is output. To specify which format you would prefer, append format=json or format=xml to the end of a request.

For example: http://api.welcomebackstage.com/search/postcode=n14aa&format=json

Any subsequent URLs generated by the API will append the format parameter for you.

Bitmasks

Each category and its subcategories have 2 unique identifiers, categoryId and bitmask.

By adding the bitmasks of two or more categories (or subcategories) together you can search for events in those categories.

For example:

• the Film subcategory Action has a bitmask of 1
• the Music subcategory Rock has a bitmask of 16384
• and the Leisure subcategory Days Out has a bitmask of 4194304

To search for Action and Rock events you would pass the API the bitmask 16385 (16384 + 1)

Example: http://api.welcomebackstage.com/search/bitmask=16385

To search for Rock and Days Out events you would pass the API the bitmask 4210688 (16384 + 4194304)

Example: http://api.welcomebackstage.com/search/bitmask=4210688

To search for all 3 you would pass the API the bitmask 4210689 (1+ 16384 + 4194304)

Example: http://api.welcomebackstage.com/search/bitmask=4210689

API Overview