NBA

Overview

The APRO AI Oracle API v2 provides comprehensive NBA basketball data aggregated from multiple trusted data providers (Sportradar, API-Sports, and RapidAPI). All endpoints require authentication via X-API-KEY and X-API-SECRET headers.

Base URL: https://api-ai-oracle.apro.com

Authentication Headers:

X-API-KEY: your-api-key
X-API-SECRET: your-api-secret

Data Verification: All responses include cryptographic signatures from multiple signers for data integrity verification.

Workflow1: Get latest teams list by /v2/sport/nba/teams firstly, then use the date and team name to get game result by /v2/sport/nba/game.

Workflow2: Use /v2/sport/nba/schedule to get the games list, then select one game id to get game result by /v2/sport/nba/game.

---

Endpoints

1. Get Teams

Route: GET /v2/sport/nba/teams

Credits: 1 API calls per request

Description: Returns the complete list of NBA teams with their identifiers across all data providers.

Query Parameters: None

Example Request:

curl -H "X-API-KEY: your-api-key" \
     -H "X-API-SECRET: your-secret" \
     "https://api-ai-oracle.apro.com/v2/sport/nba/teams"

Example Response:

{
    "status": {
        "timestamp": 1768268010994,
        "code": 200,
        "message": ""
    },
    "data": {
        "count": 30,
        "teams": [
            {
                "id": 1,
                "name": "Atlanta Hawks",
                "code": "ATL"
            },
            {
                "id": 2,
                "name": "Brooklyn Nets",
                "code": "BKN"
            },
            {
                "id": 3,
                "name": "Boston Celtics",
                "code": "BOS"
            }
        ]
    }
}

2. Get Daily Schedule

Route: GET /v2/sport/nba/schedule

Credits: 5 API calls per request

Description: Returns all NBA games scheduled for a specific date (in Eastern Time).

Query Parameters:

Parameter	Type	Required	Description	Example
date	string	Optional	Date in YYYY-MM-DD format (Eastern Time). If omitted, returns today’s schedule.	2026-01-04

Date Range Restrictions:

• Can query schedules from the past 3 years

• Can query schedules up to 1 year in the future

• Request by American Eastern Date, the schedule time in the response data will be UTC time

Example Request:

curl -H "X-API-KEY: your-api-key" \
     -H "X-API-SECRET: your-secret" \
     "https://api-ai-oracle.apro.com/v2/sport/nba/schedule?date=2026-01-04"

Example Response:

{
    "status": {
        "timestamp": 1736698800000,
        "code": 200,
        "message": ""
    },
    "data": {
        "date": "2026-01-04T00:00:00-05:00",
        "games": [
            {
                "id": "44ffce43-4a55-4816-a2e8-5c0bbc500214",
                "date": "2026-01-04T00:00:00-05:00",
                "status": "closed",
                "home_team": {
                    "id": 6,
                    "name": "Cleveland Cavaliers",
                    "code": "CLE",
                    "sportradar_id": "583ec773-fb46-11e1-82cb-f4ce4684ea4c"
                },
                "away_team": {
                    "id": 9,
                    "name": "Detroit Pistons",
                    "code": "DET",
                    "sportradar_id": "583ec928-fb46-11e1-82cb-f4ce4684ea4c"
                },
                "venue": "Rocket Arena",
                "scheduled": "2026-01-04T19:00:00Z"
            }
        ],
        "count": 8,
        "timestamp": "2026-01-12T10:00:00Z",
        "signatures": [
            {
                "signer": "0xf3xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
                "hash": "0xabxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
                "signature": "0xeexxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
                "timestamp": 1767157946010
            }
        ]
    }
}

3. Get Games Result

Route: GET /v2/sport/nba/games

Credits: 10 API calls per request

Description: The Games endpoint returns all NBA games for a specified date with scores and multi-provider verification. This is a batch endpoint optimized for fetching multiple games efficiently.

Query Parameters:

Parameter	Type	Required	Description	Example
date	string	No	Game date in Eastern Time (YYYY-MM-DD). Defaults to today.	2026-01-25

Date Range Restrictions:

• Can query games from the past 3 years

• Can query games up to 1 year in the future

Example Request:

curl -X GET "https://api-ai-oracle.apro.com/v2/sport/nba/games?date=2026-01-25" \
  -H "X-API-KEY: your-api-key" \
  -H "X-API-SECRET: your-api-secret"

Example Response:

{
    "status": {
        "timestamp": 1769408207893,
        "code": 200,
        "message": ""
    },
    "data": {
        "date": "2026-01-25",
        "games": [
            {
                "game_id": "e1cadb5d-1c23-4941-816c-5f93b07792ed",
                "scheduled": "2026-01-25T20:00:00Z",
                "status": "closed",
                "home_team": "Detroit Pistons",
                "away_team": "Sacramento Kings",
                "home_score": 139,
                "away_score": 116,
                "venue": "Little Caesars Arena",
                "verified": true,
                "providers": [
                    {
                        "provider": "sportradar",
                        "home_team": "Detroit Pistons",
                        "away_team": "Sacramento Kings",
                        "home_score": 139,
                        "away_score": 116,
                        "status": "closed"
                    },
                    {
                        "provider": "rapidapi",
                        "home_team": "Detroit Pistons",
                        "away_team": "Sacramento Kings",
                        "home_score": 139,
                        "away_score": 116,
                        "status": "closed"
                    }
                ]
            }
        ],
        "count": 8,
        "verified": 8,
        "timestamp": "2026-01-26T14:16:47.892169137+08:00",
        "signatures": [
            {
                "signer": "0xf3xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
                "hash": "0xabxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
                "signature": "0xeexxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
                "timestamp": 1767157946010
            }
        ]
    }
}

Response Fields:

Top-Level Data Object

Field	Type	Description
date	string	Query date in Eastern Time (YYYY-MM-DD)
games	array	List of games
count	integer	Total number of games
verified	integer	Number of verified games
timestamp	string	Response timestamp (ISO 8601)
signatures	array	Cryptographic signatures for data verification

Game Object

Field	Type	Description
game_id	string	Unique game identifier (Sportradar ID)
scheduled	string	Scheduled start time (UTC, ISO 8601)
status	string	Game status: scheduled, live, closed, cancelled
home_team	string	Home team name
away_team	string	Away team name
home_score	integer	Home team score
away_score	integer	Away team score
venue	string	Arena/stadium name
verified	boolean	true if verified by at least 2 providers
providers	array	Raw data from each provider

Provider Object

Field	Type	Description
provider	string	Provider name: sportradar, apisports, rapidapi
home_team	string	Home team name (provider’s format)
away_team	string	Away team name (provider’s format)
home_score	integer	Home team score
away_score	integer	Away team score
status	string	Game status (provider’s raw status)

Game Status Values

Status	Description
scheduled	Game has not started
live	Game is in progress
closed	Game has ended
cancelled	Game is postponed, cancelled, or suspended

Status Mapping

The following raw statuses are normalized:

Raw Status	Normalized
scheduled, NS, notstarted, pre-game, pregame	scheduled
inprogress, halftime, Q1, Q2, Q3, Q4, OT	live
closed, complete, final, FT	closed
postponed, cancelled, suspended, delayed, PST	cancelled

4. Get Game Result

Route: GET /v2/sport/nba/game

Credits: 5 API calls per request

Description: Returns detailed game results with scores, verified by multiple data providers (2-of-3 verification).

Query Parameters:

Parameter	Type	Required	Description	Example
game_id	string	Optional*	Sportradar game identifier	44ffce43-4a55-4816-a2e8-5c0bbc500214
date	string	Optional*	Date in YYYY-MM-DD format (Eastern Time)	2026-01-04
home_team	string	Optional*	Home team name or code	Cleveland Cavaliers or CLE
away_team	string	Optional*	Away team name or code	Detroit Pistons or DET

Query Methods:

1. By game_id: Provide game_id (recommended, most efficient)

2. By teams and date: Provide date, home_team, and away_team

*At least one query method must be provided. Currently, only live (in-progress) and completed games are supported.

Date Range Restrictions:

• Can query games from the past 3 years

• Can query games up to 1 year in the future

Example Request (by game_id):

curl -H "X-API-KEY: your-api-key" \
     -H "X-API-SECRET: your-secret" \
     "https://api-ai-oracle.apro.com/v2/sport/nba/game?game_id=44ffce43-4a55-4816-a2e8-5c0bbc500214"

Example Request (by teams and date):

curl -H "X-API-KEY: your-api-key" \
     -H "X-API-SECRET: your-secret" \
     "https://api-ai-oracle.apro.com/v2/sport/nba/game?date=2026-01-04&home_team=CLE&away_team=DET"

Example Response:

{
    "status": {
        "timestamp": 1768268523304,
        "code": 200,
        "message": ""
    },
    "data": {
        "result": {
            "game_id": "44ffce43-4a55-4816-a2e8-5c0bbc500214",
            "date": "2026-01-04T19:00:00Z",
            "status": "closed",
            "home_team": {
                "id": 6,
                "name": "Cleveland Cavaliers",
                "code": "CLE",
                "sportradar_id": "583ec773-fb46-11e1-82cb-f4ce4684ea4c"
            },
            "away_team": {
                "id": 9,
                "name": "Detroit Pistons",
                "code": "DET",
                "sportradar_id": "583ec928-fb46-11e1-82cb-f4ce4684ea4c"
            },
            "home_score": 110,
            "away_score": 114,
            "venue": "",
            "completed": true
        },
        "providers": [
            {
                "provider_name": "sportradar",
                "result": {
                    "game_id": "44ffce43-4a55-4816-a2e8-5c0bbc500214",
                    "date": "2026-01-04T19:00:00Z",
                    "status": "closed",
                    "home_team": {
                        "id": 6,
                        "name": "Cleveland Cavaliers",
                        "code": "CLE",
                        "sportradar_id": "583ec773-fb46-11e1-82cb-f4ce4684ea4c"
                    },
                    "away_team": {
                        "id": 9,
                        "name": "Detroit Pistons",
                        "code": "DET",
                        "sportradar_id": "583ec928-fb46-11e1-82cb-f4ce4684ea4c"
                    },
                    "home_score": 110,
                    "away_score": 114,
                    "venue": "",
                    "completed": true
                }
            },
            {
                "provider_name": "apisports",
                "result": {
                    "game_id": "469969",
                    "date": "2026-01-04T19:00:00Z",
                    "status": "closed",
                    "home_team": {
                        "id": 6,
                        "name": "Cleveland Cavaliers",
                        "code": "",
                        "apisports_id": 137
                    },
                    "away_team": {
                        "id": 9,
                        "name": "Detroit Pistons",
                        "code": "",
                        "apisports_id": 140
                    },
                    "home_score": 110,
                    "away_score": 114,
                    "venue": "",
                    "completed": true
                }
            }
        ],
        "verified": true,
        "timestamp": "2026-01-13T09:42:03.303157831+08:00",
        "signatures": [
            {
                "signer": "0xf3xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
                "hash": "0xabxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
                "signature": "0xeexxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
                "timestamp": 1767157946010
            }
        ]
    }
}

Response Fields:

• verified: Boolean indicating if the result was verified by at least 2 of 3 providers

• providers: Array of results from each data provider for transparency

• result: The aggregated, verified game result

5. Get Play-by-Play

Route: GET /v2/sport/nba/pbp

Credits: 5 API calls per request

Description: Returns real-time play-by-play event data for a specific NBA game, with cross-provider verification. Each event from the primary source (Sportradar) is matched against secondary source (RapidAPI) to ensure data accuracy.

Query Parameters

Parameter	Type	Required	Description	Example
game_id	string	Required	Unique game identifier (Sportradar format)	df603a98-aa2f-4613-82c5-44b4dfd47cde

Example Request

curl -X GET "https://api-ai-oracle.apro.com/v2/sport/nba/pbp?game_id=df603a98-aa2f-4613-82c5-44b4dfd47cde" \
  -H "X-API-KEY: your-api-key" \
  -H "X-API-SECRET: your-api-secret"

Example Response

{
    "status": {
        "timestamp": 1768379567196,
        "code": 200,
        "message": ""
    },
    "data": {
        "play_by_play": {
            "game_id": "df603a98-aa2f-4613-82c5-44b4dfd47cde",
            "date": "2026-01-10T00:00:00Z",
            "status": "closed",
            "home_team": {
                "id": 22,
                "name": "Orlando Magic",
                "code": "ORL"
            },
            "away_team": {
                "id": 23,
                "name": "Philadelphia 76ers",
                "code": "PHI"
            },
            "current_period": 4,
            "current_clock": "00:00",
            "events": [
                {
                    "id": "e82b9360-1262-44a0-8be4-ef16ca00a0bf",
                    "period": 1,
                    "clock": "12:00",
                    "type": "opentip",
                    "description": "Joel Embiid vs. Wendell Carter Jr. (Desmond Bane gains possession)",
                    "team_id": "583ed157-fb46-11e1-82cb-f4ce4684ea4c",
                    "home_score": 0,
                    "away_score": 0,
                    "timestamp": "2026-01-10T00:11:05Z",
                    "matched_event": {
                        "provider": "rapidapi",
                        "id": "4018103884",
                        "type": "Jumpball",
                        "description": "Joel Embiid vs. Wendell Carter Jr. (Desmond Bane gains possession)"
                    }
                },
                {
                    "id": "560be649-6ed1-49a1-8af2-0d21c1c19b29",
                    "period": 1,
                    "clock": "11:44",
                    "type": "twopointmade",
                    "description": "Wendell Carter Jr. makes two point cutting dunk (Paolo Banchero assists)",
                    "team_id": "583ed157-fb46-11e1-82cb-f4ce4684ea4c",
                    "home_score": 2,
                    "away_score": 0,
                    "timestamp": "2026-01-10T00:11:18Z",
                    "matched_event": {
                        "provider": "rapidapi",
                        "id": "4018103887",
                        "type": "Cutting Dunk Shot",
                        "description": "Wendell Carter Jr. makes 1-foot dunk (Paolo Banchero assists)"
                    }
                }
            ]
        },
        "verified": true,
        "timestamp": "2026-01-14T16:32:47.196285+08:00",
        "signatures": [
            {
                "signer": "0xf3xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
                "hash": "0xabxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
                "signature": "0xeexxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
                "timestamp": 1767157946010
            }
        ]
    }
}

Response Fields

Top Level

• status: API response status with timestamp and code

• data: Contains the play-by-play data and verification status

play_by_play Object

Field	Type	Description
game_id	string	Unique identifier for the game
date	string	Game date in ISO 8601 format
status	string	Game status (scheduled, live, halftime, closed)
home_team	object	Home team information (id, name, code)
away_team	object	Away team information (id, name, code)
current_period	integer	Current quarter/period (1-4, 5+ for overtime)
current_clock	string	Current game clock (MM:SS format)
events	array	Array of play-by-play events

Event Object

Field	Type	Description
id	string	Unique event identifier
period	integer	Quarter number (1-4, 5+ for OT)
clock	string	Game clock at event time (MM:SS)
type	string	Event type (see Event Types below)
description	string	Human-readable event description
team_id	string	Sportradar team ID (nullable)
home_score	integer	Home team score after event
away_score	integer	Away team score after event
timestamp	string	Event timestamp in ISO 8601 format
matched_event	object	Cross-verified event from secondary provider (nullable)

matched_event Object

Field	Type	Description
provider	string	Secondary data provider name (e.g., “rapidapi”)
id	string	Event ID from secondary provider
type	string	Event type as reported by secondary provider
description	string	Event description from secondary provider

Verification Fields

Field	Type	Description
verified	boolean	true if events have been cross-verified with secondary provider
timestamp	string	Response generation timestamp

Event Types

Type	Description
startperiod	Start of a quarter/period
endperiod	End of a quarter/period
opentip	Jump ball / tip-off
twopointmade	Two-point field goal made
twopointmiss	Two-point field goal missed
threepointmade	Three-point field goal made
threepointmiss	Three-point field goal missed
freethrowmade	Free throw made
freethrowmiss	Free throw missed
rebound	Offensive or defensive rebound
turnover	Turnover
steal	Steal
block	Blocked shot
assist	Assist (included in scoring event description)
personalfoul	Personal foul
shootingfoul	Shooting foul
technicalfoul	Technical foul
flagrantfoul	Flagrant foul
teamtimeout	Team timeout
officialtimeout	Official timeout
lineupchange	Substitution
stoppage	Game stoppage

Data Verification

Play-by-play data is aggregated from multiple providers:

• Primary Source: Sportradar (real-time event stream)

• Secondary Source: RapidAPI (cross-verification)

Events are matched between providers using:

1. Period and game clock alignment

2. Event type correlation

3. Description similarity analysis

The verified field is true when sufficient events are successfully matched between providers.

Notes

• For live games, there may be a slight delay (1-3 minutes) between providers, resulting in recent events without matched_event

• Completed games (status: "closed") typically achieve 90%+ event match rates

• Events like lineupchange, stoppage, and startperiod may not have matches as they’re not consistently reported across providers

Response Format

All endpoints return responses in the following structure:

{
  "status": {
    "timestamp": 1736698800000,
    "code": 200,
    "message": ""
  },
  "data": {
    // Endpoint-specific data
  }
}

Status Codes

Code	Description
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API credentials
404	Not Found - Game or data not found
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Error Response Format

{
  "status": {
    "timestamp": 1736698800000,
    "code": 400,
    "message": "date must be within the last 3 years"
  }
}

Data Verification

The NBA API uses a 2-of-3 verification system to ensure data accuracy:

1. Multiple Providers: Data is sourced from three independent providers:

   • Sportradar (primary)

   • API-Sports

   • RapidAPI

2. Verification Process:

   • Game results must match from at least 2 providers

   • The verified field in responses indicates successful verification

   • Individual provider results are included for transparency

3. Cryptographic Signatures:

   • All responses include signatures from multiple signers

   • Enables verification of data integrity and authenticity

Best Practices

1. Use game_id when available: More efficient than querying by team names

2. Cache team data: Team list rarely changes

3. Respect rate limits: Implement exponential backoff for retries

4. Verify data: Check the verified field in game results

5. Date format: Always use YYYY-MM-DD format for date parameters

---