canonical: https://jentic.com/apis/auth.api.geniussports.com/genius-sports

# Auth Api Geniussports Genius Sports Data API

Jentic publishes the only available OpenAPI specification for Genius Sports Data API, keeping it validated and agent-ready. Genius Sports is an official data and technology partner for major sports leagues, and its Data API provides real-time and historical match-state, fixture, and statistics feeds for American Football, Basketball, Football (Soccer), and Tennis. The spec covers the OAuth 2.0 token endpoint at auth.api.geniussports.com plus the data endpoints on platform.matchstate.api.geniussports.com and statistics.api.geniussports.com. Both an OAuth access token and an x-api-key are required on data calls.

## For AI agents

Get OAuth tokens, then pull real-time enhanced match state, fixture details, and statistics for football, basketball, soccer, and tennis using both an access token and an x-api-key.

## Scope

Does not handle odds calculation, betting markets, or video streams - use for Genius Sports authentication, match state, fixtures, and statistics only.

## Capabilities

- Exchange client credentials for an OAuth 2.0 access token via POST `/oauth2/token`
- Pull enhanced live match state for a fixture via the matchstate endpoint
- Retrieve fixture metadata and scheduling for a sport and source
- Read live and historical statistics for a fixture by sport ID and fixture ID
- Cover American Football, Basketball, Football (Soccer), and Tennis from a single auth flow
- Combine OAuth and x-api-key headers for tiered access control

## Use cases

### Live in-play data for sportsbooks

Sportsbooks and odds-modelling tools need real-time match state to keep markets priced. POST `/oauth2/token` issues an access token; the matchstate endpoint then returns enhanced state by source, sportId, and fixtureId for football, basketball, soccer, and tennis. The pricing engine consumes the feed and adjusts markets within the latency window the league allows.

Example prompt: Authenticate via POST `/oauth2/token`, then call GET `/api/v2/sources/{source}/sports/{sportId}/fixtures/{fixtureId}/liveaccess/matchstate/enhanced` for the active fixture and emit each state change to a pricing queue.

### Editorial fixture and statistics widgets

Sports media sites and broadcasters use Genius Sports to power live scores, fixture lists, and player statistics. The fixtures endpoint returns scheduling and team context, while the statistics endpoint returns box-score-style metrics that drive on-page widgets. Both calls authenticate against auth.api.geniussports.com once and share the same x-api-key for the editorial product.

Example prompt: After obtaining a token, GET the fixture by source and sportId, then GET the statistics for the same fixtureId and render a JSON payload for the page.

### Historical data extraction for analytics

Quant teams and clubs back-test models against historical match-state and statistics data. The same statistics endpoint serves historical fixtures by ID, and the fixture endpoint surfaces metadata such as season, competition, and team identifiers. An ETL agent loops over a season's fixture IDs and lands the structured stats into a warehouse.

Example prompt: For each fixtureId in a season list, call GET `/api/v2/sources/{source}/sports/{sportId}/fixtures/{fixtureId}/statistics` and write the response to a parquet file.

### AI agent integration via Jentic

A sports-analyst agent built on Jentic can call the Genius Sports Data API without juggling OAuth credentials and an x-api-key. The agent searches an intent like 'get live match state from Genius Sports', Jentic returns the matching operation with its input schema, and execution uses both the OAuth token and API key resolved from your Jentic One instance. Token refresh is handled automatically.

Example prompt: Use Jentic search 'get enhanced match state from Genius Sports', load the schema for the matchstate endpoint, and execute it with source, sportId, and fixtureId.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/oauth2/token` | Get an OAuth 2.0 access token |
| GET | `/api/v2/sources/{source}/sports/{sportId}/fixtures/{fixtureId}/liveaccess/matchstate/enhanced` | Get enhanced match state for a fixture |
| GET | `/api/v2/sources/{source}/sports/{sportId}/fixtures/{fixtureId}` | Get fixture details |
| GET | `/api/v2/sources/{source}/sports/{sportId}/fixtures/{fixtureId}/statistics` | Get fixture statistics |

## Key resources

- **Authentication** — OAuth 2.0 token exchange at auth.api.geniussports.com
- **Match State** — Enhanced live state for a fixture by source, sport, and fixtureId
- **Fixtures** — Fixture metadata and scheduling for a sport
- **Statistics** — Live and historical statistics for a fixture

## Why Jentic

- **Setup:** Wiring the Genius Sports Data API by hand means running its OAuth 2.0 token flow, attaching an x-api-key, and threading source, sport, and fixture ids through every match-state read. Through Jentic you install once, import the Genius Sports Data API from the API Directory, store the credentials once, and your agent calls it while Jentic injects both headers.
- **Permission scoping:** Genius Sports puts the source, sport, and fixture ids in the URL path (`/api/v2/sources/{source}/sports/{sportId}/fixtures/{fixtureId}`), so a rule can pin your agent to reads for one fixture, such as its match state or statistics. You choose the operations it may call, and the fixture endpoints are read-only.
- **Credential handling:** Your Genius Sports client credentials and x-api-key are stored once, encrypted, by your own Jentic One instance, which refreshes the access token and injects both headers at execution time. Neither secret enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'get live match state from Genius Sports', and Jentic returns the matching operation with its input schema so the agent picks the match-state, fixture, or statistics endpoint without reading the reference docs.

## Related APIs

- **Sportmonks API** — Sportmonks offers developer-friendly football, cricket, and other sports data with self-serve plans.
- **API-Football** — API-Football provides global football fixtures, standings, and live scores via a public REST API.
- **Stripe API** — Stripe handles billing for downstream sports data products built on top of Genius Sports.

## FAQ

### Why is there no official OpenAPI spec for Genius Sports Data API?

Genius Sports publishes prose documentation at sportsdata.api.geniussports.com/docs but does not distribute an OpenAPI file. Jentic generates and maintains this spec so that AI agents and developers can call Genius Sports Data API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Genius Sports Data API use?

The Genius Sports Data API uses OAuth 2.0 client-credentials together with an x-api-key header. Clients exchange their credentials for an access token via POST `/oauth2/token` at auth.api.geniussports.com, then send both the Bearer token and x-api-key on every data call. Through Jentic both secrets are held in the vault.

### Can I get live match state for a soccer fixture with the Genius Sports Data API?

Yes. After obtaining a token, call GET `/api/v2/sources/{source}/sports/{sportId}/fixtures/{fixtureId}/liveaccess/matchstate/enhanced` with the soccer sportId and the fixtureId for the live match. The response contains the enhanced live state used by pricing and broadcast tools.

### What are the rate limits for the Genius Sports Data API?

Rate limits are negotiated per commercial agreement and tied to the x-api-key tier rather than declared in the spec. High-frequency consumers should follow Genius Sports' guidance for polling cadence and consider their streaming feeds for sub-second updates instead of REST polling.

### How do I pull statistics for a fixture through Jentic?

Run jentic search 'get fixture statistics from Genius Sports', load the schema for GET `/api/v2/sources/{source}/sports/{sportId}/fixtures/{fixtureId}/statistics`, and execute it with the fixture identifiers. Jentic resolves both the Bearer token and x-api-key from the vault.

### Is the Genius Sports Data API free?

No. Access is commercial and tied to a licensed agreement with Genius Sports. The OAuth client and x-api-key are issued only once a contract is in place, typically for sportsbooks, broadcasters, leagues, or licensed data redistributors.

### Can I limit what my agent is allowed to do with the Genius Sports Data API?

Yes. Because you run Jentic One yourself, your own rules decide which Genius Sports operations and credentials the agent can use. Since the source, sport, and fixture ids sit in the URL path (`/api/v2/sources/{source}/sports/{sportId}/fixtures/{fixtureId}`), you can pin the agent to reads for a single fixture, such as its match state or statistics, and the fixture endpoints are read-only. You choose the exact operations it may call, so it never touches the token exchange or fixtures beyond the ones you allow.