🎾 Live Score Scraper — Help & Data Reference

This guide explains the API, fields, and includes an in-browser explorer.

🛠 API Reference

GET /api/v1/scores — all cached matches; response includes tournament_id, last_updated, refresh_interval_seconds, match_count, matches[].
GET /api/v1/scores/court/<court_number> — same as above, filtered to one court.
GET /api/v1/match/<match_id> — single match lookup; 404 if not found.
GET or POST /api/v1/tourid/<new_tour_id> — switch the active tournament being scraped (numeric only).

Examples:

curl -s http://localhost:5000/api/v1/scores | jq '.match_count, .last_updated'
curl -s http://localhost:5000/api/v1/scores/court/3 | jq '.matches[] | {matchid, court, matchstatus}'
curl -s http://localhost:5000/api/v1/match/12345 | jq
curl -X POST http://localhost:5000/api/v1/tourid/7140 | jq

Notes: all endpoints return JSON; errors include an error field; timestamps are Unix seconds in the match objects and a formatted string in last_updated.

⚡ API Explorer (in-browser)

Run a request against this server directly from your browser.

Endpoint Method Body (JSON for POST)

Response will appear here…

📑 API Output Fields

Top-level (GET /api/v1/scores)

status: success or error text.
filter: description of court filter applied.
tournament_id: current tournament being scraped.
last_updated: latest match timestamp (formatted string).
refresh_interval_seconds: scraper interval.
match_count: number of matches returned.
matches: array of match objects (see below).

Match object (common fields)

matchid (string): unique match id.
matchname (string): display title.
court (string): court label/number.
matchstatus (string): IN PROGRESS, COMPLETED, UPCOMING/PLAN, TEST.
timestamp (int): Unix seconds of last update for this match.
is_plan (int): 1 if planned/upcoming; 0 otherwise.
schedtime (string): scheduled start time (may be empty).
winner (string/int): winner flag; winner_name (string): name if completed.
player1, player2: player display names.
player1_country, player2_country: 3-letter country codes.
player1_full, player2_full, player1_surname, player2_surname: raw name fields as provided.
sets_played_count: number of sets reported (may be 0 for planned).
game1, game2: current game score for p1/p2 (live only).
player2serve: "1" means p1 serving, "2" means p2 serving.
lastservetype: raw serve type flag (if present).
tournid, eventid, extmid: source identifiers.
cam, cameraurl, camerarooturl: camera metadata if provided.
stats_general, stats_match: stats availability flags.

Set fields

For each set N (1..11): setN_p1, setN_p2 are set games; setN_tb is tie-break value when relevant.

Single-match endpoint

GET /api/v1/match/<match_id> returns { status, match } or 404 with { error }.

Tournament switch

GET/POST /api/v1/tourid/<new_tour_id> returns { status, message, new_tournament_id }; errors include { error }.

🎬 Selecting a Match for Scoreboard/Bug

Overlays pick a match in this order:

?matchid=123 in the URL forces that match (if it exists).
No matchid + exactly one live or warm-up match ⇒ that match is used automatically.
Multiple live matches without matchid ⇒ overlays may stay empty; pass a matchid.

Examples:

Scoreboard: /caspar/scoreboard/?matchid=12345
Bug:        /caspar/bug/?matchid=12345

# Quick links from dashboard cards:
# - Bug button: adds matchid automatically
# - Scoreboard button: adds matchid automatically

Tip: Use the dashboard card buttons (“Bug” or “Scoreboard”) to open the overlay with matchid pre-filled.

🎛 vMix Serve Script Guide

The vMix script in this repo (file: vmix/scripting) automatically toggles serve indicators in your scoreboard title based on live API data.

What you need in vMix first

A title input named SCOREBOARD (or change SCOREBOARD variable in script).
A text field in that title called MATCHID.Text containing the current match ID.
Two image layers named SERVE_1.Source and SERVE_2.Source.

How to install and run in vMix

Open vMix and go to Settings → Scripting.
Create a new script and paste the contents of vmix/scripting.
Set SCOREBOARD to your title input name if different from default.
Set API_BASE_URL to your server, for example https://scores.nkpa.co.uk/api/v1/match or your local endpoint.
Save and click Start for the script.
Update MATCHID.Text on the scoreboard input to the match you want to track.

What the script is doing

Runs an infinite loop and polls every 500ms.
Reads MATCHID.Text from the SCOREBOARD title input.
Calls /api/v1/match/<matchid> to get match JSON.
Extracts player2serve from the JSON response.
If value is 1: shows SERVE_1.Source, hides SERVE_2.Source.
If value is 2: hides SERVE_1.Source, shows SERVE_2.Source.
For missing/invalid value: hides both serve indicators.
Only performs visibility updates when the serve value changes, to reduce unnecessary commands.

Troubleshooting

If console shows Scoreboard input not found, check the input name matches SCOREBOARD.
If console shows Match ID not found, ensure MATCHID.Text exists and is populated.
If indicators never change, verify API reachability by opening /api/v1/match/<matchid> in a browser and checking player2serve.

Quick copy: vMix script

Use this when you need to paste directly into Settings -> Scripting in vMix.

' ============================================================
' Serve Indicator Automation Script for vMix
' ============================================================
' Copyright (c) 2025 Nathan Silveston. All rights reserved.
'
' Description: Automated serve indicator control that reads
'              player2serve data from the tennis score API
'              hosted at https://scores.nkpa.co.uk
'              and displays the appropriate serve bug.
'              MatchID is read from a text field in the
'              specified SCOREBOARD title input.
'
' Author: Nathan Silveston (nathan@nkpa.co.uk)
' Created: December 2025
' Version: 1.0
'
' Usage: Add this script to vMix and set SCOREBOARD and
'        API_BASE_URL variables to match your setup.
' ============================================================

Dim SCOREBOARD As String = "SCOREBOARD"
Dim API_BASE_URL As String = "https://scores.nkpa.co.uk/api/v1/match"
Dim lastServeValue As String = ""
Dim currentServeStatus As String = "unknown"

Console.WriteLine("========== SCRIPT INITIALIZED ==========")
Console.WriteLine("[INIT] Serve indicator script starting...")

' Check initial state of serve sources
Try
    Dim scoreboardInput = Input.Find(SCOREBOARD)
    If scoreboardInput IsNot Nothing Then
        Console.WriteLine("[INIT] SCOREBOARD input found")
        Console.WriteLine("[INIT] Checking initial visibility states...")
        Console.WriteLine("[INIT] SERVE_1.Source - Initial state: checking...")
        Console.WriteLine("[INIT] SERVE_2.Source - Initial state: checking...")
    Else
        Console.WriteLine("[INIT] WARNING: SCOREBOARD input not found at startup")
    End If
Catch ex As Exception
    Console.WriteLine("[INIT] Error during startup check: " & ex.Message)
End Try

Console.WriteLine("[INIT] Script ready and monitoring for changes")
Console.WriteLine("========================================")

While True
    System.Threading.Thread.Sleep(500)
    Try
        ' Get the scoreboard input to read the match ID
        Dim scoreboardInput = Input.Find(SCOREBOARD)

        If scoreboardInput Is Nothing Then
            Console.WriteLine("Scoreboard input not found")
        Else
            ' Read the match ID from the text field
            Dim matchId As String = scoreboardInput.Text("MATCHID.Text")

            If String.IsNullOrEmpty(matchId) Then
                Console.WriteLine("Match ID not found in scoreboard")
            Else
                ' Fetch the match data from the API using WebRequest
                Dim url As String = API_BASE_URL & "/" & matchId
                Dim client = System.Net.WebRequest.Create(url)
                Dim response = client.GetResponse()

                If response IsNot Nothing Then
                    Dim sr As System.IO.StreamReader = New System.IO.StreamReader(CType(response.GetResponseStream(), System.IO.Stream))
                    Dim jsonContent As String = sr.ReadToEnd()
                    sr.Close()

                    ' Parse player2serve from JSON string manually
                    Dim serveValue As String = ""
                    Dim startIndex As Integer = jsonContent.IndexOf("""player2serve""")

                    If startIndex > -1 Then
                        startIndex = jsonContent.IndexOf(":", startIndex) + 1
                        Dim endIndex As Integer = jsonContent.IndexOf(",", startIndex)
                        If endIndex = -1 Then
                            endIndex = jsonContent.IndexOf("}", startIndex)
                        End If
                        serveValue = jsonContent.Substring(startIndex, endIndex - startIndex).Trim()
                        serveValue = serveValue.Replace("""", "").Trim()
                    End If

                    ' Only log and update if serve value changed
                    If serveValue <> lastServeValue Then
                        Console.WriteLine("[CHANGE] Serve value changed from '" & lastServeValue & "' to '" & serveValue & "'")
                        lastServeValue = serveValue

                        If serveValue = "1" Then
                            ' Player 1 (TOP) is serving
                            Console.WriteLine("[ACTION] Player 1 serving detected")
                            Console.WriteLine("[VISIBLE] Showing SERVE_1.Source")
                            API.Function("SetImageVisibleOn", Input:=SCOREBOARD, SelectedName:="SERVE_1.Source")
                            Console.WriteLine("[STATE] SERVE_1.Source is now: VISIBLE")
                            Console.WriteLine("[HIDDEN] Hiding SERVE_2.Source")
                            API.Function("SetImageVisibleOff", Input:=SCOREBOARD, SelectedName:="SERVE_2.Source")
                            Console.WriteLine("[STATE] SERVE_2.Source is now: HIDDEN")
                            currentServeStatus = "Player 1"
                        ElseIf serveValue = "2" Then
                            ' Player 2 (BOTTOM) is serving
                            Console.WriteLine("[ACTION] Player 2 serving detected")
                            Console.WriteLine("[HIDDEN] Hiding SERVE_1.Source")
                            API.Function("SetImageVisibleOff", Input:=SCOREBOARD, SelectedName:="SERVE_1.Source")
                            Console.WriteLine("[STATE] SERVE_1.Source is now: HIDDEN")
                            Console.WriteLine("[VISIBLE] Showing SERVE_2.Source")
                            API.Function("SetImageVisibleOn", Input:=SCOREBOARD, SelectedName:="SERVE_2.Source")
                            Console.WriteLine("[STATE] SERVE_2.Source is now: VISIBLE")
                            currentServeStatus = "Player 2"
                        Else
                            ' No serve data - hide both
                            Console.WriteLine("[ACTION] No serve data or invalid value")
                            Console.WriteLine("[HIDDEN] Hiding SERVE_1.Source")
                            API.Function("SetImageVisibleOff", Input:=SCOREBOARD, SelectedName:="SERVE_1.Source")
                            Console.WriteLine("[STATE] SERVE_1.Source is now: HIDDEN")
                            Console.WriteLine("[HIDDEN] Hiding SERVE_2.Source")
                            API.Function("SetImageVisibleOff", Input:=SCOREBOARD, SelectedName:="SERVE_2.Source")
                            Console.WriteLine("[STATE] SERVE_2.Source is now: HIDDEN")
                            currentServeStatus = "None"
                        End If
                        Console.WriteLine("[UPDATE] Current status now: " & currentServeStatus)
                    End If

                    response.Close()
                Else
                    Console.WriteLine("Error fetching match data")
                End If
            End If
        End If

    Catch ex As Exception
        Console.WriteLine("Error: " & ex.Message)
    End Try
End While

🧾 Example Match JSON

{
  "matchid": "56789",
  "matchname": "Centre Court QF",
  "court": "1",
  "matchstatus": "IN PROGRESS",
  "timestamp": 1712505600,
  "is_plan": 0,
  "schedtime": "2025-12-13 14:00",
  "winner": null,
  "winner_name": null,
  "player1": "Alex Morton",
  "player2": "Diego Alvarez",
  "player1_country": "GBR",
  "player2_country": "ESP",
  "player1_surname": "Morton",
  "player2_surname": "Alvarez",
  "sets_played_count": 2,
  "game1": "30",
  "game2": "15",
  "player2serve": "2",
  "set1_p1": 6,
  "set1_p2": 4,
  "set2_p1": 3,
  "set2_p2": 6,
  "set2_tb": "0",
  "set3_p1": null,
  "set3_p2": null,
  "tournid": "7140",
  "eventid": "E123",
  "extmid": "EXT-56789",
  "cam": null,
  "cameraurl": null,
  "camerarooturl": null,
  "stats_general": 1,
  "stats_match": 1
}