Documentation

Overview

The Seatwave Discovery API allows partners to discover events and the tickets listed for those events:

Full details of the API methods can be found here. Below is more general information on the API implementation.

Service End Points or Entry Points

The API can be accessed via 2 different service end-points.

  • Web based REST API – HTTP GETs and POSTs returning either JSON or XML
  • SOAP based web service

This online documentation concentrates on the REST API but if you are interested in the SOAP web services, WSDL definitions can be found at:

http://api-sandbox.seatwave.com/v2/discovery?wsdl
http://api-sandbox.seatwave.com/v2/purchase?wsdl

Many coding languages and frameworks, for example .NET and JAVA, offer tools to auto-generate proxies based on these defintions.

Response Formats: JSON, JSONP and XML

The services return either JSON or XML. This is controlled by the Accept header in the request

Accept: application/json
Accept: application/xml

If a JSONP response is required and additional callback parameter should be added to the querystring: for example

http://api-sandbox.seatwave.com/v2/discovery/genres?apikey=4739E4694D0E482A92C9D0B478D83934&callback=myfunction

Similarly the POST methods accept both JSON and XML formatted data. This is determined by the Content-Type header in the request

Content-Type: application/json
Content-Type: application/xml

Authentication

Seatwave API methods simply require a valid API key. The key is used to identify your requests and to track overall call usage.

The API key is passed using the apikey query string parameter, for example:

http://api-sandbox.seatwave.com/v2/discovery/genres?apikey=4739E4694D0E482A92C9D0B478D83934

Response

Each API method returns a standard response entity. They contain the following child entities:

  • Status: details the success or failure of the request
  • Domain entity: either a list or single entity
  • Paging: details the total entity count and page size and number. This is only returned with a list of domain entities
The response entity names are all suffixed 'Response', depending on the domain entity that they contain, for example EventsResponse.

Status

The Status entity, indicates the success or failure of a call via the Code and Message properties. Additional information may be included in the Details property.

JSON
{"Status":{ "Version":"2.0","TimeStampUtc": "\/Date(1328696521000+0000)\/","Code":0,"Message":"Success", "Details":""}}
XML
Version API version
TimeStampUtc UTC time stamp
Code Error code, 0 indicates success
Message Code description
Details Further details of the error

A full list of respose codes is given below:

Code Message
0Success
1Missing / Invalid Version Number
10Missing / Invalid API Key
11Missing / Invalid Time Stamp
12Missing / Invalid Token
20Authorisation Error
21Not authorised to access transaction
30Invalid Input
31Invalid Buyer Delivery Details
100Unable to hold tickets
101Unable to confirm tickets
1000API Error

Paging

Every method that returns a list of entities (as opposed to a single entity) accepts 2 optional paging parameters. These determines which page of results (from the full results set) are returned by the method call.

ParameterDefault
pgNumber1
pgSize50 (max page size = 1000)
JSON
{"PageNumber":1,"PageSize":50,"PageResultCount":50,"TotalResultCount":116,"TotalPageCount":3}
XML

An example of the use of the paging paramters is given below:

http://api-sandbox.seatwave.com/v2/discovery/categories?apikey=4739E4694D0E482A92C9D0B478D83934&pgsize=10&pgnumber=2

Site Parameter

All the calls in the discovery API accept a SiteID parameter. This parameter controls the language and currency of the data returned in the response. The site options are shown below. If no valid site ID is supplied, the default site associated with the API key is used.

Site ID Name Language Currency
1 Seatwave UK English GBP
2 Seatwave Germany German EUR
3 Seatwave Netherlands Dutch EUR
4 Seatwave Spain Spanish EUR
5 Seatwave Italy Italian EUR
6 Seatwave Sweden Swedish SEK
7 Seatwave Fance French EUR
8 Seatwave Austria German EUR
10 Seatwave Switzerland German EUR
11 Seatwave Ireland English EUR
12 Seatwave US English USD
14 Seatwave Canada English CAD
16 Seatwave South Africa English ZAR
17 Seatwave Finland Finnish EUR

Examples of the use of the site parameter are given below:

http://api-sandbox.seatwave.com/v2/discovery/events?apikey=4739E4694D0E482A92C9D0B478D83934&siteid=1&what=music&where=london

http://api-sandbox.seatwave.com/v2/discovery/events?apikey=4739E4694D0E482A92C9D0B478D83934&siteid=12&what=music&where=london

Search Filter Parameters

The majority of the discovery API calls that return, Event Groups, Events and Venues accept a set of optional filter parameters. These enable you to refine the results returned by the call.

Name Description Example
what Artist, performer, team, show, category or genre name , part of name, alternate name Rock
where Country, town or venue name, part of name, alternate name or UK post code London
whenFrom Start date [yyyy-mm-dd] 2012-02-15
whenTo End date [yyyy-mm-dd] 2012-04-30
maxPrice Maximum price (in Site currency) 100
eventsWithoutTix set to true to return events without tickets true

An example of the use of these parameters is given below:

http://api-sandbox.seatwave.com/v2/discovery/events?apikey=4739E4694D0E482A92C9D0B478D83934&siteid=1&what=music&where=london&whenfrom=2012-02-14&whenfrom=2012-05-31&maxprice=100