Events / Index





Name

Events / Index

Description

Obtain a list of Events that match given conditions.

Type

GET

URL

/v9/events

Credential Type

API|User

Supports Pagination

Yes



Long Description

Possible Event States 
The possible event states are shownpostponed, and canceled.

TBD Events 
TBD Events will be returned with an occurs_at of 00:00:00.



Note: You should not use the list method with a name parameter to search events as that will perform an exact match search. To search events first use the /search endpoint to search against your string and then list events using a performer_id or venue_id selected from your /search results.

 

NOTE: The seating_chart image URLs within the configuration object are deprecated and no longer updated. Instead, you should use our dynamic seating charts.



Parameters

Name

Description

Type

Presence

Location

Name

Description

Type

Presence

Location

venue_id

Venue at which the event occurs

Integer

Optional

Query

No

name

Exact name of the event. Use Events / Search when searching for events by name.

String

Optional

Query

No

occurs_at

Refine dates at which the event occurs using an ISO 8601 formatted datetime.

You can use occurs_at twice when using conditionals to retrieve events within a date range. For example, to retrieve only events within April 2018 use occurs_at.gte=2018-04-01&occurs_at.lt=2018-05-01



Date (ISO_8601)

Optional

Query

Yes

updated_at

Refine dates at which the event was updated using an ISO 8601 formatted datetime

Date (ISO_8601)

Optional

Query

Yes

popularity_score

Refine long term popularity score

Decimal

Optional

Query

No

short_term_popularity_score

Refine short term popularity score

Decimal

Optional

Query

No

office_id

Show only events for which this office has tickets

Integer

Optional

Query

No

performer_id

Show only events at which this performer will perform

Integer

Optional

Query

No

primary_performer

If primary_performer is true only events where  performer_id is the Primary performer for the event will be returned.

If primary_performer is false only events where  performer_id is the NOT the Primary performer for the event will be returned.

Boolean

Optional

Query

No

category_id

Show only events in this category (does not include sub-categories)

Integer

Optional

Query

No

category_tree

When true and used in conjunction with category_id events in sub-categories of the category_id will be included.

Boolean

Optional

Query

No

q

Full-text search events

String

Optional

Query

No

fuzzy

When true and used in conjunction with q will result in fuzzy full text search. Will NOT work if passed without q.

Boolean

Option

Query

No

lat

Latitude & longitude for geolocated searches. Control size of geolocation area using within. Must supply both.

Decimal

Optional

Query

No

lon

within

Radius in miles for geolocated searches (default 15)

Decimal

Optional

Query

No

ip

Infer lat and lon by location of IP address for geolocated searches.

String

Optional

Query

No

postal_code

Infer lat and lon by location of postal code for geolocated searches. Control size of geolocation area using within.

This method of geolocation is not recommended.

String

Optional

Query

No

city_state

Infer lat and lon by location of city and state for geolocated searches. Control size of geolocation area using within.

This method of geolocation is not recommended.

String

Optional

Query

No

country_code

Provide an ISO 3166 Alpha-2 country code to have results filtered to that specific country.

String (2)

Optional

Query

No

only_with_tickets

Show only events that have inventory regardless of whether they are available for sale (All states will be shown). If you want only available tickets, use only_with_available_tickets

String [all | etickets]

Optional

Query

No

by_time

Show only events whose start time is during the day (between 4 AM-4 PM) or night (otherwise)

String [day | night]

Optional

Query

No

only_with_available_tickets

Show only events that have available tickets (tickets for sale). Pass with office_id for inventory belonging only to your office. 

Boolean

Optional

Query

No

order_by

Pass in the parameter that you want to order by and the sorting order (Ex. :order_by => "events.popularity_score DESC")

String

Optional

Query

No

only_discounted

If true then only events that have discounted tickets will be returned.

Boolean

Optional

Query

No



Examples

Request

Response

Request

Response

GET /v9/events?performer_id=13910&occurs_at.gte=2023-08-19&occurs_at.lte=2023-08-21

{ "current_page": 1, "per_page": 100, "total_entries": 2, "events": [ { "available_count": 811, "category": { "id": "4", "name": "Minor League Baseball", "slug": "minor-league", "url": "/categories/4", "slug_url": "/categories/minor-league", "parent": { "id": "2", "name": "Baseball", "slug": "baseball", "url": "/categories/2", "slug_url": "/categories/baseball", "parent": { "id": "1", "name": "Sports", "slug": "sports", "url": "/categories/1", "slug_url": "/categories/sports", "parent": null } } }, "configuration": { "id": 11583, "url": "/configurations/11583", "name": "Baseball", "fanvenues_key": null, "ticket_utils_id": null, "seating_chart": { "medium": "null", "large": "null" } }, "id": 2165591, "long_term_popularity_score": 0.216, "name": "Louisville Bats at Iowa Cubs", "notes": "", "occurs_at_local": "2023-08-19T00:00:00-05:00", "occurs_at": "2023-08-19T00:00:00Z", "owned_by_office": false, "performances": [ { "performer": { "id": 14029, "slug": "louisville-bats", "slug_url": "/performers/louisville-bats", "url": "/performers/14029", "name": "Louisville Bats" }, "primary": false }, { "performer": { "id": 13910, "slug": "iowa-cubs", "slug_url": "/performers/iowa-cubs", "url": "/performers/13910", "name": "Iowa Cubs" }, "primary": true } ], "popularity_score": 2.78, "products_count": 811, "products_eticket_count": 459, "promotion_label": "Brennen Davis Bobblehead Giveaway", "state": "shown", "stubhub_id": null, "updated_at": "2023-07-25T14:41:34Z", "url": "/events/2165591", "venue": { "id": 4735, "slug": "principal-park", "url": "/venues/4735", "slug_url": "/venues/principal-park", "name": "Principal Park", "location": "Des Moines, IA", "time_zone": "America/Chicago" }, "discount_magnitude": 0 }, { "available_count": 897, "category": { "id": "4", "name": "Minor League Baseball", "slug": "minor-league", "url": "/categories/4", "slug_url": "/categories/minor-league", "parent": { "id": "2", "name": "Baseball", "slug": "baseball", "url": "/categories/2", "slug_url": "/categories/baseball", "parent": { "id": "1", "name": "Sports", "slug": "sports", "url": "/categories/1", "slug_url": "/categories/sports", "parent": null } } }, "configuration": { "id": 11583, "url": "/configurations/11583", "name": "Baseball", "fanvenues_key": null, "ticket_utils_id": null, "seating_chart": { "medium": "null", "large": "null" } }, "id": 2165592, "long_term_popularity_score": 0.172, "name": "Louisville Bats at Iowa Cubs", "notes": "", "occurs_at_local": "2023-08-20T00:00:00-05:00", "occurs_at": "2023-08-20T00:00:00Z", "owned_by_office": false, "performances": [ { "performer": { "id": 14029, "slug": "louisville-bats", "slug_url": "/performers/louisville-bats", "url": "/performers/14029", "name": "Louisville Bats" }, "primary": false }, { "performer": { "id": 13910, "slug": "iowa-cubs", "slug_url": "/performers/iowa-cubs", "url": "/performers/13910", "name": "Iowa Cubs" }, "primary": true } ], "popularity_score": 1.37, "products_count": 897, "products_eticket_count": 704, "promotion_label": null, "state": "shown", "stubhub_id": null, "tbd": false, "updated_at": "2022-10-11T21:05:37Z", "url": "/events/2165592", "venue": { "id": 4735, "slug": "principal-park", "url": "/venues/4735", "slug_url": "/venues/principal-park", "name": "Principal Park", "location": "Des Moines, IA", "time_zone": "America/Chicago" }, "discount_magnitude": 0 } ] }