minimize header



Bring Out Yer Data!

TicketStumbler's event database features thousands of sports, concert and theater events throughout the U.S. and parts of Canada! The API includes basic event information (name, date, venue, etc.) as well as more useful metadata such as venue latitude and longitude. Additionally, our ticket database gives you access to the millions of ticket listings we link to on TicketStumbler.com. This page describes the technical details of the API and does not cover information regarding third-party partnerships and so forth. If you want to work with us, we want to hear from you, though. Please contact us to discuss the topic further.

The design goal for this API was to create something extremely simple and straight-forward. There are no complicated hoops to jump through to use it and it is based on RESTful requests. Given nothing but this document and a terminal prompt, your grandmother could access our data. If she knows what those various terms mean.

Becoming an API Consumer

All you need to do to become a consumer is register for a token.

All you need to do is append the token parameter along with your supplied token's value to API requests you make. For instance: http://ticketstumbler.com/api/1.0/rest/event/today.json?token=asd123. Easy like Sunday morning!

We have recently changed the process for consumer registration to make it easier on you! You no longer need a TicketStumbler.com account (which have been deprecated in general). This means, however, that if you lose your token, you'll need to email api[at]ticketstumbler.com directly to retrieve it.

Request Path

Make requests to http://ticketstumbler.com/api/1.0/rest/

Response Formats

All API methods are available in either JSON or XML. YAML is also technically available, though there are enough compatability issues with the object representer that we do not officially support it. To select your desired format, simply change the extension of the method you are calling.

Feedback

Since this API is a new service we are very open to suggestions for improvement. We strongly encourage you to tell us how we can make the API better and more useful for you; we already have access to all our data just how we like it! To discuss API issues, feel free to directly email api[at]ticketstumbler.com.

API Namespaces

Events

  1. event/by_id.{ json|xml } Documentation »

    allowed methods: get

    Retrieve an event by ID.

    This method returns event data which matches the supplied id attribute.

    Required parameters:
    id (Integer):

    The event id.

  2. event/search.{ json|xml } Documentation »

    allowed methods: get
    Search for events using a number of optional parameters.
    Optional parameters:
    query (UTF-8 String):

    A query which supports all the functionality of our site search. See: http://ticketstumbler.com/help/search/

    name (UTF-8 String):

    A simple, partial event name match. The advantage of this over the query parameter is that it may be combined with ip or lat/lon.

    category_id (UTF-8 String):

    An optional Category ID which will be used to filter results. Events which fall in the supplied category or one below it will be included. NEW! You can now specify multiple categories by separating them with commas, i.e. 120,14,3

    venue_id (Integer):

    An optional Venue ID which will be used to filter results. Events which happen at the supplied venue will be included.

    date_end (UTF-8 String):

    End of the date range, e.g. 2008-11-12

    date_start (UTF-8 String):

    Start of the date range, e.g. 2008-11-1

    Default: today

    radius (Integer):

    A search radius, specified in miles.

    Default: 10

    lon (Floating point number):

    A longitude; same purpose as ip; requires lat.

    lat (Floating point number):

    A latitude; same purpose as ip; requires lon.

    ip (UTF-8 String):

    An IP address to use to filter events by proximity to a given area. Supply either ip or lat/ lon; if you supply both, lat/lon will be used. Note that not all IP addresses will provide a location, though most do.

    limit (Integer):

    The maximum number of records returned.

    Default: 50

    Maximum value: 100

    Minimum value: 1

    offset (Integer):

    Skip the first X records. Used in conjunction with limit to create paginated requests.

    Default: 0

    Minimum value: 0

  3. event/this_week.{ json|xml } Documentation »

    allowed methods: get
    A convenience method which returns optionally-local events happening this week.
    Optional parameters:
    radius (Integer):

    A search radius, specified in miles.

    Default: 10

    lon (Floating point number):

    A longitude; same purpose as ip; requires lat.

    lat (Floating point number):

    A latitude; same purpose as ip; requires lon.

    ip (UTF-8 String):

    An IP address to use to filter events by proximity to a given area. Supply either ip or lat/ lon; if you supply both, lat/lon will be used. Note that not all IP addresses will provide a location, though most do.

    limit (Integer):

    The maximum number of records returned.

    Default: 50

    Maximum value: 100

    Minimum value: 1

    offset (Integer):

    Skip the first X records. Used in conjunction with limit to create paginated requests.

    Default: 0

    Minimum value: 0

  4. event/today.{ json|xml } Documentation »

    allowed methods: get
    A convenience method which returns optionally-local events happening today.
    Optional parameters:
    radius (Integer):

    A search radius, specified in miles.

    Default: 10

    lon (Floating point number):

    A longitude; same purpose as ip; requires lat.

    lat (Floating point number):

    A latitude; same purpose as ip; requires lon.

    ip (UTF-8 String):

    An IP address to use to filter events by proximity to a given area. Supply either ip or lat/ lon; if you supply both, lat/lon will be used. Note that not all IP addresses will provide a location, though most do.

    limit (Integer):

    The maximum number of records returned.

    Default: 50

    Maximum value: 100

    Minimum value: 1

    offset (Integer):

    Skip the first X records. Used in conjunction with limit to create paginated requests.

    Default: 0

    Minimum value: 0

Event Categories

  1. category/by_id.{ json|xml } Documentation »

    allowed methods: get

    Retrieve a category by ID.

    This method returns category data which matches the supplied id attribute.

    Required parameters:
    id (Integer):

    The category id.

  2. category/search.{ json|xml } Documentation »

    allowed methods: get

    Search for categories by name. Supports partial matches.

    This method returns category data which matches the supplied name attribute. This is useful mostly for finding events by category as a category_id must be provided.

    Required parameters:
    name (UTF-8 String):

    Name to search for.

    Optional parameters:
    limit (Integer):

    The maximum number of records returned.

    Default: 50

    Maximum value: 100

    Minimum value: 1

    offset (Integer):

    Skip the first X records. Used in conjunction with limit to create paginated requests.

    Default: 0

    Minimum value: 0

Event Venues

  1. venue/search.{ json|xml } Documentation »

    allowed methods: get

    Search for venues by name, city, and state. Supports partial matches.

    This method returns venue data which matches the supplied parameters. This is useful mostly for finding events by venue as a venue_id is required for filtering. This method also returns more detailed information about a venue than event/search does. These responses include lat/lon, address, timezone etc. (where available). Although the extra metadata is not complete for all venues, we are constantly adding to it.

    Optional parameters:
    id (Integer):

    A venue_id as returned by event namespace responses.

    name (UTF-8 String):

    A Venue name to filter by.

    city (UTF-8 String):

    A city name to filter by.

    state (UTF-8 String):

    A 2-letter state code to filter by. Keep in mind that full state names are not currently supported. Additionally, for venues outside the United States, “state” means provincial code, e.g. “ON” is the “state” in “Toronto, ON”.

    limit (Integer):

    The maximum number of records returned.

    Default: 50

    Maximum value: 100

    Minimum value: 1

    offset (Integer):

    Skip the first X records. Used in conjunction with limit to create paginated requests.

    Default: 0

    Minimum value: 0

Ticket Listings

Ticket listing data is updated on-demand and only cached for 10 minutes. The returned listings will include a stale attribute which will indicate if the listings are outdated. Stale listings are automatically updated after the latest request for them, and in many cases will include additional results.

The block parameter is provided to circumvent this issue, however. Use it to block the request until fresh results are available (1-10 seconds).

  1. tickets/by_event.{ json|xml } Documentation »

    allowed methods: get
    Get ticket listings by event.
    Required parameters:
    event_id (Integer):

    The Event ID as supplied in responses from the methods in the Event namespace (key: id)

    Optional parameters:
    order_by (UTF-8 String):

    Field to order the results by. It may be prepended with a - sign to denote descending ordering. One of: price, section, row, provider

    Default: price

    limit (Integer):

    The maximum number of records returned.

    Default: 500

    Maximum value: 1500

    Minimum value: 1

    offset (Integer):

    Skip the first X records. Used in conjunction with limit to create paginated requests.

    Default: 0

    Minimum value: 0

    provider_id (UTF-8 String):

    Limit results to listings from the provided supplier (via provider_id value as returned by event namespace responses. Separate by commas to use multiple, i.e. 1,2,3

    min_price (Integer):

    Minimum price to meet for a listing to be included.

    max_price (Integer):

    Maximum price to meet for a listing to be included.

    block (Boolean):

    If set to 1, the request will block until such a time that ticket listings have been updated. Do NOT use this parameter if you need the request to return immediately!

    Default: 0

  2. tickets/schedule_update.{ json|xml } Documentation »

    allowed methods: post
    A special method which schedules a ticket update for an event. This serves to create a guarantee that listings for the supplied event will never be 'stale’. This is not a public method and is authorized on a case-by-case basis at this time. If you have a use for it, please contact us.
    Required parameters:
    interval (Integer):

    An interval at which to ensure listings are updated, in minutes.

    event_id (Integer):

    The Event ID as supplied in responses from the methods in the Event namespace (key: id)

Site contents ©2008-2009 TicketStumbler Inc., unless otherwise noted.

Terms of Service | Privacy Policy

Location successfully updated!
An error occurred and we couldn't alter your location. Sorry!

Enter your email address and we'll alert you when tickets are available!

Alert created successfully! You will be sent an email when tickets are available.