Appearance

Find events & tickets ​

Build your catalogue in five steps: pick sports, fetch events, enrich with venues, fetch tickets and enrich with categories.

  1. Determine the sports you are interested in
  2. Fetch all events of those sports
  3. Fetch all venues of those events (enriching)
  4. Fetch all tickets of those events
  5. Fetch all categories of those tickets (enriching)

Before you start

Know the resources and the filtering operators. Always include a date filter greater or equal to today, otherwise historical data is returned too.

Determine sport(s) ​

The first step is determining what sports you are interested in, since you can filter tournaments and events on sports.

We have quite a few sports and keep adding new ones. Use our get sports endpoint to see the most recent list.

Fetching tournaments (optional) ​

Our tournaments are seasonal. For "Premier League" there will also be historical tournaments. Therefore always include a date filter which is greater or equal to the current date, see Filtering & sorting.

With the get tournaments endpoint, you get all soccer tournaments ending in the future like this:

/v1/tournaments?sport_type=soccer&date_stop={{DOC_DATE_FILTER_GE}}

To break it down:

  • /v1/tournaments - the endpoint
  • sport_type=soccer - filter on tournaments with sport type soccer
  • date_stop= - filter on tournaments with a stop date greater or equal than

The response includes several fields, most importantly:

  • tournament_id: our internal identifier of this tournament
  • official_name: the official name of the tournament
  • number_events: the number of events yet to start (or end) in this tournament

Fetching events ​

For events, the same date filter rule applies. Apply a date_stop filter to only get events that are yet to stop.

Filtering on tournament is optional, you can also apply the sport_type filter here. The tournament_id and tournament_name are included in the response, so the tournament endpoint only adds the start and stop date of the tournament itself.

Using the get events endpoint, you can get all future soccer events like this:

/v1/events?sport_type=soccer&date_stop={{DOC_DATE_FILTER_GE}}

Or, if you know the tournament_id, filter on that. For example Premier League (24/25) has id f4e18b5c2d2c4693907b3453bd92b87a_trn:

/v1/events?tournament_id=f4e18b5c2d2c4693907b3453bd92b87a_trn&date_stop={{DOC_DATE_FILTER_GE}}

Using the in operator, you can fetch multiple sports in one go:

/v1/events?sport_type=in:[soccer,formula1]&date_stop={{DOC_DATE_FILTER_GE}}

Or multiple tournaments:

/v1/events?tournament_id=in:[f4e18b5c2d2c4693907b3453bd92b87a_trn,c059aea958fb44c4b778c88c0b10b7c0_trn]&date_stop={{DOC_DATE_FILTER_GE}}

The event response already holds information of related resources, which you can use to enrich your website:

  • tournament_id, tournament_name
  • hometeam_id, hometeam_name
  • visiting_id, visiting_name
  • venue_id, venue_name

If you need more information from the venue, like the address, fetch the venue.

Fetching venues (enriching) ​

Venues usually do not change often. Sometimes a stadium gets a different name.

Using the get venues endpoint you can fetch all our venues. Beware of pagination: the default page_size is 50 and we have several hundreds of venues, see Formats & conventions.

The venue response contains address information which can enrich your website.

Fetch all tickets ​

Using our get tickets endpoint you can fetch all the tickets for a specific event.

For example, to grab all tickets which are available and have a stock greater than 0:

/v1/tickets?event_id=some_event_id&ticket_status=available&stock=gt:0

You will sometimes notice tickets which appear to be overlapping. This is correct: we often have multiple suppliers for the "same" tickets. These suppliers can be actual resellers, but also other customers who have decided to relist their ticket on our platform.

To make sense of these, group the tickets on the following fields:

  • event_id is the identifier of the event
  • category_id is the identifier of the category
  • sub_category identifies a ticket for a specific ticket validity and target group

The last one is a combination of ticket_validity and ticket_targetgroup (we currently only have regular).

Seating together

Each ticket_id implies a different supplier, so we cannot guarantee seating together if you buy several tickets with different ticket_id.

Formula 1 (and other multi-day events) ​

For multi-day events, we sometimes have tickets for specific days or the whole weekend for one category. These all share the same event_id and category_id, but each has its own sub_category:

Ticket valid forsub_category value
Fridayfri_regular
Saturdaysat_regular
Sundaysun_regular
Saturday + Sundaysatsun_regular
Whole weekendweekend_regular

Some combinations will have just one ticket, others several. Which one to show depends on your (customer) needs:

  • Cheapest ticket
  • and/or the amount of tickets you need

For example, the cheapest ticket might only have 2 left while you need 4. Then the second cheapest is a better fit.

How many seats are guaranteed together? ​

Fetch the categories of the whole event via /v1/categories?event_id=some_event_id. The category_id in the response matches the category_id on the ticket. The category has a party_size_together field with the number of seats that are guaranteed together.

You can fetch each category separately, but this is inefficient for bigger events due to round trips and latency.

Football ​

For football, the only sub_category is singleday_regular. Applying the same grouping as for Formula 1 gives the proper result as well.

Ticket flags ​

Some resources, such as tickets, have extra flags to signify rules that are active for that ticket. For commercial reasons, we (or our suppliers) do not want to be left with a single ticket since these are hard to sell.

FlagDescription
pairs_onlyOnly pairs of tickets can be ordered (2-4-6-etc)
no_max_minus_1To prevent a single ticket from being left over, the maximum - 1 quantity cannot be ordered

Fetch categories (enriching) ​

Categories contain information that is useful on your site. Filter on event_id, since you know which events you are interested in:

/v1/categories?event_id=<your_event_id>

You can also fetch multiple categories using category_id and the in operator:

/v1/categories?category_id=in:[f22deca3d4374614b324a08c45808bd0_ctg,cabeea26bc584a5db30664ccc4fca4ba_ctg]

Next steps ​