Designing GraphQL queries

There are several sections of the LIVE Data API to explore

• live_area - area id, code and name use to represent match locations
• live_competition_season - names and ids for competitions and seasons you have access to
• live_lineup - match schedules and general information about each match (attendance, weather, etc)
• live_match - discover information about all scheduled matches
• live_match_event - all the attributes from every event that happened in live match or matches already played
• *_aggregated_stats - provide match, season and competition wide statistics for players and teams.

Each section will return a JSON result and it is possible to combine some sections for a more detailed query. However, StatsBomb recommends starting with simple queries.

Design queries with Apollo Studio

Apollo has a navigation tool to select and traverse all the data available in the LIVE Data API. The left-hand navigation includes the whole LIVE Data API graph.

Clicking on the plus will add the attribute to the query in the operations section

Clicking on the name of an attribute will expand it and show nested attributes, which can be individually selected for a more specific query.

Use the breadcrumb trail or back arrow in the Documentation section to navigate back up through the graph of the LIVE Data API.

Use the spyglass icon above the documentation to search the graph

Event updates

The LIVE Data API returns a set of events that are valid at the time of a particular query. As this is a near real-time API, there is the potential that an event can be updated during the live match.

Events are most likely to be updated due to further information being available, such as expected goal value xg. Corrections are more rare, however, given there are over 3000 events captured per match there may be some corrections during and soon after a live match.