ShotTrackerDeveloper

Unparalleled data set + realtime API = future of sports. Build with live tracking, stats, and broadcast-ready endpoints.

Authentication (Event API)

REST requests use HMAC request signing with a ShotTracker-issued username and secret. Live Data V2 WebSocket uses a subscription token only.

→ Authentication

External Data Ingestion

  • POST/v1/data— Ingest External Data

    External data ingestion endpoint for games. This endpoint is only supported with games.

    The request body is a JSON envelope with a single data field. The shape of the data object is defined between the consumer and ShotTracker for each integration.

Team Events And Schedules

Search and manage team events, game schedules, subscription tokens, practices, games, lineups, and video actions.

Live Data V2 Games

REST endpoints for catch-up and live game stats, play-by-play, shots, possessions, and ball screens (for WebSocket, see Live Data V2).

Teams

List teams, rosters, and officials. Replace or update team rosters.

Practice Stats

Team and player stats for practice, scrimmage, shooting drills, and workouts; includes shots and summaries.

Game Stats

Team and player stats for games (by event). Game shots and shot summaries.

Specific Period / Drill Stats

Stats, details, shots, and possessions for a specific period or drill by ID.

Sensors Locations

Sensor location data by ID and time range.

Web Callbacks

Register an HTTPS callback ShotTracker PUTs when live sessions, practices, or games start (and optionally end). Includes callback design requirements, query parameters, and notify management endpoints.

  • GET/v1/data/live/notify— List LIVE Notifies

    Returns all LIVE notify registrations for the authenticated consumer. Each item includes the notify id, action (LIVE), registered url, and whether end_notification is enabled. An empty notifications array means no LIVE notify is registered yet. See Create LIVE Notify for how to design the callback endpoint ShotTracker will PUT to.

  • PUT/v1/data/live/notify— Create LIVE Notify

    Registers your callback URL for LIVE notifications. On success the response has no body; the new notify id is returned in the X-ShotTracker-Notify-Id header. End notifications are disabled by default (end_notification: false); call Enable LIVE End Notify if you also want state=END callbacks.

    The url query parameter is required and must be URL-encoded. Use a base path with no query string. Only one LIVE notify is allowed per consumer.

    Designing your callback endpoint

    ShotTracker invokes your registered URL with an HTTP PUT when a live practice drill, practice, game round, or game starts (and optionally ends). Your service must expose a publicly reachable HTTPS endpoint that accepts that call.

    Request ShotTracker sends

    PUT {your-registered-url}?notify_id={notify id}&action=LIVE&data={id}&state={START|END}&type={SESSION|GAME|PRACTICE}

    Query ParameterDescription
    notify_idThe notify registration id returned in X-ShotTracker-Notify-Id when you created the notify
    actionAlways LIVE for Event API live notifies
    dataId of the activity that changed. For type=SESSION this is the session (drill / half / quarter) id. For type=PRACTICE this is the practice id. For type=GAME this is the game id
    stateSTART or END
    typeSESSION, GAME, or PRACTICE (see when notifies fire below)
    • Method is always PUT
    • Request body is empty
    • ShotTracker does not send HMAC or other auth headers on the callback; secure the URL yourself (path secret, network controls, etc.)
    • Query parameters are appended with ?. Register a URL without an existing query string (for example https://hooks.example.com/shottracker/live)

    Example: PUT https://hooks.example.com/shottracker/live?notify_id=abc-123&action=LIVE&data=45a64b38-b205-11ed-b27e-0242e9e2912e&state=START&type=GAME

    How your callback should behave

    1. Accept PUT on the exact path you registered.
    2. Respond quickly. ShotTracker uses short connect (~500 ms) and read (~1000 ms) timeouts. Acknowledge immediately (for example 204 No Content or 200 OK) and do heavier work asynchronously.
    3. Parse query parameters (notify_id, action, data, state, type). Use data with type to decide what to fetch next from the Event API (subscribe, search, catch-up, WebSocket, and so on).
    4. Treat the call as a signal, not a data payload. The callback does not include stats or box score; it tells you that something started or ended so you can call the Event API.
    5. Be idempotent. The same logical event should not break your system if delivered more than once.
    6. Failures are not retried. If your endpoint times out or returns an HTTP error, ShotTracker logs the failure and continues; it does not automatically retry that notification.

    Minimal Node.js callback (see also Code examples):

    const http = require("http"); const { URL } = require("url"); http.createServer((req, res) => { if (req.method !== "PUT") { res.writeHead(405); return res.end(); } const url = new URL(req.url, "http://localhost"); const notifyId = url.searchParams.get("notify_id"); const data = url.searchParams.get("data"); const state = url.searchParams.get("state"); const type = url.searchParams.get("type"); console.log({ notifyId, data, state, type }); res.writeHead(204); res.end(); }).listen(8080);

    When notifies fire

    typestateWhen it is sentValue of data
    SESSIONSTARTA practice drill (for example scrimmage or shooting) or a game round (half / quarter) startsSession id
    SESSIONENDThat practice or game-round session ends (only if end notify is enabled)Session id
    PRACTICESTARTA practice is started for the first timePractice id
    PRACTICEENDA practice ends (only if end notify is enabled)Practice id
    GAMESTARTA game enters pregame / live startGame id
    GAMEENDGame play ends (only if end notify is enabled)Game id

    SESSION covers period- or drill-level activity. GAME / PRACTICE cover the overall event lifecycle.

    End notifications

    When you create a notify, end_notification is false. You only receive state=START callbacks until you call Enable LIVE End Notify. Use Disable LIVE End Notify to turn END callbacks off again.

    Registration rules

    • Requires the consumer NOTIFY scope
    • Only one LIVE notify may exist per consumer. Creating a second returns 422 with Notify action already exists
    • You are notified only for live activity your credentials are authorized to access (team and/or court / facility access)
    • URL-encode the url query parameter when registering or updating (for example https%3A%2F%2Fhooks.example.com%2Fshottracker%2Flive)
  • PUT/v1/data/live/notify/{notify_id}— Update LIVE Notify URL

    Replaces the callback URL for an existing LIVE notify. The notify id and end-notification setting are unchanged. The new url must be URL-encoded and should not include a query string.

  • DELETE/v1/data/live/notify/{notify_id}— Delete LIVE Notify

    Removes the LIVE notify registration. ShotTracker stops calling your callback. To receive notifies again, create a new registration.

  • PUT/v1/data/live/notify/{notify_id}/_enableEndNotify— Enable LIVE End Notify

    Turns on state=END callbacks for this notify (end_notification: true). Until this is called, ShotTracker only sends state=START notifications. After enabling, you also receive END for SESSION, PRACTICE, and GAME activity your consumer is authorized to see.

  • PUT/v1/data/live/notify/{notify_id}/_disableEndNotify— Disable LIVE End Notify

    Turns off state=END callbacks for this notify (end_notification: false). START notifications continue.

ShotTracker Facilities

List locations, court layouts, and nearest locations by lat/long.

System Data

System-level stats.