Getting started

As you can see in this documentation, we have a wide varierty of endpoints. In this page we will try to give you some hand holds on how to get started using our API.

Resources

There are several important resources in our system as described in the image below:

1. Tournament, a season bound resource grouping events together.
2. Venue, a place where one or more events take place.
3. Team(s), events with teams such as football will always have two teams linked.
4. Event, the actual sportevent on a specific location on a specific date (or several days)
5. Tickets, the actual ticket you buy from us.
6. Category, a specific section of a venue. Tickets are always part of ONE category.

Entity relation diagram

Update interval

Below is an overview of the resources and if you could cache them locally and how often we suggest to update them.

Resource	Suggested update interval	What could change	Cache locally
Tournament	Monthly	End date	✅
Venue	Monthly	Minor details	✅
Team	Monthly	Fixes in team naming	✅
Event	Daily	Date confirmation, exact start and end date	✅
Tickets	directly	Available tickets, prices, status	❌ - changes too often you risk being out-of-date
Category	Weekly	Descriptions	✅

Fair use and rate limiting

We have rate limiting in place, but so far has never been an issue to any of our customers. It's goal is to prevent abuse.

Some rule of thumb:

1. Only update information you actually need
2. Use the in operator to fetch several items in one go (keep in mind that there is a technical limit to URLs)

Suggested steps

Now that you have a general idea of the resources involved, you can start calling our API. But where to start? Our advise:

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

Determine sport(s)

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

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

Fetching tournaments (optional)

An important thing to remember, our tournaments are seasonal. So for example for "Premier League", there will also be historical tournaments.

Therefor it is important to always include a 'date filter' which is greater or equal then the current date. See our resource filtering and sorting for more information about this.

For our get tournaments endpoint, getting all soccer tournaments ending in the future you can do this:

/v1/tournaments?sport_type=soccer&date_stop=ge:2025-03-05

To break it down:

• /v1/tournaments - the endpoint
• sport_type=soccer - filter on tournaments with sport type soccer
• date_stop=ge:2025-03-05 - filter on tournaments with a stop date greater or equal then 5th of march 2025

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. You will want to apply a similar 'date_stop' filter to only get events that are yet to stop.

Filtering on tournament is optional, you can also choose to apply the 'sport_type' filtering here. The tournament_id and tournament_name are included in the response.

So the tournament endpoint only adds 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=ge:2025-03-05

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

/v1/events?tournament_id=f4e18b5c2d2c4693907b3453bd92b87a_trn&date_stop=ge:2025-03-05

Using the in operator, you can also do multiple sports (our tournaments) in one go:

/v1/events?sport_type=in:[soccer,formula1]&date_stop=ge:2025-03-05

Multiple Tournaments:

/v1/events?tournament_id=[f4e18b5c2d2c4693907b3453bd92b87a_trn,c059aea958fb44c4b778c88c0b10b7c0_trn]&date_stop=ge:2025-03-05

Our event response is quite extensive and already holds a lot of information of related resources, for example:

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

You can use this to enrich the data on your website. If you need more information from the venue, like the adress, you'll have to fetch those.

Fetching venues (enriching)

Venues usually do not change often. Sometimes a stadium might get a different name of course.

Using the get venues endpoint you can fetch all our events, beware of pagination since the default page_size is 50 and we have several hundreds of venues.

The venue response contains adress information which could be beneficial to your website as it enriches the information.

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 stocket greater then 0:

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

One thing you will sometime notice, is that we have several tickets which appear to be overlapping.

This is correct; since we often have multiple suppliers for the 'same' tickets.

These supplier could be actual resellers, but also other customers who have decided to 'relist' their ticket on our platform.

To make sense of these, you will need to group the tickets, which you should do on the following fields of a ticket:

• 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 targetgroup.

The last one is a combination based on ticket_validity and ticket_targetgroup (note: we currently only have regular).

CAUTION

Each ticket_id implies a different supplier and means we cannot guarantee sitting 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 identifiers. But they will all have their own specific sub_category

Ticket valid for	sub_category value
Friday	fri_regular
Saturday	sat_regular
Sunday	sun_regular
Saturday + Sunday	satsun_regular
Whole weekend	weekend_regular

With this knowledge, you now know you should group tickets based on:

• event_id
• category_id
• sub_category

Some combinations will have just one ticket, others might have several. Then it really depends on your (customer) needs;

• Cheapest ticket
• and/or Amount of tickets you need

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

CAUTION

Each ticket_id implies a different supplier and means we cannot guarantee sitting together if you buy several tickets with different ticket_id.

How many seats are guaranteed together?

To find out, you can fetch the category information of all the categories for the whole event via: /v1/categories?event_id:some_event_id

The category_id in response can then be matched to category_id on the ticket.

This category object in the response has a party_size_together field which gives the number of seats that are guaranteed together.

Note: Yes, you can fetch each category separately but this is inefficient for bigger events due to roundtrips and latency for each call.

Football

For football, the only sub_category will be singleday_regular. Applying the same grouping as for formula 1 makes it easier and will give the proper result as well.

Fetch categories (enriching)

As already hinted in the previous part, categories contain some information which can be useful. You can fetch categories using some filters, or all of them.

Suggested approach would be to filter on event_id, since you know what events you'll be interested in.

So for example:

/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

Now that you have the basics of our API integrated, you can move on to to more advance topics;

• Guest data
• Booking flow