API Update: Real-Time Clock Feeds and GraphQL Subscriptions

API Update: Real-Time Clock Feeds and GraphQL Subscriptions

Today we're rolling out more additions to our public GraphQL API. These additions include the API that you'll be able to use to get real-time game and play clock data.

API Changes

We've added fields that allow you to get the current clocks for games:

  • GameClock has been added.
  • GamePlayClock has been added.
  • Game has new fields: clock, playClock

Each clock object simply consists of a number of seconds and a real world time.

We've also added fields that allow you to get the complete historical data for clocks:

  • GameClockEdge has been added.
  • GameClockHistoryConnection has been added.
  • GamePlayClockEdge has been added.
  • GamePlayClockHistoryConnection has been added.
  • Game has new fields: clockHistoryConnection, playClockHistoryConnection

Using these fields, you can get every clock tick for a game.

We've added support for GraphQL subscription operations:

  • Subscription has been added.

This top level object has heartbeat, gameClock, and gamePlayClock fields that can be used to test your subscription code and receive clock samples with the lowest possible latency.

We've introduced a few mutations (not publically usable) to support these additions:

  • GamePlayClockInput has been added.
  • GameClockInput has been added.
  • Mutation has new fields: setGameClock, setGamePlayClock

And one unrelated change has also been made:

  • UserPatchInput has new fields: handle

This will allow users to change their handle once we enable registration.

Subscriptions with graphql-ws

We use the graphql-ws subprotocol to support GraphQL subscriptions. WebSocket connections should be established with the /v1/graphql-ws endpoint, and use the protocol as described by this document.

Our GraphiQL interface fully supports subscriptions, so you can easily try them out there:



Like NFL games, our games will use the scoreboard to keep the official time.

That means the origin for clock data is either one of these:


Or one of these:


These controllers connect to a computer that feeds the clock ticks into our API via the setGameClock and setGamePlayClock mutations introduced today. Those mutations immediately publish clock ticks to all subscribers. This means you'll have access to the lowest latency feeds we can provide and can generally expect at most a few hundred milliseconds of latency.

API Update: Real-Time Clock Feeds and GraphQL Subscriptions
Share this