G League API Basics

This page covers the practical basics of the NBA G League API: authentication, URL structure, formats and languages, errors, and cache behavior. The concepts behind the feeds (the season model, league structure, game feeds, and coverage) are on G League Fundamentals; the payloads themselves are covered in the scenario pages.

Authentication

Every request is authenticated with your API key in the x-api-key header:

GET https://api.sportradar.com/nbdl/trial/v8/en/league/hierarchy.json
x-api-key: YOUR_API_KEY

Keep the key server-side; do not embed it in client applications.

Base URL and URL Structure

All requests follow one URL shape:

GET https://api.sportradar.com/nbdl/{access_level}/v8/{language_code}/{feed}.{format}

access_level: trial or production, matching your key.
language_code: en. English is the supported language for the NBA G League API.
format: json or xml. Both carry the same data on every feed.

Feeds are scoped three ways:

League-wide feeds live under /league/ (Seasons, Hierarchy, Teams, Injuries, Free Agents, and the date-scoped Transfers and Change Log)
Season-scoped feeds take a {season_year}/{season_type} pair (Schedule, Standings, Rankings, Leaders, Seasonal Statistics, Series Schedule); the season model and full type list are on G League Fundamentals
Entity-scoped feeds take a GUID (Game Summary, Boxscore, and Play-by-Play by game ID; Team and Player Profiles; Series Statistics)

Complete Responses

Feeds return the complete data set for their scope in a single response; there is no pagination. A full-season Schedule returns every game (561 for the 2025-26 regular season), and Free Agents returns the entire league-wide list in one payload.

Errors

Authentication failures return 403 with an HTML page, not a JSON or XML error object; branch on the status code:

<!DOCTYPE html>
      <html lang="en">
        <head>
          <meta charset="utf-8">
          <title>Authentication Error</title>
        </head>
        <body>
          <p>Authentication Error</p>
        </body>
      </html>

Rate-limit errors return 429 Too Many Requests; slow your request rate and retry, increasing the wait between attempts
404 indicates an unknown ID or path
Other statuses follow the Response Codes page

Cache Behavior

Each response carries a cache-control header stating how long the payload may be served from cache. TTLs are tiered by feed family: roughly 10 minutes on schedules and standings, 15 minutes on rankings, leaders, and statistics, and several hours on the league catalog and completed-game feeds. The per-feed chart is on the Update Frequencies page.

⚠️
A TTL Is Not a Polling Recommendation
A short TTL means the payload can change that often, not that you should request it that often. Check the header on each response you receive, and match your polling cadence to the freshness your product actually needs. Recommended cadences are on the Update Frequencies page and in each scenario's Best Practices.

Time Values

Timestamps are UTC ISO 8601 (scheduled values carry an explicit offset). Date-scoped feeds (Daily Schedule, Daily Transfers, Daily Change Log) use the US Eastern date, matching the league's calendar: a change-log day runs from midnight to midnight Eastern, which is 05:00Z to 05:00Z in winter and 04:00Z to 04:00Z during daylight saving time, and an evening game whose scheduled timestamp is 2026-01-16T00:00:00+00:00 belongs to the January 15 Daily Schedule. Plan date math accordingly.