Concepts
How matches, court positions and insights are described in the API.
Everything is from your team's point of view
A match involves two teams, but you read it through one of your club's teams. Responses describe that team as team and the other side as opponent, whichever club uploaded the footage.
- In a match,
team.scoreis your team's score andopponent.scoreis theirs. - In events,
sideisteamoropponent. - In the box score,
teamholds your players andopponentholds the other team's totals and, when their stats were tagged, their players.
When you request a match by id and both teams in it belong to your club, the side that uploaded the footage is treated as team.
recordedBy
recordedBy on a match tells you which side uploaded the footage.
| Value | Meaning |
|---|---|
team | Your club recorded the match. |
opponent | Another club recorded it and shared it with your team. |
Insights work the same either way. Generate them from the API; nobody has to open the Superstat app first.
Match status
| Value | Meaning |
|---|---|
not_started | The match exists but no footage has been uploaded. |
in_progress | Footage is uploading or being tagged. |
processing | Stats and insights are being produced. |
complete | Everything is ready. |
failed | The footage could not be processed. failureReason says why. |
Box scores and events fill in as a match moves through processing. Read them once status is complete for final numbers. Insights can be generated only after the match is complete.
Periods
Footage is split into periods: quarters or halves. Each period has an id, and events refer to it as periodId. periodSeconds counts from the start of that period; matchSeconds counts from the start of the match.
Court position
A shot event's location is a point on a full FIBA basketball court, 28 metres long and 15 metres wide. That is the court diagram Superstat draws in the app.
xruns from the left baseline (0) to the right baseline (1).yruns from the top sideline (0) to the bottom sideline (1).fromLeftBaselineMetresandfromTopSidelineMetresare those fractions converted to metres.- The court is not rotated to the shooting team's basket.
(0, 0)is the top-left corner of the diagram. - Events that were not placed on the court, such as rebounds, assists and fouls, have
location: null.
Players and roster entries
Two ids identify a player:
playerIdis the player on your team roster. It stays the same across matches. Use it for player insights.rosterEntryIdis the player's spot on one match's team sheet. Use it to join box score rows and events within a match.
Opponent players do not have a playerId; they are identified by name and jersey number.
Insights
Team insights and player insights share a status.
status | Meaning |
|---|---|
ready | summary and ratings are included. |
not_generated | The match is complete, but insights have not been written. POST the insights URL. |
generating | A run is in progress. Poll the GET. It usually takes one to two minutes. |
failed | The last run failed. message says why. POST again to retry. If insights were written before, they are still included. |
unavailable | The match is not complete, so insights cannot be written yet. |
POST /v1/matches/{matchId}/insights writes the team summary and every rostered player's insights in one run. POST /v1/matches/{matchId}/player-insights/{playerId} starts that same run. The response comes back immediately with status: generating; keep calling the GET until status is ready.
When the box score changes after insights were written, stale is true. POST again to regenerate them. Pass ?regenerate=true to rewrite insights that are already up to date.
Percentages and minutes
Percentages are numbers from 0 to 100 with one decimal place, for example 44.8. Minutes are decimal minutes, for example 27.4. When a coach has entered minutes by hand they replace the minutes detected from footage.