ScoreHub

API

How to use the API (no experience needed)

What is an API? It is a web address that gives you scores as plain data instead of a web page. Software such as a scorebug or graphics program can read that data on its own, so you never have to retype a score. If you only want to look at scores, you do not need the API at all: use the Scores page.

Step 1 - Try it in your browser

Copy this address into a new browser tab. The browser will show a block of text, and that text is the API's answer:

http://ajssurfacebook3.tail62af76.ts.net/api/v1/games

That is a list of games. Each item has its teams, score, period and status. The text is in a format called JSON: names in quotes, each followed by its value. You can read it like a form, for example "status": "live" means the game is live. Nothing is changed by just looking.

Step 2 - Find a game's ID

Every game has a number called its ID. Open a game on the Scores page and look at the address bar: in http://ajssurfacebook3.tail62af76.ts.net/game/5 the ID is 5. You can also find it as "id" in the list from Step 1.

Step 3 - Get one game for your scorebug

Put the ID into this address (swap 5 for your game's ID):

http://ajssurfacebook3.tail62af76.ts.net/api/v1/games/5/scorebug

This gives simple, flat fields (home score, away score, period and so on) that scorebug software understands. Add ?format= and pick the one your software wants:

In your scorebug software, look for a setting like data source, URL or web feed, paste the address in, and set it to refresh every few seconds. The score is current every time the software asks.

Just want the graphic? Skip the API: add http://ajssurfacebook3.tail62af76.ts.net/overlay/5 as a Browser Source in OBS or vMix. It shows a ready-made scorebug that updates by itself.

Step 4 - Narrow down the list (optional)

Add filters to the end of the games address. Start with ?, and join extra filters with &:

About dates: date= means that calendar day in the site's local timezone, so a Friday 7 PM kickoff is found under Friday. If your games are in a different timezone, add it to the address, for example &tz=America/Chicago. Admins can change the default with the timezone setting.

Step 4b - One feed for all the teams you follow

If you have an account, you do not need a separate address for every game. Follow your teams on the My teams page, then use your username as your ID (swap yourname for it):

http://ajssurfacebook3.tail62af76.ts.net/api/v1/users/yourname/scorebug

That one address returns every game for the teams you follow, one row per game: live games first, then upcoming, then finished. It accepts the same ?format= choices as Step 3 and the same filters as Step 4, for example ?status=live. Add it to vMix (or any data-driven scorebug) as a single data source. .../users/yourname/games gives the full details instead. Your number ID works in place of the username, and both are shown on the My teams page.

Step 5 - API keys: when you need one

Reading scores works without any key, but the site limits how many requests you can send each minute. If you run into that limit, ask a site admin for a read key.

Changing a score through the API needs a write key. A key is a long password for your software; the admins create them. Send it with every request as a header named X-API-Key. Keep it private: anyone who has a write key can change scores. If a key leaks, tell an admin so it can be revoked.

Step 6 - Send a score (write key only)

Browsers cannot send data just by opening an address, so use a tool like curl (included with Windows 10/11 as curl.exe, and with macOS and Linux). Change the game ID, key and numbers to yours:

curl -X POST http://ajssurfacebook3.tail62af76.ts.net/api/v1/games/5/score -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" -d '{"home_score":14,"away_score":7,"period":"Q2"}'

You can send just the parts that changed. Valid periods depend on the sport (football: Q1, Q2, HT, Q3, Q4, OT, Final). If it works you get the updated game back; if not you get a short "error" message that says what to fix.

If something does not work

The tables below list every endpoint for developers.

Reference

Base URL: http://ajssurfacebook3.tail62af76.ts.net/api/v1. Reads are open (rate limited); an API key raises your limit. Writes need a write key. Send keys as X-API-Key: YOUR_KEY or Authorization: Bearer YOUR_KEY.

Read

EndpointWhat it returns
GET /gamesList games. Filters: sport, status (scheduled/live/final), date (YYYY-MM-DD, UTC), team, limit. Time window on the start time: from (inclusive) and to (exclusive), ISO timestamps; add include_live=1 to keep games that are live right now; order=desc for newest first or order=asc for strictly oldest first
GET /games/{id}One game
GET /games/{id}/scorebugFlat fields for scorebug software. ?format=json|csv|xml|text. JSON is a one-item list, like ScoreTrace's /scoretrace. Team colors: HomeColor/AwayColor (primary) and HomeColor2/AwayColor2 (secondary, empty if the school has none)
GET /users/{username}/gamesGames for every team that user follows, in one list (same shape and filters as /games). The username is the user's ID (not case-sensitive); the numeric user id also works. Unknown or disabled users give 404
GET /users/{username}/scorebugThe same games as flat scorebug rows, one per game, for vMix and similar. ?format=json|csv|xml|text (XML root is <scorebugs>; an empty follow list gives an empty list / header-only CSV). Same filters as /games
GET /games/{id}/historyScoring changes
GET /schools, /schools/{id}Schools: name, mascot, short, location, color, color2 (optional secondary color, empty if none), logo and the sports each has a team in (?sport=)
GET /teams, /teams/{id}A school's team in one sport (?sport=); includes the school fields
GET /stream?game={id}Server-Sent Events (event: score), pushed the moment a score changes

Write (write key)

POST /games/{id}/scoreJSON: home_score, away_score, period (Q1, Q2, HT, Q3, Q4, OT, Final...), status (scheduled/live/final) - send any subset. Status follows the period: no period = scheduled, Final = final, anything else = live. A status sent on its own is turned into the matching period. ScoreTrace keys (HomeScore, AwayScore, Period) also work.
POST /games{"sport","home_id","away_id","start_time","site","location"}. site is home (default), away or neutral; a neutral site needs location. Otherwise the game uses the host school's location.
POST /schools{"name","mascot","short","location","color","color2" (optional),"sports":["football","volleyball"]}
POST /teams{"school_id","sport"} adds a sport to an existing school
POST /games/{id}/suggestWebsite update form (same fields as above). Needs a signed-in user account by default. Applies instantly, or goes to the admin review queue, depending on public_updates in settings.json. Developers should use a write key with /score instead.

Accounts (website sessions)

Visitors can create an account to keep their own followed-teams list and to update scores or submit new teams. These endpoints use the website's login cookie, not API keys: POST /auth/register, /auth/login, /auth/logout, GET /me, GET|PUT|DELETE /me/teams/{id}, GET /games?following=1, POST /team-submissions, PUT /me/prefs (saved scoreboard filters).

Example

curl http://ajssurfacebook3.tail62af76.ts.net/api/v1/games?status=live
curl "http://ajssurfacebook3.tail62af76.ts.net/api/v1/games/1/scorebug?format=csv"
curl "http://ajssurfacebook3.tail62af76.ts.net/api/v1/users/yourname/scorebug?status=live"
curl -X POST http://ajssurfacebook3.tail62af76.ts.net/api/v1/games/1/score -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" -d '{"home_score":21,"period":"Q3"}'