-
Notifications
You must be signed in to change notification settings - Fork 0
Event API
jeffsb edited this page Feb 20, 2013
·
7 revisions
#Introduction
The ScoreBig API is a simple REST web service interface with lightweight JSON-formatted responses, providing you the capability to use many of the functions and data of ScoreBig's platform. This document outlines the API methods pertinent to event discovery. If you haven't already, you should go over the basics of the ScoreBig API by reading the ScoreBig API Introduction documentation.
Events are the atomic building blocks of ScoreBig. Events can be searched and filtered.
##Objects
###Object: Event
| Field | Type | Description | Value Constraints | Nullable |
|---|---|---|---|---|
| id | guid | ScoreBig's unique identifier for the event | no | |
| url | string | Your affiliate deep-link URL to the ScoreBig offer page for this event. | yes | |
| name | string | Event name | No | |
| local_date_time | datetime | The date and time of the event in the local timezone of the venue for the event. | string in the format M/d/YYYY H:MM:SS AM/PM
|
No |
| local_date_time_type | int | Determines the level of certainty for the LocalDateTime. | 1 = Known date time, 2 = Known date but time is TBD, 3 = Both time and date are TBD | No |
| time_zone | string | The timezone name for the event. | no | |
| venue_id | guid | Id of the venue for this event. | no | |
| venue | string | Name of the venue for this event. | no | |
| deal_rating | int | Determines the level of savings for this event. | 0 = Event is out of stock, 1 = Big savings, 2 = Bigger savings, 3 = Biggest savings | no |
| deal_rating_percentage | int | The overall percentage savings for this event. | Returned values are 10, 25, or 50 percent for Big, Bigger, and Biggest savings respectively | no |
| performer_Id | guid | The id of the primary performer for this event. | no | |
| performer | string | The name of the primary performer for this event. | no | |
| categories | array of Category objects | The list of categories for this event. Categories have an Id and Name property. | no | |
| is_on_sale | bool | Determines whether the event is on sale at ScoreBig. | no | |
| is_cancelled | bool | Determines whether the event has been cancelled. | no | |
| is_out_of_stock | bool | Determines if there are no more tickets available for this event. | no | |
| rescheduled_from_event_id | guid | The id of the cancelled event that resulted in this event. | yes | |
| rescheduled_to_event_id | guid | If this event is cancelled, this is the id for the rescheduled event. | yes | |
| secondary_performer_id | GUID | If this event is sports, it lists the opponent id | yes | |
| secondary_performer_name | string | If this event is sports, it lists the opponent name | yes | |
| metro_region | string | The general metro region of the event | no | |
| top_category | string | The top most primary category for the event | no | |
| lower_categories | array of strings | All lower level categories for the event | yes | |
| description | string | An event description | yes | |
| city | string | The name of the event city | no | |
| venue_address | string | The street address of the event's venue | no | |
| state | string | The name of the event state | no | |
| venue_latitude | string | The venue's latitude | yes | |
| venue_longitude | string | The venue's longitude | yes | |
| day_of_week | string | The day of week for the event | yes | |
| ticket_expiration | datetime | The date and time of the event's projected ticket expiration from ScoreBig inventory (UTC) | string in the format M/d/YYYY H:MM:SS AM/PM | yes |
| next_3_days | bool | True if the event falls within the next 3 calendar days | no | |
| next_7_days | bool | True if the event falls within the next 7 calendar days | no | |
| next_30_days | bool | True if the event falls within the next 30 calendar days | no | |
| this_weekend | bool | True if the event falls in the upcoming weekend | no | |
| star_ratings | array of StarRating objects | The list of star ratings currently available for sale on ScoreBig | yes |
###Object: StarRating
| Field | Type | Description | Value Constraints | Nullable |
|---|---|---|---|---|
| rating | int | The quality of the ticket | 0 = unrated, 1-6 = 1 through 6 stars, 7-11 = custom rating | no |
| deal_rating | int | The amount of savings | 0 = None, 1 = Hot, 2 = Hotter, 3 = Hottest | no |
| retail_price | decimal | The estimated box office price of the ticket including fees and shipping | no | |
| deal_rating_percentage | int | The average savings for this ticket | 0-100 | no |
##Methods
###Method: SearchEvents
######Description
Returns available events. Includes the ability to search by keywords and filter by a variety of fields.
######URI
/events
######HTTP Method
GET
######Returns
An array of Event objects. If your search yields no events, an empty array with be returned.
######Parameters
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
| query | string | Free form text for a general search (event, city, venue, performer, etc) | ||
| name | string | Free form event name | ||
| performer_name | string | Free form performer name | ||
| performer_id | guid (comma separated) | IDs of the performers to restrict the search to (both home & away games/events) | ||
| primary_performer_id | guid (comma separated) | IDs of the performers to restrict the search to (home games only) | ||
| secondary_performer_id | guid (comma separated | IDs of the performers to restrict the search to (away games only) | ||
| venue | string | Free form venue name | ||
| city | string | Free form cityname | ||
| city_id | string (comma separated | IDs of the metro regions to restrict the search to. Multiple metro region IDs should be separated by commas. | ||
| category | string | Free form metro category name | ||
| category_id | guid (comma separated) | IDs of the category to restrict the search to. Multiple category ids should be separated by commas. | ||
| start_date | date | Only include events after this date and time | ||
| end_date | date | Only include events up to this date and time | ||
| deal_rating | int (comma separated) | Restrict search to certain deal ratings | ||
| max_results | int | 200 | Maximum number of results to return. |
######Sample Request
GET http://developer.api.scorebig.com/1/events
To get all available events (could take up to 20 seconds to return)
######Sample Response
{
type: "EventResult",
count: 9,
results: [ //Array
{
"id":"2c2b435b-2835-4efd-b137-9fe80149dc24",
"url":"/san-francisco-giants-tickets/san-francisco-giants-vs-arizona-diamondbacks-9-27-2012?affiliateCode=ios-1&a=ios-1&isAffiliate=true&ref_tag=",
"name":"San Francisco Giants vs. Arizona Diamondbacks",
"local_date_time":"9/27/2012 12:45:00 PM",
"local_date_time_type":1,
"venue":"AT&T Park",
"deal_rating":2,
"deal_rating_percentage":25,
"primary_performer_id":"feb514a6-d745-4cb3-89e2-e54108f9c345",
"primary_performer":"San Francisco Giants",
"secondary_performer_id":"3fd5e155-3253-4182-b8ab-8e47aea3132a",
"secondary_performer":"Arizona Diamondbacks",
"is_onsale":true,
"is_canceled":false,
"is_outofstock":false,
"metro_region":"SF Bay",
"top_category":"Sports",
"lower_categories":[
"Baseball",
"MLB"
],
"description":"Even though Tim Lincecum has been very un-Lincecum-like thus far, Matt Cain and Madison Bumgarner have more than picked up the slack. With the best rotation in the game and Melky Cabrera lighting it up at the plate, the Giants are the team to beat in the NL West. Again.",
"city":"San Francisco",
"venue_address":"24 Willie Mays Plaza",
"state":"CA",
"venue_latitude":37.778644,
"venue_longitude":-122.38938,
"day_of_week":"Thursday",
"ticket_expiration":"9/25/2012 7:00:00 PM",
"next_3_days":false,
"next_7_days":false,
"next_30_days":true,
"this_weekend":false,
"star_ratings":[
{
"rating":2,
"deal_rating":2,
"retail_price":43.92,
"deal_rating_percentage":25
},
{
"rating":3,
"deal_rating":2,
"retail_price":60.32,
"deal_rating_percentage":25
},
{
"rating":4,
"deal_rating":2,
"retail_price":70.05,
"deal_rating_percentage":25
},
{
"rating":5,
"deal_rating":2,
"retail_price":115.09,
"deal_rating_percentage":25
}
]
}
//...And so forth the for other 8 results
]
}###Method: GetEvent
######Description
Returns a specific Event.
######URI
/events/:event_id
######HTTP Method
GET
######Returns
Event object.
######Parameters
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
| event_id | guid | Y | ScoreBig event ID | |
| verbose | bool | false | If true, includes detailed section manifest in results |
######Sample Request
GET http://developer.api.scorebig.com/1/events/a20c6aa0-de40-483e-bf61-a0f30129d180
GET http://developer.api.scorebig.com/1/events/a20c6aa0-de40-483e-bf61-a0f30129d180?verbose=true
######Sample Response (default)
{
"type":"Event",
"count":1,
"results":[
{
"id":"a20c6aa0-de40-483e-bf61-a0f30129d180",
"client_id":null,
"url":"/michigan-state-spartans-mens-ice-hockey-tickets/michigan-state-spartans-men-s-ice-hockey-vs-notre-dame-fighting-irish-men-s-ice-hockey-1-11-2013?affiliateCode=ios-1&a=ios-1&isAffiliate=true&ref_tag=aff.api&s=ios-1",
"name":"Michigan State Spartans Men's Ice Hockey vs. Notre Dame Fighting Irish Men's Ice Hockey",
"local_date_time":"1/11/2013 7:05:00 PM",
"local_date_time_type":1,
"time_zone":"America/Detroit",
"venue_id":"625c36fa-b7e2-4267-9756-9e2f00815473",
"venue":"Munn Ice Arena",
"deal_rating":3,
"deal_rating_percentage":50,
"performer_id":"d2ccba0d-1064-419b-b2b6-9e2f008c354e",
"performer":"Michigan State Spartans Men's Ice Hockey",
"categories":[
{
"id":"ef87b34e-b33a-41c1-ac2e-089d7dd58d21",
"name":"Sports"
},
{
"id":"10a508af-1e1e-46a3-bffb-d86cb33b2e4a",
"name":"Hockey"
},
{
"id":"9eea95a5-8412-4ccf-9e1c-e89672aaee57",
"name":"College Hockey"
}
],
"is_on_sale":true,
"is_canceled":false,
"is_out_of_stock":false,
"rescheduled_from_event_id":null,
"rescheduled_to_event_id":null,
"secondary_performer_id":"9d163758-19cd-43f8-8a88-9e330109f0f3",
"secondary_performer":"Notre Dame Fighting Irish Men's Ice Hockey",
"metro_region":"Detroit",
"top_category":"Sports",
"lower_categories":[
"Hockey",
"College Hockey"
],
"description":"With the NHL locked out, the spotlight shifts to the college game and you wanna know what’s awesome? Big-time, high-stakes college hockey, up close and personal. Get out and see the Michigan State Spartans as they take on the best teams in the nation.",
"city":"East Lansing",
"venue_address":"1407 South Harrison Road",
"state":"MI",
"venue_latitude":42.7182049,
"venue_longitude":-84.4936633,
"day_of_week":"Friday",
"ticket_expiration":"1/11/2013 12:05:00 AM",
"next_3_days":false,
"next_7_days":false,
"next_30_days":true,
"this_weekend":false,
"star_ratings":[
{
"rating":3,
"deal_rating":3,
"retail_price":27.24,
"deal_rating_percentage":50
},
{
"rating":7,
"deal_rating":3,
"retail_price":27.24,
"deal_rating_percentage":50
},
{
"rating":8,
"deal_rating":3,
"retail_price":27.24,
"deal_rating_percentage":50
}
]
}
]
}######Sample Response (verbose)
{
"type":"Event",
"count":1,
"results":[
{
"sections":[
{
"rating":3,
"ratingname":"Three Star",
"section":"D"
},
{
"rating":3,
"ratingname":"Three Star",
"section":"E"
},
{
"rating":7,
"ratingname":"Visiting Section",
"section":"F"
},
{
"rating":3,
"ratingname":"Three Star",
"section":"K"
},
{
"rating":3,
"ratingname":"Three Star",
"section":"L"
},
{
"rating":8,
"ratingname":"Family Section",
"section":"M"
},
{
"rating":8,
"ratingname":"Family Section",
"section":"N"
},
{
"rating":8,
"ratingname":"Family Section",
"section":"O"
},
{
"rating":3,
"ratingname":"Three Star",
"section":"P"
},
{
"rating":3,
"ratingname":"Three Star",
"section":"Q"
}
],
"id":"a20c6aa0-de40-483e-bf61-a0f30129d180",
"client_id":null,
"url":"/michigan-state-spartans-mens-ice-hockey-tickets/michigan-state-spartans-men-s-ice-hockey-vs-notre-dame-fighting-irish-men-s-ice-hockey-1-11-2013?ref_tag=aff.api",
"name":"Michigan State Spartans Men's Ice Hockey vs. Notre Dame Fighting Irish Men's Ice Hockey",
"local_date_time":"1/11/2013 7:05:00 PM",
"local_date_time_type":1,
"time_zone":"America/Detroit",
"venue_id":"625c36fa-b7e2-4267-9756-9e2f00815473",
"venue":"Munn Ice Arena",
"deal_rating":3,
"deal_rating_percentage":50,
"performer_id":"d2ccba0d-1064-419b-b2b6-9e2f008c354e",
"performer":"Michigan State Spartans Men's Ice Hockey",
"categories":[
{
"id":"ef87b34e-b33a-41c1-ac2e-089d7dd58d21",
"name":"Sports"
},
{
"id":"10a508af-1e1e-46a3-bffb-d86cb33b2e4a",
"name":"Hockey"
},
{
"id":"9eea95a5-8412-4ccf-9e1c-e89672aaee57",
"name":"College Hockey"
}
],
"is_on_sale":true,
"is_canceled":false,
"is_out_of_stock":false,
"rescheduled_from_event_id":null,
"rescheduled_to_event_id":null,
"secondary_performer_id":"9d163758-19cd-43f8-8a88-9e330109f0f3",
"secondary_performer":"Notre Dame Fighting Irish Men's Ice Hockey",
"metro_region":"Detroit",
"top_category":"Sports",
"lower_categories":[
"Hockey",
"College Hockey"
],
"description":"With the NHL locked out, the spotlight shifts to the college game and you wanna know what’s awesome? Big-time, high-stakes college hockey, up close and personal. Get out and see the Michigan State Spartans as they take on the best teams in the nation.",
"city":"East Lansing",
"venue_address":"1407 South Harrison Road",
"state":"MI",
"venue_latitude":42.7182049,
"venue_longitude":-84.4936633,
"day_of_week":"Friday",
"ticket_expiration":"1/11/2013 12:05:00 AM",
"next_3_days":false,
"next_7_days":false,
"next_30_days":true,
"this_weekend":false,
"star_ratings":[
{
"rating":3,
"deal_rating":3,
"retail_price":27.24,
"deal_rating_percentage":50
},
{
"rating":7,
"deal_rating":3,
"retail_price":27.24,
"deal_rating_percentage":50
},
{
"rating":8,
"deal_rating":3,
"retail_price":27.24,
"deal_rating_percentage":50
}
]
}
]
}