Search For Events

Learn to search for and filter events using Ticketmaster's Discovery API.

We'll cover the following

With our API key in hand, we can finally start making calls to the Ticketmaster APIs. Starting in this chapter, we'll go over the different endpoints offered by Ticketmaster's Discovery and Inventory Status APIs. We'll begin with the Discovery API.

Event search

The purpose of the Discovery API is—as the name implies—to discover events, venues, attractions, and so on. We can use the events endpoint of the Discovery API to search for and filter events based on different criteria.

The URL for this endpoint is:

https://app.ticketmaster.com/discovery/v2/events

We can provide multiple optional parameters to filter the search results. A few of these parameters and their uses are mentioned below—you can visit this lesson to see the complete list:

Parameter

Type

Category

Description

id

string

optional

If provided, the search results are filtered by the event ID.

keyword

string

optional

A keyword on which the search is performed.

attractionId

string

optional

If provided, the search results are filtered by the attraction ID.

venueId

string

optional

If provided, the search results are filtered by the venue ID.

startDateTime

string

optional

If provided, the search results are filtered to return events with a start date after this date.

endDateTime

string

optional

If provided, the search results are filtered to return events with a start date before this date.

size

number

optional

The number of results to be returned per page. The default value is 20.

page

number

optional

The page of the search results to be returned. The default value is 0.

sort

string

optional

The sorting order of the search results. Allowable values are, name,asc, name,desc, date,asc, date,desc, relevance,asc, relevance,desc, distance,asc, name,date,asc, name,date,desc, date,name,asc, date,name,desc, distance,date,asc, onSaleStartDate,asc, id,asc, venueName,asc, venueName,desc, random. The default value is relevance,desc.

classificationId

array[string]

optional

If provided, the search results are filtered by classification id, that is, the ID of any segment, genre, subgenre, type, subtype. Negative filtering is supported by using the following format '-'. (Negative filters may cause decreased performance.)

The result of an API call to this endpoint is a JSON object. The table below shows the keys of the resultant JSON object:

Property

Type

Description

_embedded

object

The _embedded object contains a single property, events that holds the search results in the form of an array of objects, with each object representing one event. By default, the events are sorted in descending order of relevance.

_links

object

The _links object contains links to the first, next, and last pages in the search results, as well as the link to the current page.

page

object

The page object contains information regarding the pages of the search results, including the size of each page, the total number of results, the total number of pages, and the current page number.

As we know, search results are usually returned in the form of multiple pages, like how Google presents search results.

The response object returned as the result of a single API call represents a single page of the search results—by default, the first page. The number of results per page is defined by the query parameter, size, which defaults to 20.

If we want a specific page of the results, we can use the page query parameter. Alternatively, we can simply use the links conveniently provided to us in the _links property to navigate to the next or previous pages of the search results.

The actual results of the search are stored within the events array in the _embedded property, where each array element represents an event. We'll discuss the details of the event objects in a later chapter.

Search without parameters

Let's try making an actual call to this endpoint, first with no search parameters. Later we'll make a call with a few of the optional parameters, such as id and keyword.

The code below makes a call to the events endpoint, using none of the optional parameters. If you haven't yet, provide your API_KEY below before running the code.

Press + to interact
import json

import requests



api_key = '{{API_KEY}}'



response = requests.get('https://app.ticketmaster.com/discovery/v2/events',

                        params = {

                            'apikey' : api_key

                        }).json()



print(json.dumps(response, indent=4))

In the code above:

  • Lines 1–2: We import the required libraries, including the requests library to make HTTP calls.
  • Line 4: We store the API_KEY in a variable called api_key.
  • Lines 6–10: We ping the events endpoint, specifying that we want only five results per page.
  • Line 12: We format and print the response object to the console.

Search with optional parameters

Now let's try searching with some optional parameters, such as the size parameter:

Note: The code below extracts an event ID to be used later. Don't forget to save this ID after you run the code!

Event IDs expire after considerable time has passed since the respective events. If you end up with an invalid event ID, you can run the code below to generate a new ID for you.

Press + to interact
import json

import requests



api_key = '{{API_KEY}}'



response = requests.get('https://app.ticketmaster.com/discovery/v2/events',

                        params = {

                            'apikey' : api_key,

                            'size': 5

                        }).json()



print(json.dumps(response, indent=4))

This time around, the size of the response is limited by the size parameter we passed to the endpoint. We can confirm this by checking the value of the size property in the page object.

Let's try some other parameters as well, such as the id and keyword parameters:

Note: The widget below uses the event ID extracted from the previous widget. If you want, you can also replace it with another valid event ID.

Press + to interact
import json

import requests



api_key = '{{API_KEY}}'

event_id = '{{EVENT_ID}}'



response = requests.get('https://app.ticketmaster.com/discovery/v2/events',

                        params = {

                            'apikey' : api_key,

                            'id' : event_id

                        }).json()



print(json.dumps(response, indent=4))

In the code above, we're using the event ID extracted from the previous example to filter the results. Since IDs are unique, we get a single event in the search results. We can verify this by checking the page property of the search results, where the value of totalElements is 1.

Let's also try searching for a keyword. Replace lines 5–11 in the widget above with the code below. If you want, you can also replace the value of the keyword variable with a phrase of your liking:

Press + to interact
keyword = 'concert'



response = requests.get('https://app.ticketmaster.com/discovery/v2/events',

                        params = {

                            'apikey' : api_key,

                            'keyword' : keyword

                        }).json()

So far, we've used these parameters individually, but we can also use combinations of parameters. Feel free to play around with other search parameters as well!

Navigate between pages

As mentioned before, search results are returned in the form of pages, and we can navigate between these pages using the links provided in the _links property. Let's try navigating to the next page of the results using this approach:

Press + to interact
import json

import requests



api_key = '{{API_KEY}}'



page_one_response = requests.get('https://app.ticketmaster.com/discovery/v2/events',

                        params = {

                            'apikey' : api_key

                        }).json()



# retrieving the link of the next page from the _links property

page_two_url = page_one_response['_links']['next']['href']



# constructing the full url for the next page

page_two_url = 'https://app.ticketmaster.com' + page_two_url



# getting the next page of the search results

page_two_response = requests.get(page_two_url, params = {'apikey' : api_key}).json()



print(json.dumps(page_two_response, indent=4))

This is admittedly a trivial example, but the ability to navigate so easily to the next and previous pages of the results is instrumental, especially in the context of an application using the Discovery API!