Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: DataSports Search API
version: '2026-11-12'
summary: Real-time sports data over REST for 24 sports — scores, schedules, lineups, match statistics, tables, and team, player and league profiles.
description: 'One consistent JSON contract for 24 sports: fixtures and live scores, lineups and statistics, standings, plus teams, players and leagues, delivered in real time over REST, WebSocket and webhooks.
Successful responses use a `{ data, meta? }` envelope; failures return `{ error: { code, message } }` under a matching HTTP status. All ids are DataSportsAPI ids. Each component schema documents its fields, units and enum values, as does the data reference (https://datasportsapi.com/markdown/reference.md). The WebSocket stream, webhooks and widgets are documented at https://datasportsapi.com/docs/.
Availability: pre-launch. This documents the v2 contract; accounts, API keys and the SDK packages open with the public launch — until then, join the early-access list at https://datasportsapi.com/signup/. During the beta the Free plan allows 1,000 requests a day (100 a day after).'
contact:
name: DataSportsAPI
email: contact@noventra.dev
url: https://datasportsapi.com/contact/
servers:
- url: https://api.datasportsapi.com
description: Production
security:
- bearerAuth: []
tags:
- name: Search
x-displayName: Search
description: Search
paths:
/v2/search:
get:
operationId: search.query
tags:
- Search
summary: Search
description: 'A single search over teams (individual competitors included), players, managers, referees, leagues, fixtures, venues, racing series and races; each hit’s type names the endpoint family its id is valid for. Those families are /v2/teams, /v2/players, /v2/managers, /v2/referees, /v2/leagues, /v2/fixtures, /v2/series and /v2/races (venue ids are covered in the note). Player hits include the player’s current team; fixture hits include the teams, league, start time and status; venue hits include city, country and capacity.
**Note:** This API models every competitor as a team, so tennis players and other individual-sport athletes are returned with type team. type is a closed set — manager, referee, series and race were added on 2026-10-24, fixture and venue on 2026-11-04 — so ignore any value your client does not recognise. Three fields depend on the type and are null for all others: venue (a Venue), team (the player’s current team, as a TeamRef) and fixture ({ home, away, league, startTime, status }, with status as the coarse StatusType — the score and the rest come from /v2/fixtures/{id}). Venue hit ids work with /v2/venues/{id} and match the id in Fixture.venue and TeamDetail.venue. Since 2026-11-04 team hits include gender (male | female | mixed, matching TeamDetail), which lets you mark a women’s team without a call to /v2/teams/{id}; it is null for every other type. Venue hits come from a separate search at the source and are merged in by relevance. Passing type (since 2026-11-09) restricts the list to that type, returns 20 hits per page and reaches much further than the mixed list: ask for ?q=smith&type=player and pages go up to 50; hasNextPage stays true as long as a page is full. type=series comes from the mixed list and is therefore a single page — the source offers no paged search for series. Managers and referees also get image, a photo on our CDN (since 2026-11-04; null if the source has none); series, races, fixtures and venues always have image null.
**Plans:** Every plan, Free included.'
x-plans:
- free
- starter
- pro
- business
- enterprise
externalDocs:
description: Docs page
url: https://datasportsapi.com/docs/api/search/query/
parameters:
- name: q
in: query
required: true
description: 'text to search for: 2–100 characters once trimmed and free of control characters, otherwise a 400 names q as the problem'
schema:
type: string
minLength: 2
maxLength: 100
- name: type
in: query
required: false
description: limits hits to one type — team \| player \| league \| manager \| referee \| series \| race \| fixture \| venue — at 20 per page; leave it out for the single-page mixed list
schema:
type: string
enum:
- team
- player
- league
- manager
- referee
- series
- race
- fixture
- venue
- name: page
in: query
required: false
description: page number from 0 to 50 (defaults to 0); a page above 0 needs a type other than series
schema:
type: integer
minimum: 0
maximum: 50
default: 0
responses:
'200':
description: OK
headers:
RateLimit-Limit:
$ref: '#/components/headers/RateLimit-Limit'
RateLimit-Remaining:
$ref: '#/components/headers/RateLimit-Remaining'
RateLimit-Reset:
$ref: '#/components/headers/RateLimit-Reset'
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/SearchResult'
meta:
type: object
description: query, type, page, count, hasNextPage
properties:
query:
type: string
type:
anyOf:
- type: string
- type: 'null'
page:
type: integer
count:
type: integer
hasNextPage:
type: boolean
required:
- data
'400':
description: '- bad_request — q is absent, type is not recognised, page is not within 0–50, or page is above 0 while type is missing or set to series
Bad request (`bad_request`): the message lists the values the parameter accepts.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Missing, unknown or revoked API key (`unauthorized`).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: 'Refused: your plan does not include this endpoint (`endpoint_not_in_plan`), the requested data predates your plan''s history window (`history_not_in_plan`; see `historyFrom`), or the caller''s IP is missing from the account''s allowlist (`ip_not_allowed`, Business and Enterprise).'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not found (`not_found`), valid ids with no source data behind them (`no_data`, e.g. tracking of a fixture the source does not follow), or an endpoint that does not cover this sport (`not_supported`).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Per-minute rate exceeded (`rate_limited`) or the period's quota spent (`quota_exceeded`); wait the `Retry-After` seconds.
headers:
Retry-After:
$ref: '#/components/headers/Retry-After'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Our fault (`internal_error`); safe to retry with backoff.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: Upstream data temporarily unavailable (`upstream_unavailable`); try again once the `Retry-After` seconds have passed.
headers:
Retry-After:
$ref: '#/components/headers/Retry-After'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
x-codeSamples:
- lang: Shell
label: cURL
source: "curl -H \"Authorization: Bearer dsa_live_…\" \\\n \"https://api.datasportsapi.com/v2/search?q=…\""
- lang: TypeScript
label: TypeScript
source: 'const { data, meta } = await client.search.query({ q });
for await (const page of client.search.queryPages({ q })) { … }'
- lang: Python
label: Python
source: 'res = client.search.query(q=q)
for page in client.search.query_pages(q=q): ...'
- lang: Go
label: Go
source: 'res, err := client.Search.Query(ctx, &datasportsapi.SearchQueryParams{Q: q})
for page, err := range client.Search.QueryPages(ctx, &datasportsapi.SearchQueryParams{Q: q}) { … }'
- lang: Shell
label: CLI
source: '$ dsa search query <q>
$ dsa search query <q> --all -o csv'
components:
schemas:
StatusType:
type: string
enum:
- notstarted
- inprogress
- interrupted
- willcontinue
- postponed
- canceled
- finished
description: High-level state of a match, meant for filtering.
x-enumDescriptions:
notstarted: 'Has not begun yet: still scheduled, or its start has been delayed.'
inprogress: Under way, breaks included (for example half-time, or a fight waiting for its decision).
interrupted: Halted partway through (weather, crowd, …); play is expected to restart.
willcontinue: A match spread over several days, currently between days (for cricket Tests, the end of day N).
postponed: Rescheduled for a later date; the fixture id stays the same.
canceled: The match is not going to be played (canceled, abandoned or removed).
finished: Completed and has a result.
SearchResult:
type: object
description: A single search match, ordered by our data source’s relevance ranking. Competitors in tennis and other individual sports come back as `team` results. Since 2026-10-24 managers, referees, racing series and races can match too; since 2026-11-04, fixtures and venues as well, plus a player’s `team`.
properties:
type:
$ref: '#/components/schemas/SearchType'
description: The kind of entity matched, which tells you which endpoint its id is for.
id:
type: integer
description: 'Identifier of the matched entity. Which endpoint it works with depends on `type`: /v2/teams, /v2/players, /v2/leagues, /v2/managers, /v2/referees, /v2/series, /v2/races, /v2/fixtures or /v2/venues.'
name:
type: string
description: Name to show; for a fixture it is our data source’s "Home - Away" string.
slug:
anyOf:
- type: string
- type: 'null'
sport:
anyOf:
- type: string
- type: 'null'
description: Slug of the sport; null for venues, as a venue does not belong to a single sport.
gender:
anyOf:
- $ref: '#/components/schemas/TeamGender'
- type: 'null'
description: 'Only set on `team` results (since 2026-11-04): whether the team is men’s, women’s or mixed, as shown on TeamDetail. All other result types return null, as does an individual competitor flagged mixed by our data source.'
image:
anyOf:
- type: string
format: uri
- type: 'null'
description: Image on our CDN — a logo for teams and leagues, a photo for players, managers and referees. Series, races, fixtures and venues never have one; for other entities it is null when no image exists or it is still to be uploaded.
team:
anyOf:
- $ref: '#/components/schemas/TeamRef'
- type: 'null'
description: For player results, the club our data source currently lists them at (since 2026-11-04). Null for other types and for players with no team (free agents, retired).
fixture:
anyOf:
- $ref: '#/components/schemas/SearchFixture'
- type: 'null'
description: Populated only for `fixture` results (since 2026-11-04) with the key facts of the match; null otherwise.
venue:
anyOf:
- $ref: '#/components/schemas/Venue'
- type: 'null'
description: Populated only for `venue` results (since 2026-11-04) with the venue’s city, country and capacity; null otherwise.
required:
- type
- id
- name
- slug
- sport
- gender
- image
- team
- fixture
- venue
Error:
type: object
description: The body of every failed request. Branch on error.code; the message may be reworded.
properties:
error:
type: object
properties:
code:
type: string
description: Stable, snake_case code, e.g. not_found. Part of the contract.
message:
type: string
description: A readable sentence for logs; never parse it.
historyFrom:
type: string
format: date
description: 'history_not_in_plan only: the first day your plan can read.'
required:
- code
- message
required:
- error
SearchType:
type: string
enum:
- team
- player
- league
- manager
- referee
- series
- race
- fixture
- venue
description: The kind of entity a search result is, which also tells you which endpoint accepts its id.
x-enumDescriptions:
team: A team, or a competitor in an individual sport (tennis player, fighter, driver); use /v2/teams/{id}.
player: A team-sport player; use /v2/players/{id}.
league: A league or competition; use /v2/leagues/{id}.
manager: A manager or head coach; use /v2/managers/{id}.
referee: A match referee; use /v2/referees/{id}.
series: A racing series such as Formula 1 or MotoGP; use /v2/series/{id}.
race: A Grand Prix, a cycling race or any other single race in a racing series; look it up with /v2/races/{id}.
fixture: A match or fixture (since 2026-11-04); use /v2/fixtures/{id}. `fixture` holds its teams, league, start time and status.
venue: A stadium or arena (since 2026-11-04); use /v2/venues/{id}, the same id found in Fixture.venue and TeamDetail.venue. `venue` holds its city, country and capacity.
LeagueRef:
type: object
description: A league or competition. /v2/leagues/{id} and every league list return this same shape.
properties:
id:
type: integer
description: The league’s DataSportsAPI id.
name:
type: string
description: Name of the league or competition.
slug:
anyOf:
- type: string
- type: 'null'
description: Slug for use in URLs.
sport:
anyOf:
- type: string
- type: 'null'
description: Slug of the sport, matching the values listed by /v2/sports.
category:
anyOf:
- type: string
- type: 'null'
description: 'How the source groups the league: by country ("England"), region ("International", "North America", "World"), tour ("ATP", "WTA") or game (esports: "Counter Strike"). It is not necessarily a country; use `country` for that.'
country:
anyOf:
- $ref: '#/components/schemas/Country'
- type: 'null'
description: Country of the league when its category is a country; null for regions, tours and games.
image:
anyOf:
- type: string
format: uri
- type: 'null'
description: League logo hosted on our CDN; null if the league has no image.
priority:
anyOf:
- type: integer
- type: 'null'
description: 'The source’s prominence ranking for the competition, handy for ordering leagues: a higher value means a bigger competition (for example 719 for the Champions League, 704 for the Premier League, 702 for LaLiga, 519 for Primeira Liga), and 0 means unranked. It is filled only where the source supplies it: on the league embedded in a fixture and in the /v2/fixtures?date&sport day lists. Everywhere else — league profiles, directories, search — it is null, as it is on rows saved before 2026-11-04. Available since 2026-11-04.'
required:
- id
- name
- slug
- sport
- category
- country
- image
- priority
TeamRef:
type: object
description: Compact team reference embedded in other objects (fixtures, standings, players, leaders).
properties:
id:
type: integer
description: The team’s DataSportsAPI id.
name:
type: string
description: Name of the team. Individual sports (tennis, table tennis, darts, MMA, …) also model each competitor as a team — a single player, or a doubles pair.
slug:
anyOf:
- type: string
- type: 'null'
description: Slug for use in URLs.
shortName:
anyOf:
- type: string
- type: 'null'
description: Abbreviated display name, if the source provides one.
code:
anyOf:
- type: string
- type: 'null'
description: Abbreviation of 1–4 characters as used on scoreboards (e.g. "ARS", "LA"); generated artificially for individual sports.
image:
anyOf:
- type: string
format: uri
- type: 'null'
description: Team logo hosted on our CDN; null if the team has no image.
required:
- id
- name
- slug
- shortName
- code
- image
Venue:
type: object
description: 'A stadium or arena: where a fixture takes place, or a team’s home ground.'
properties:
id:
anyOf:
- type: integer
- type: 'null'
description: The venue’s DataSportsAPI id; null if the source supplies the venue without an id.
name:
anyOf:
- type: string
- type: 'null'
description: Name of the stadium or arena.
city:
anyOf:
- type: string
- type: 'null'
description: City where the venue is located.
country:
anyOf:
- $ref: '#/components/schemas/Country'
- type: 'null'
description: Country where the venue is located.
capacity:
anyOf:
- type: integer
- type: 'null'
description: Number of seats.
required:
- id
- name
- city
- country
- capacity
SearchFixture:
type: object
description: The match summary carried by a `fixture` search result (since 2026-11-04). For status, score and everything else, call /v2/fixtures/{id}.
properties:
home:
anyOf:
- $ref: '#/components/schemas/TeamRef'
- type: 'null'
description: The home side; null until it has been determined.
away:
anyOf:
- $ref: '#/components/schemas/TeamRef'
- type: 'null'
description: The away side; null until it has been determined.
league:
anyOf:
- $ref: '#/components/schemas/LeagueRef'
- type: 'null'
description: Competition the match belongs to; null if our data source does not name one.
startTime:
anyOf:
- type: string
format: date-time
- type: 'null'
description: Planned start time in UTC; null if our data source does not provide one.
status:
anyOf:
- $ref: '#/components/schemas/StatusType'
- type: 'null'
description: Broad match state when the search ran (no more detailed state is available here); null if our data source gives none.
required:
- home
- away
- league
- startTime
- status
Country:
type: object
description: A country record.
properties:
code:
anyOf:
- type: string
- type: 'null'
description: Two-letter code supplied by the source. ISO 3166-1 alpha-2, apart from XK for Kosovo and four codes for the UK home nations (England EN, Scotland SX, Wales WA, Northern Ireland NX). Null if unknown.
name:
type: string
description: Country name in English.
flag:
anyOf:
- type: string
format: uri
- type: 'null'
description: Flag image (PNG) hosted on our CDN. Null when there is no code or the image has not been uploaded yet. Available since 2026-11-04.
required:
- code
- name
- flag
TeamGender:
type: string
enum:
- male
- female
- mixed
description: Tells whether a team or competitor is men’s, women’s or mixed.
x-enumDescriptions:
male: Men’s team, or a male competitor.
female: Women’s team, or a female competitor.
mixed: Mixed team, as in mixed doubles.
headers:
RateLimit-Limit:
description: Your plan's request quota for the current period (UTC month on paid plans, UTC day on Free).
schema:
type: integer
Retry-After:
description: Seconds to wait before trying again.
schema:
type: integer
RateLimit-Remaining:
description: Requests still available in the current period.
schema:
type: integer
RateLimit-Reset:
description: Seconds until the period ends and the quota refills.
schema:
type: integer
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: 'Your secret API key: `Authorization: Bearer dsa_live_…`. Publishable widget keys (`dsa_pub_…`) work only for the endpoints widgets read, from the sites registered on them.'
externalDocs:
description: Documentation
url: https://datasportsapi.com/docs/