Common GraphQL Queries

Competition Seasons available

Confirm you have access to the match data you require by checking the competitions and seasons you have access too.

query ExampleQuery {
 live_competition_season {
   season_name
   competition_name
   competition_id
   season_id
 }}

Team identity

Search for the first 10 matches with a team name starting with Man. The % character is a wild-card that represents any number of characters. % is a wild card character that can be used before or after the name to match any number of other characters. The % should be within the double quotes that defines the value used for the search.

query TeamIdentity {
 live_lineup(where:
   { team_name: { _like: "Man%" } },
   limit: 10) {
     team_name
     team_id
 }}

Scheduled matches for a team

The home and away matches scheduled (including those already played) can be viewed for your team

Use the _like attribute in the where filter to find teams by a partial match of the team name.

query TeamMatches {
 live_match(
   where: {
     _or: [
       {
         match_home_team_name: { _like: "Man%" }
         match_away_team_name: { _like: "Man%" }
       }
     ]
   }
 ) {
   match_date
   match_local_kick_off
   match_id
   match_home_team_name
   match_home_team_id
   round_type_name
   round_id
   match_away_team_name
   match_away_team_id
 }}

Avoid unwanted matches by using the team_id of your team

Modify the where condition of the query to use match_home_team_id and match_away_team_id fields, using _eq for the value the team identity should equal.

query TeamMatches {
 live_match(
   where: {
     _or: [
       {
         match_home_team_id: { _eq: 42 }
         match_away_team_id: { _eq: 42 }
       }
     ]
   }
 ) {
   match_date
   match_local_kick_off
   match_id
   match_home_team_name
   match_home_team_id
   round_type_name
   round_id
   match_away_team_name
   match_away_team_id
 }}

Matches within a time frame

Find a specific set matches or a single match by adding a where condition on the match_data attribute

Find all the matches scheduled for a particular time frame

query CompetitionMatchesSnapshot {
 live_match(
   where: { match_date: { _lt: "2021-09-01",
                          _gte: "2021-08-01" } }
 ) {
    match_id
    match_date
    match_local_kick_off
    match_name
    match_home_team_id
    match_away_team_id
 }
}

Find a specific match and match_id for an up-coming game by also including a condition on team_id.

Substitute the dates in _lt less than and _gt greater than as required.

As the team could be playing at home or away, both attributes are checked and any data that matches either identity is returned.

query NextTeamMatch {
  live_match(
    where: {
      _and: [
        { match_date: { _lt: "2021-10-15",
                        _gte: "2021-10-16" } }
        {
          _or: [
            { match_home_team_id: { _eq: 42 },
              match_away_team_id: { _eq: 42 } }
          ]
        }
      ]
    }
  ) {
    match_id
    match_date
    match_local_kick_off
    match_name
    match_home_team_id
    match_away_team_id
  }
}

Shots and Shot statistics from a live match

See the outcome of ever shot in the game, where the shot took place on the pitch and when the shot was taken

The shot events are followed by a statistical summary of the shots over the match so far

Replace the match_id value, 1000001, with the value of the match you are interested in

query ShotsAndStatistics {
 live_match_event(
   where: { match_id: { _eq: 1000001 }, name: { _eq: "shot" } }
 ) {
   name
   outcome
   player_id
   xg
   team_id
   end_x
   end_y
   minute
   second
 }
 live_team_match_aggregated_stat(
   where: { stat_name: { _eq: "shots" }, match_id: { _eq: 1000001 } }
 ) {
   stat_name
   value
 }
}

Including Player Positions

Add freezeframe attribute to the list of live_match_event attributes to also see position of all the players on the pitch at the time the shot was taken.

Tracking Event Status

To publish events as soon as possible to the LIVE Data API, events such as shots are available before all their accompanying data is available.

The event's status will be set to "COMPLETE" once an event contains all the accompanying data.

Using a where condition to filter queries to show only completed events

query CompleteEvents {
  live_match_event(
    where: {
      match_id: { _eq: 1000125 }
      _and: [{ status: { _eq: "COMPLETE" } }]
    }
    limit: 4
  ) {
    id
    name
    team_id
    player_id
    timestamp
    status
  }
}

{
  "data": {
    "live_match_event": [
      {
        "id": "48bc8bda-05c3-4b2a-b091-990666f1ebba",
        "name": "starting-xi",
        "team_id": 58,
        "player_id": null,
        "timestamp": "00:00:00",
        "status": "COMPLETE"
      },
      {
        "id": "ec85fff5-1de0-4dca-aba1-babb0d5b6fff",
        "name": "starting-xi",
        "team_id": 35,
        "player_id": null,
        "timestamp": "00:00:00",
        "status": "COMPLETE"
      },
      {
        "id": "b4c25e29-9644-423b-9642-31bccf192cfe",
        "name": "half-start",
        "team_id": 35,
        "player_id": null,
        "timestamp": "00:00:00",
        "status": "COMPLETE"
      },
      {
        "id": "715eedf5-f77d-483a-8ac0-3001d2a77e15",
        "name": "ball-receipt",
        "team_id": 35,
        "player_id": 381,
        "timestamp": "00:00:02.783",
        "status": "COMPLETE"
      }
    ]
  }
}

When an event has status "COMPLETE" and all previous events in that match period are complete, then the event field finished is marked true. The latest event that indicate finished is true marks the point in the match where all information about the match events has been captured.

query LatestFinishedEvent {
  live_match_event(
    where: { match_id: { _eq: 1000125 }, _and: [{ finished: { _eq: true } }] }
    limit: 1
    order_by: [{ minute: "desc_nulls_last" }]
  ) {
    id
    name
    index
    match_id
    minute
    outcome
    finished
    team_id
    player_id
  }
}

{
  "data": {
    "live_match_event": [
      {
        "id": "cf505cec-ae96-4010-955c-ba20f404ee8e",
        "name": "pass",
        "index": 1116,
        "match_id": 1000125,
        "minute": 93,
        "outcome": "complete",
        "finished": true,
        "team_id": 35,
        "player_id": 381
      }
    ]
  }
}

Calculating scores

For the purpose of score calculations, the API makes the following attributes available:

• goal_for - the ID of the team scoring a goal (or whose opposition conceded an own goal)
• goal_against - the ID of the team conceding a goal

Ordering

Given our API can update and delete events you may want to order events in two different ways:

1. Order by most recently updated so you will know which events have been updated using the updated_at field (most useful with subscriptions)
2. Order by match event sequence using the period and index fields (most useful with queries)

Both these options have different tradeoffs:

• If you order by most recently updated the API may not return events in sequence as this is denoted by the index field
• If you order by match event sequence it will be less clear when events have been updated

Ordering by updated_at

If you wish to know the most recent updates to events in a match you can order by updated_at. This is an example:

subscription MySubscriptionToMatch789 {
  live_match_event(where: {match_id: {_eq: 789}}, order_by: {updated_at: desc}) {
    id
    name
    team_id
    player_id
    timestamp
    updated_at
  }
}

Ordering by period and index

If you want to receive the newest events in a match ordered by event sequence you can order by period and index:

query MyQueryToMatch789 {
  live_match_event(where: {match_id: {_eq: 789}}, order_by: {period: desc, index: desc}) {
    id
    name
    team_id
    player_id
    timestamp
  }
}

Please note the following:

• It's important to use period as the index field always resets to 1 at the start of a new match half
• An event's index field can change as our system may receive events out of order due to network latency

Pagination

Our API returns enough events to cover an entire match, up to 4,200 events. Pagination typically is only required when limiting the number of events returned

The number of events returned can be managed by limit.

The offset parameter in a query can be set to skip a number of events, enabling a basic pagination approach that will retrieve a specific range of data.

In this example query, specifying an offset of 150 skips the first 150 events, returning the 50 events after the offset.

query MatchPagination {
  live_match_event(
    where: {match_id: {_eq: 789}},
            order_by: {period: asc, index: asc},
            limit: 150,
            offset: 50) {
    id
    name
    team_id
    player_id
    timestamp
  }
}

Continue paging through the events with successive queries by increasing the limit and offset values by 50, until there are no further events returned from the query.