Let's learn about the fast-moving data of events in the SportsEngine GraphQL API. Events are the unique intersection of organizations, teams, location, and time. They help profiles know when a practice, game, or meeting will happen. Working with events also means working with mutations to navigate the constant updates around scores, referee assignments, and video links. Let's start with event queries.
Query Events by Organization
Getting all the events for an organization is the easiest way to know what is happening. We recommended passing in start and end dates to filter your results, which are UTC formatted.
query Events {
events(organizationId: 12345) {
pageInformation {
pages
count
page
perPage
}
results {
id
organizationId
name
type
start
end
location {
name
description
url
address
}
status
eventTeams {
score
primaryColor
homeTeam
name
}
}
}
}
The events response will paginate according to the page information. See First GraphQL Query for more information on how to navigate pagination.
{
"data": {
"organization": {
"events": {
"pageInformation": {
"pages": 11,
"count": 257,
"page": 1,
"perPage": 25
},
"results": [
{
"id": "7f49cdae-e4e1-4f16-a4bd-667f4d74be02",
"organizationId": 12345,
"name": "Bloomington Bandits-Blue at 18U Boys",
"description": "",
"type": "game",
"status": "scheduled",
"start": "2015-06-03T18:00:00.000Z",
"end": "2015-11-17T21:22:15.000Z",
"created": "2019-07-10T16:35:27.000Z",
"updated": "2022-12-01T19:12:00.000Z",
"location": {
"name": "",
"description": "",
"url": "",
"address": "Dred Scott Field #1"
},
"eventTeams": [
{
"score": "1",
"primaryColor": "0036E0",
"homeTeam": true,
"name": "18U Boys"
},
{
"score": "5",
"primaryColor": "0036e0",
"homeTeam": false,
"name": "Bloomington Bandits-Blue"
}
]
}
]
}
}
}
}
Add and Update Mutations for Events
The next step is updating an existing event on the platform using GraphQL mutations. In the mutation, you only need to specify the updated attributes. You can skip all the other attributes in the update. The only attribute required is "eventId."
While any attribute can be defined and returned in these mutations, we recommend adding the mutated attribute(s) to confirm the change. If no attributes are defined, you will receive a "GRAPHQL_VALIDATION_FAILED error."
mutation UpdateEvent {
updateEvent(
eventId: "9ebade3c-ed9d-42fd-a4cc-b47499a0c2f1"
input: {description: "Test Event"}
) {
id
name
updated
description
}
}
Adding a new event is a similar mutation to updating an event:
mutation CreateEvent {
createEvent(
input: {name: "Test Event", type: "event", start: "2023-09-22T22:00:00.000Z", end: "2023-09-22T24:00:00.000Z", status: scheduled, description: "Get everyone together for season start"}
) {
id
organizationId
name
description
type
start
end
created
updated
status
}
}
Convenience Mutations for Events
Events are some of the fastest-changing objects on the platform. To make understanding those changes easier, we have provided specific mutations for:
Update Event Score
Add & Remove Event Officials
Add & Remove Event Videos
Update Event Score
This mutation provides direct access to scoring an event. Only created game events that have teams assigned can be scored.
mutation UpdateScore {
updateScore(
eventId: "2746b68a-5959-45f8-aa58-8d8022a4a11b"
scoreTeam1: "1"
scoreTeam2: "8"
) {
name
eventTeams {
score
}
}
} Add & Remove Event Officials
These mutations provide access to adding and removing event officials. Event officials encompass referees, umpires, judges, etc. Events can have several officials assigned, each with an official name, role, and profile ID. When removing an official, the profileId is the primary key. ProfileId must match for the official to remove them from the list.
mutation AddOfficial {
addOfficial(
eventId: "2746b68a-5959-45f8-aa58-8d8022a4a11b"
official: {firstName: "Ryan", lastName: "Benson", role: "Field Referee", profileId: 95714444}
) {
name
officials {
firstName
lastName
role
}
}
} Add & Remove Event Videos
These mutations are for adding and removing video links on a specific event. Typical events include live streams and recorded videos. Profiles in HQ and mobile applications will display the title and description. When removing video links, the URL attribute is the primary key and must match.
mutation AddVideo {
addVideo(
eventId: "2746b68a-5959-45f8-aa58-8d8022a4a11b"
url: "https://www.sportsengine.com"
title: "Watch on SE Play"
description: "Live stream of the Dragons at the Cardinals"
) {
name
videos {
title
description
url
}
}
}