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 shown, postponed, 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	Conditionals

Name	Description	Type	Presence	Location	Conditionals
`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`		Decimal	Optional	Query	No
`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
`min_and_max_price`	Results will include `avg_price`, `sum_price`, `median_price`, `min_price` & `max_price`, calculated based on that Credential’s settings	Boolean	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,
      "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
    }
  ]
}