Documentation

Basics

The API is located at the following address: 

http://api.gigjunkie.net/v1.0/

An example of a request to the API including the consumer key to authentiate your request, would look something like: 

http://api.gigjunkie.net/v1.0/events?q=brixton&consumerKey=yourkey

All calls at the moment must be HTTP GETs. We will support additional verbs in the near future.

Paging and Results

It's possible that your query might generate many results. We provide the result count in the returned resulset as an attribute.

API calls support the following paging parameters:

name

type

use

description

 
pageIndex

int

optional

Page number of the result set, using a zero-based index. If not supplied, defaults to 0

 
pageSize

int

optional

Number of items to be returned per page. If not supplied, defaults to 10. Maximum page size is 500

Geolocation

By default we return results for the whole of the world. If you don't already have the location of your users, you can use good services such as the Google Maps API or Microsoft's Bing Maps to help you.

http://api.gigjunkie.net/v1.0/events?q=u2&latitude=51.5075&longitude=-0.1136&distance=15

You can provide results filtered on a location using the parameters below:

name

type

use

description

 
latitude

string

optional

The latitude i.e. 51.5075

 
longitude

string

optional

The longitude i.e. -0.1136

 
distance

int

optional

Distance in kilometres. If omitted, will default to show all events.

Genre

It's possible to filter the result set by genre. This is a very high level concept of genre (which should avoid too much subjective argument!). The genre filter could be useful on a website that only targeted jazz musicians for example. 

http://api.gigjunkie.net/v1.0/events?q=brixton&genre=rock-pop

name

type

use

description

 
genre

string

optional

Filter the resultset by genre. The possible genres are:

  • Rock/Pop: 
    rock-pop
  • Country/Folk: 
    country-folk
  • Rap and Hip-Hop: 
    rap-hip-hop
  • Jazz/Blues: 
    jazz-blues
  • World: 
    world
  • Alternative and Indie: 
    alternative-indie
  • Hard Rock/Metal: 
    hard-rock-metal
  • Clubs and Dance: 
    clubs-dance
  • R&B/Urban Soul: 
    r-and-b-urban-soul
  • Tribute Bands: 
    tribute-bands

Response Format

You can choose whether you want the response from the API to be in XML, JSON or JSONP. XML is the default format. 

http://api.gigjunkie.net/v1.0/events?q=birmingham&format=json

name

type

use

description

 
format

string

optional

Values can be json or xml

 
callback

string

optional

When used in conjunction with format=json , the response will be padded by a call to the method specified by the callback parameter. This is known as JSONP, and is used for managing client-side calls to the API. For more information, see Wikipedia, and for secure client-side Ajax, you might want to consider using flHXR.

Images

We do output images for artists, and these images have been provided by last.fm. If you wish to use these images, you will need to get an agreement from last.fm. We provide these images for your convenience.

Ticket Vendor Logos

If you want to display ticket vendor logos against each ticket, you can refence our CDN at http://affiliateassets.gigjunkie.net. You can download these images to your own site or application, but be mindful that this list is constantly growing, so keep an eye on our Twitter feed for updates. The image name is the provider name in lower case with spaces removed. i.e.

http://affiliateassets.gigjunkie.net/img/vendors/[providername].png
http://affiliateassets.gigjunkie.net/img/vendors/ticketmaster.png

Events

Searching

When requesting a list of events from the API, you can filter the results based on a search term. The search term will search our database for artists, events, venues and towns. It is both powerful and simple to use.  A search term would typically look like:

http://api.gigjunkie.net/v1.0/events?q=liverpool&consumerKey=yourkey
http://api.gigjunkie.net/v1.0/events?q=lady%20gaga%20Glasgow&consumerKey=yourkey

name

type

use

description

 
q

string

optional

Search term to query GigJunkie database and can include a mixture of entity names to search for i.e.
London
Prodigy London
Lily Allen 02

If querying for multiple terms at once, separate the terms with "|", i.e.
Kings of Leon|Lady Gaga|Prodigy 

queryType

int

optional

Type of match to use, e.g. "Exact Match Artist" tells the API to treat the query term (or terms separated by "|") all as Artist names, and to match exactly rather than allowing for spelling mistakes. Default is Best Match Search. Valid values are:

  • Best Match Search: 
    0
  • Exact Match Search: 
    1
  • Best Match Artist: 
    2
  • Exact Match Artist: 
    3

Date Ranges

It's possible to filter the result set by date range. 

http://api.gigjunkie.net/v1.0/events?q=brixton&startDate=2009-12-01
http://api.gigjunkie.net/v1.0/events?q=brixton&startDate=2009-12-01&endDate=2010-01-01

name

type

use

description

 
startDate

string

optional

The date should be in ISO format i.e. 2009-08-28

 
endDate

string

optional

The date should be in ISO format i.e. 2009-12-25

Additional Parameters

http://api.gigjunkie.net/v1.0/events?q=birmingham&hideUserAdded=true
http://api.gigjunkie.net/v1.0/events?q=birmingham&showOnlyRevenue=true
http://api.gigjunkie.net/v1.0/events?q=birmingham&sortBy=distance
http://api.gigjunkie.net/v1.0/events?q=lily&includeCancelled=true

name

type

use

description

 
hideUserAdded

boolean

optional

Hides user added events. However, if the likes of TicketMaster for example have told us of tickets for this event, then we will output the event. This flag might be of use to those people who are concerned about the quality of event data added by users, though we generally find it to be excellent.

 
showOnlyRevenue

boolean

optional

If you have an affiliate account with GigJunkie and you only want to get the data of events and tickets for those which you can earn a revenue, set this flag to true.

 
sortBy

string

optional

By default, events are sorted by date, but if you wish, you can sort your results by distance.

 
includeCancelled

bool

optional

By default, cancelled events are not returned by the API. If you are persisting our data in a cache or local storage, you might want to double check that the event has not been cancelled by including cancelled events, and then checking the iscancelled status on each event.

Hot Events

You can query the GigJunkie API to retrieve "hot events". We determine how hot an event is by analysing lots of data, and we also weight events based on activities in the media. For example, if we know that an artist is appearing in a popular TV show, that artist's events will be hotter during and after this appearance.

The data returned from this call could be used to great effect on your ticket homepage. What is hot is very much location specific, so you do need to call this end point with the geo parameters. 

http://api.gigjunkie.net/v1.0/hot-events?latitude=51.5075&longitude=-0.1136&distance=50

You can also use the parameters mentioned under Basics to filter by genre, and/or to control paging:

http://api.gigjunkie.net/v1.0/hot-events?pageIndex=3&pageSize=20&genre=rock-pop&latitude=51.5075&longitude=-0.1136&distance=20

Date Ranges

It's possible to filter the result set by date range. 

http://api.gigjunkie.net/v1.0/hot-events?startDate=2009-12-01&latitude=51.5075&longitude=-0.1136&distance=50
http://api.gigjunkie.net/v1.0/hot-events?startDate=2009-12-01&endDate=2010-01-01&latitude=51.5075&longitude=-0.1136&distance=50

name

type

use

description

 
startDate

string

optional

The date should be in ISO format i.e. 2009-08-28

 
endDate

string

optional

The date should be in ISO format i.e. 2009-12-25

Additional Parameters

http://api.gigjunkie.net/v1.0/hot-events?hideUserAdded=true&latitude=51.5075&longitude=-0.1136&distance=50
http://api.gigjunkie.net/v1.0/hot-events?showOnlyRevenue=true&latitude=51.5075&longitude=-0.1136&distance=50

name

type

use

description

 
hideUserAdded

boolean

optional

Hides user added events. However, if the likes of TicketMaster or See Tickets for example have told us of tickets for this event, then we will output the event. This flag might be of use to those people who are concerned about the quality of event data added by users, though we generally find it to be excellent.

 
showOnlyRevenue

boolean

optional

If you have an affiliate account with GigJunkie and you only want to get the data of events and tickets for those which you can earn a revenue, set this flag to true.

Hot Artists

Very similar to hot events above, if you would like to present your users with a page of popular artists with their images, then call this end point. Again, what is hot is very much location specific, so you do need to call this end point with the geo parameters.

http://api.gigjunkie.net/v1.0/hot-artists?latitude=51.5075&longitude=-0.1136&distance=200

Additional Parameters

http://api.gigjunkie.net/v1.0/hot-artists?hideUserAdded=true&latitude=51.5075&longitude=-0.1136&distance=50

name

type

use

description

 
hideUserAdded

boolean

optional

Hides user added artists. However, if for example the likes of Ticketmaster have told us of tickets for this artist, then we will output the artist. This flag might be of use to those people who are concerned about the quality of artist data added by GigJunkie users.

Release Notes

In this release, we:

  • made the API public after extensive beta testing with some major partners