A basketball scoreboard changes every few seconds: the game clock, the shot clock, the score and the team fouls. If Scoreboard OCR or your own program sends those to ScoreCastr, it has to use names ScoreCastr reads. This page lists every basketball field, the formats it accepts and one rule that matters more than the rest: always send both scores.
Before you start
- The Pro plan. The ScoreCastr button on the basketball Scoring tab opens the Data Hub.
- A webhook turned on for the match: on the Scoreboard OCR tab, pick HTTP Client (Webhooks), click Enable ScoreCastr and copy the Webhook URL. See Send live data by webhook.
- Scoreboard OCR users: see Connect Scoreboard OCR. Request format and replies: Webhook API reference.
Away means the away team from match setup; home is the home team. Field names are case sensitive.
away_score or home_score, ScoreCastr sets that score to 0. Send both scores in every update, even when you only mean to change the clock.Score, clocks and game state
| Field names | What it changes | Format |
|---|---|---|
away_score, awayScore |
Away score | Number |
home_score, homeScore |
Home score | Number |
period, quarter |
Quarter | 1 to 4, 5 for overtime. Numbers only |
clock, time, timeRemaining, time_remaining, game_clock, periodTimeLeft |
Game clock | MM:SS, like 4:12, or seconds, like 45.3 |
shot_clock, shotClock, shotClockTime |
Shot clock | Seconds |
possession, poss |
Possession arrow | home or h; away, a, visitor or guest |
away_fouls, awayFouls |
Away team fouls | Number |
home_fouls, homeFouls |
Home team fouls | Number |
away_timeouts, awayTimeouts |
Away timeouts left | Number |
home_timeouts, homeTimeouts |
Home timeouts left | Number |
Send the quarter as a number. Text like "Q2" or "OT" isn't read for basketball. currentQuarter on its own doesn't change the basketball quarter either; use period or quarter.
Team stats
Replace away_ with home_ for the home team.
| Field name (away) | Stat |
|---|---|
away_rebounds |
Rebounds |
away_assists |
Assists |
away_steals |
Steals |
away_blocks |
Blocks |
away_field_goals_made, away_field_goals_attempted |
Field goals |
away_three_pointers_made, away_three_pointers_attempted |
Three-pointers |
away_free_throws_made, away_free_throws_attempted |
Free throws |
Stats must use these snake_case names. A value that isn't a number is skipped.
How values are read
- Numbers can be numbers (
51) or text ("51"). - Game clock: "4:12" is 4 minutes 12 seconds. A plain number is seconds, so the last minute can come through as "45.3".
- Shot clock: a value that isn't a number becomes 24.
- Fouls and timeouts: a value that isn't a number becomes 0.
Example body
{
"away_score": 48,
"home_score": 51,
"period": 3,
"clock": "4:12",
"shot_clock": 14,
"possession": "away",
"away_fouls": 4,
"home_fouls": 6,
"away_timeouts": 3,
"home_timeouts": 2
}
What the scorebug does on its own
ScoreCastr compares each update with the one before:
- Timeouts left go down: the timeout flag plays for that team.
- Score up by 3 and three-pointers made up by 1 in the same update: the 3-point popup shows for 5 seconds.
- Free throws attempted go up: the free throw popup shows made/attempted for 5 seconds.
The two popups don't fire on the update where the quarter changes. Send timeouts as the number left, not the number used, or the timeout flag won't play.
Fix common problems
The score keeps going to 0. An update without the scores sets them to 0. Add away_score and home_score to every update.
The quarter shows a blank or wrong value. Send a number from 1 to 5 in period or quarter.
The clock jumps around. Let one source run the clock: the feed, or the dashboard's clock buttons, not both.
Nothing changes at all. Check the names letter for letter and that the match's method is HTTP. See the Webhook API reference.
Checklist
- Pro plan, webhook enabled with HTTP Client (Webhooks)
- Both scores in every update
- Quarter sent as a number, 5 for overtime
- Game clock as MM:SS or seconds
- Timeouts sent as the number left
- One source running the clock