{ "openapi": "3.1.1", "info": { "title": "OddsFinder API", "version": "0.1.0", "summary": "Canonical football data with full revision history.", "description": "The OddsFinder API serves football competitions, teams, persons, fixtures, results and\nmatch facts, each as it was known at any point in time. Conventions that apply to every\noperation:\n\n- **Identifiers** are OddsFinder typed identifiers: a kind prefix, an underscore and a\n decimal sequence number (`fx_1839204`, `tm_3041`, `dec_12`). The prefix is part of\n the identity, so each parameter states the kind it expects. An identifier whose prefix\n does not match the parameter's kind, or whose body is not a plain decimal number (a\n bare UUID, leading zeros, letters), is a `400 invalid-request` naming the parameter; a\n well-formed identifier that does not exist is a `404 not-found`. When two records turn\n out to be the same entity they are merged and one identifier is retired; a retired\n identifier keeps resolving, and the response carries a `resolution` object naming the\n requested and the canonical identifier.\n- **Timestamps** are RFC 3339 in UTC with a `Z` suffix (`2026-10-03T16:30:00Z`), both\n in responses and in query parameters. Offsets are rejected.\n- **Exact decimals** (such as venue coordinates) are strings with a fixed pattern,\n never JSON numbers.\n- **Missing values** are `null`, usually with a sibling status that says why (for\n example `name_status`, `formation_status`, or a result's `status`). `withheld` always\n means that a value exists but the rights of its source do not allow serving it to\n you. Zero is an ordinary value and is never used to mean \"missing\".\n- **Enumerated values can grow**: a field with a fixed list of values (a status, a\n kind, a role, a dataset, a problem type) may gain values as sports, competitions and\n datasets are added, without a new API version. Accept a value you do not know and\n treat it as unknown rather than failing on it.\n- **Time semantics**: `valid_at` is business-effective time (which role, kickoff or\n membership applied at that instant); `known_at` is the knowledge cutoff (what\n OddsFinder had recorded by that instant, including merges, corrections and\n backfills). Operations that accept `known_at` echo the effective cutoff in\n `knowledge`. Answers for a `known_at` at or before the watermark that\n `GET /v1/coverage` reports for a dataset are stable: nothing recorded at or before\n that instant is still being accepted, so the same request gives the same answer\n later. An operation that does not list one of these parameters does not support it\n and rejects it with the `unsupported-historical-capability` problem rather than\n silently serving today's state.\n- **Pagination**: list operations return `items` in the documented stable order plus\n `page.next_cursor`; pass it back as `cursor` with the same filters (a\n `valid_at`/`known_at` you did not supply may keep defaulting to the request time\n between pages). Cursors are opaque, signed by the server and expire; a malformed,\n edited, forged or expired cursor is a `400 invalid-request` naming `cursor`. `limit`\n is bounded per operation.\n- **Freshness delay and source references**: a grant may carry a freshness delay. It\n applies to every read of its dataset that has a knowledge cutoff: entity, fixture,\n result and match-fact reads are served as known at `request time - delay` at the\n latest (`knowledge.known_at` reports the cutoff served), so nothing recorded inside\n the delay window, such as a kickoff move or a result, is served before the delay has\n passed. `GET /v1/competitions`, which takes no `known_at`, lists today's names as\n known at `request time - delay` too. Source references (`sources`) appear only where\n the rights of the source and your `read:sources` scope permit them.\n- **Errors** are RFC 9457 Problem Details (`application/problem+json`). `type` is\n `urn:oddsfinder:problem:`; the catalogue is in `components.x-problem-types`.\n- **Authentication**: every `/v1` operation requires either a user access token issued\n by OddsFinder sign-in (`Authorization: Bearer `) or an OddsFinder customer API\n key (`X-API-Key`). Effective access is the intersection of the caller's permissions,\n the client's scopes, the organization's grants, source rights and territory and time\n restrictions; a denied restriction is a `403 not-entitled` problem naming the\n restriction. Because the body depends on the credential, every response carries\n `Cache-Control: private, no-store` and `Vary: X-API-Key, Authorization`: no shared\n cache may store or reuse it.\n- **Rate limit and allowances**: every authenticated `/v1` request counts towards the\n organization's `requests_per_minute` rate limit, including failed requests, `/v1/me/*`\n and paths without an operation: a `403`, a `404`, any other 4xx and a 5xx use up the\n minute like a served request. A caller without an organization (a user without a\n membership) has no organization limits and is paced by a default per-caller\n `requests_per_minute` instead. Once the minute is used up every request is\n `429 rate-limited` (`limit_kind` `requests_per_minute`) until that calendar minute\n ends, so a credential missing the operation's scope is answered `403 not-entitled`\n (`restriction` `scope`) only until then. The daily allowances (`requests_per_day`\n and any per-dataset allowance of the organization) are consumed by metered operations\n alone and never by a failed request; an exhausted one is `429 quota-exceeded`. `/v1/me/*` consumes no\n allowance, so `GET /v1/me/usage` reports every limit (`limits`) while the minute has\n room.\n- **Match facts and source rights**: lineups (`GET /v1/fixtures/{id}/lineups`, dataset\n `lineups`) are served only where every source of a team sheet holds a display right\n for lineups; elsewhere the side is `withheld` with no entries. Sportmonks, today's\n lineup source, holds that right, so its sheets are served with a `lineups` grant.\n Statistics (`GET /v1/fixtures/{id}/statistics`, dataset `statistics`) follow the same\n rule per source: a value is served only where its source holds a display right for\n statistics; Sportmonks, today's statistics source, holds it. Match events and\n sidelined players (`GET /v1/fixtures/{id}/events`, `GET /v1/fixtures/{id}/sidelined`,\n dataset `events`) follow the same rule per fixture with the display rights for events\n and for sidelined players; Sportmonks holds both.\n- **HEAD**: every GET operation also answers HEAD with the GET's status and headers and\n no body; it is authorized, rate limited and metered exactly as the GET.\n- **Request id**: every `/v1` response carries `X-Request-Id`, the server-generated\n identifier of the logical request (also `request_id` in Problem Details); quote it\n when reporting a problem.\n", "license": { "name": "Proprietary", "identifier": "LicenseRef-OddsFinder-Proprietary" } }, "servers": [ { "url": "https://api.example.com", "description": "Placeholder: use the address that comes with your API key." } ], "security": [ { "userAccessToken": [] }, { "customerApiKey": [] } ], "tags": [ { "name": "football", "description": "Competitions, seasons, stages, clubs, teams, venues, persons, fixtures, results and match facts (lineups, statistics, events, sidelined players, officials and conditions)." }, { "name": "access", "description": "Your coverage, effective entitlements and usage." } ], "paths": { "/v1/competitions": { "get": { "operationId": "listCompetitions", "tags": [ "football" ], "summary": "List competitions", "description": "Competitions the caller's `entities` grant admits, with their seasons: a grant\nnaming competitions lists those only. Stable order: `name` ascending, then `id`\nascending; competitions without a current dated name (`name` null,\n`name_status: unavailable`) follow, by `id`. `known_at` is not supported.\n", "parameters": [ { "name": "association_code", "in": "query", "description": "FIFA member-association code of national competitions (`ENG`, `SCO`, `ITA`). Confederation and FIFA competitions have no association code and are not matched by this filter.", "schema": { "$ref": "#/components/schemas/AssociationCode" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "One page of competitions.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompetitionPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableContent" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/persons": { "get": { "operationId": "listPersons", "tags": [ "football" ], "summary": "List persons by role", "description": "Persons with their dated roles. `role` restricts to persons holding that role\nat `valid_at` (default: request time); `team_id` restricts to roles attached\nto that team. Stable order: `name` ascending, then `id` ascending. `known_at`\nlimits identity decisions and role revisions to those recorded by the cutoff;\nan identifier that is an alias at the cutoff (merged into another person by a\ndecision recorded by then and not reversed) is not listed as a separate person,\nalthough `GET /v1/persons/{id}` still resolves it. An `entities` grant naming\ncompetitions lists only persons linked to one of them: through a membership (any\nrole, any date) at a team that entered or played in the competition, or a fixture\nof it they officiated.\n", "parameters": [ { "name": "role", "in": "query", "description": "Role held at `valid_at`.", "schema": { "$ref": "#/components/schemas/Role" } }, { "name": "team_id", "in": "query", "description": "Team identifier (`tm_`). A retired identifier filters by the team it resolves to at `known_at`, and `resolution.team_id` says so.", "schema": { "$ref": "#/components/schemas/TeamId" } }, { "$ref": "#/components/parameters/ValidAt" }, { "$ref": "#/components/parameters/KnownAt" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "One page of persons.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableContent" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/persons/{id}": { "get": { "operationId": "getPerson", "tags": [ "football" ], "summary": "Get a person", "description": "One person by canonical or retired identifier. A retired identifier resolves\nto the surviving identity and the response carries `resolution` with the\nmerge decision; after a reversal the identifier resolves to itself again.\nWith `known_at` before the merge decision, the retired identifier is still its\nown identity and `resolution.status` is `canonical`. Roles are filtered to\nthose effective at `valid_at`. `403 not-entitled` (`restriction: competition`)\nwhen the caller's `entities` grant names competitions and the person is linked to\nnone of them (memberships at teams that entered or played in a granted\ncompetition, or fixtures of it they officiated); unknown identifiers are `404`.\n", "parameters": [ { "$ref": "#/components/parameters/PersonPathId" }, { "$ref": "#/components/parameters/ValidAt" }, { "$ref": "#/components/parameters/KnownAt" }, { "$ref": "#/components/parameters/Include" } ], "responses": { "200": { "description": "The person as known at the cutoff.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Person" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableContent" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/teams/{id}": { "get": { "operationId": "getTeam", "tags": [ "football" ], "summary": "Get a team", "description": "One team (senior, women's, academy or national side) by canonical or retired\nidentifier. Clubs and teams are distinct; `club_id` links a club side to its\nclub. `name` is the dated display name at `valid_at` as known at `known_at`; a\nregistered team without a dated name at that date is served with `name` null and\n`name_status: unavailable`, never as a 404. `known_at` limits merges, revisions and\nnames to those recorded by the cutoff. `include=provenance` adds, for each field\nwhose value is chosen among several sources, the source it was taken from (needs the\n`read:sources` scope).\n`403 not-entitled` (`restriction: competition`) when the caller's `entities`\ngrant names competitions and the team entered or played in none of them;\nunknown identifiers are `404`.\n", "parameters": [ { "$ref": "#/components/parameters/TeamPathId" }, { "$ref": "#/components/parameters/ValidAt" }, { "$ref": "#/components/parameters/KnownAt" }, { "$ref": "#/components/parameters/Include" } ], "responses": { "200": { "description": "The team as known at the cutoff.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Team" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableContent" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/fixtures": { "get": { "operationId": "listFixtures", "tags": [ "football" ], "summary": "List fixtures in a competition and kickoff window", "description": "Fixtures of one competition whose kickoff (as known at `known_at`) lies in\n`[from, to)`. The window is required and bounded to 92 days; a wider or\ninverted window is a `422 invalid-range`. Stable order: `kickoff_at`\nascending, then `id` ascending. Kickoff is always known (precision may be\n`day` for an early listing). Only what sources holding a display right for\nfixtures stated is served: a fixture known only through other sources is not\nlisted. A page holds `limit` items while more follow, and `next_cursor` never\nrefers to a fixture that is not listed.\n", "parameters": [ { "name": "competition_id", "in": "query", "required": true, "description": "Competition identifier (`cmp_`). A retired identifier filters, and is authorized, as the competition it resolves to at `known_at` (`resolution.competition_id`).", "schema": { "$ref": "#/components/schemas/CompetitionId" } }, { "name": "season_id", "in": "query", "description": "Season identifier (`ssn_`). A retired identifier filters by the season it resolves to at `known_at` (`resolution.season_id`).", "schema": { "$ref": "#/components/schemas/SeasonId" } }, { "name": "from", "in": "query", "required": true, "description": "Inclusive lower bound of the kickoff window (UTC).", "schema": { "$ref": "#/components/schemas/Timestamp" } }, { "name": "to", "in": "query", "required": true, "description": "Exclusive upper bound of the kickoff window (UTC); at most 92 days after `from`.", "schema": { "$ref": "#/components/schemas/Timestamp" } }, { "$ref": "#/components/parameters/KnownAt" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "One page of fixtures.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FixturePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableContent" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/fixtures/{id}": { "get": { "operationId": "getFixture", "tags": [ "football" ], "summary": "Get a fixture", "description": "One fixture with its revision history and current result. Rescheduling preserves the\nidentifier; `kickoff_at`, `status`, `stage_id`, `venue` and the sides are the state as\nknown at `known_at`, `kickoff_revisions` lists every revision recorded by that cutoff\n(each a citable `rev_` record) and `result` is the highest result version recorded by\nthen (`null` when none). `include=provenance` adds, for each field whose value is\nchosen among several sources, the source it was taken from (needs the `read:sources`\nscope). Only what sources holding a display right for fixtures stated is\nserved: revisions and result versions another source reported are left out, a value\nsuch a source won is withheld (`venue` and scores as `null`), and a fixture known only\nthrough such sources, or whose kickoff or status such a source won, is a `404`.\n", "parameters": [ { "$ref": "#/components/parameters/FixturePathId" }, { "$ref": "#/components/parameters/KnownAt" }, { "$ref": "#/components/parameters/Include" } ], "responses": { "200": { "description": "The fixture as known at the cutoff.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fixture" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableContent" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/fixtures/{id}/lineups": { "get": { "operationId": "getFixtureLineups", "tags": [ "football" ], "summary": "Get a fixture's lineups", "description": "Both sides' team sheets of a fixture as known at `known_at`: per side its team, whether\nthe sheet can be served (`status`) and its entries (`lu_` lineup entries, each a\ncitable record with its own identifier and versions). Governed by the `lineups` dataset: the\norganization needs a current `lineups` grant (and the `read:entities` scope) whose\ncompetitions include the fixture's; an unknown fixture is `404`, a fixture outside the\ngrant `403 not-entitled` (`restriction: competition`).\n\n- **Versions and `known_at`.** Every entry is the highest version recorded by the\n cutoff; a correction is a new version (a later `known_at` serves it, an earlier one the\n version before), a retraction a version that removes the entry from the sheet. Entries\n of a team that is not one of the fixture's sides as known at the cutoff are left out.\n- **Identifiers.** `person_id` and `team_id` are the canonical identifiers at the cutoff:\n an entry recorded under a person or team merged away since is served under the\n surviving identifier (one entry per person and side). An entry whose player is known\n only from sources you may not be served is left out, as `GET /v1/persons/{id}` answers\n `404` for that person.\n- **Order.** Starters first, then the bench; within each, goalkeeper, defender,\n midfielder, attacker, then entries without a position; then by shirt number (entries\n without one last).\n- **`status`.** `available`: the entries are served. `unavailable`: no entry is known for\n the side at the cutoff (`entries` empty). `withheld`: entries exist but a source of the\n side holds no display right for lineups (`entries` empty; nothing about them is\n disclosed). Sportmonks holds the display right for lineups, so its sheets are\n `available`.\n- **`sheet_complete`.** Whether the served sheet is complete: every source of its entries\n sends whole team sheets and it names eleven starters. A player a source's newer whole\n sheet (eleven starters, every entry matched to a person) drops is no longer listed.\n While it is false the sheet may be short, as the source's own record of a match can be,\n or still list a player a later snapshot dropped. A newer sheet naming a player not yet\n matched to a person removes nobody until that player is matched.\n- **Freshness delay.** A grant with a freshness delay is served what was known at\n `request time - delay` at the latest (the `knowledge` block names the cutoff used): the\n fixture, its sides and the fixtures merged into it as known then, and their entries. A\n merge recorded inside the delay window is not applied yet, and a fixture not known\n then is `404`.\n- **Billing.** A response in which no side is `available` (every side withheld or\n unavailable) is recorded with 0 units and does not consume the daily allowance.\n- **Formations.** A side's `formation` (`4-2-3-1`) is served with `formation_status`\n `known` when a formation of the side is known at the cutoff from a source that may\n serve lineups to the caller (the same rights as the entries); otherwise it is `null`\n with `formation_status` `unavailable`. Each served entry carries the player's slot\n (`formation_field`, `formation_position`; `null` on the bench).\n- **Coaches.** A side's `coaches` are served from the sources that may serve lineups to the\n caller, under the same rights as the formation; a coach known only from sources you may\n not be served is left out. The list is empty when none is known at the cutoff.\n- **Bench split.** A bench entry's `bench_status` says whether the player came on, from the\n fixture's substitution events at the cutoff. It needs a finished fixture with events\n this caller may be served, under a grant that serves them at no later cutoff; otherwise,\n or when a substitution names no player, it is `unknown`. A substitution whose player is\n not yet matched to a person has no event yet, so until it is matched that player reads\n `unused_substitute`.\n\nSource references (`sources`, with `read:sources`) appear on served sides and follow the\nsource-reference rules for the `lineups` dataset.\n", "parameters": [ { "$ref": "#/components/parameters/FixturePathId" }, { "$ref": "#/components/parameters/KnownAt" } ], "responses": { "200": { "description": "The fixture's sides and their team sheets as known at the cutoff.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FixtureLineups" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableContent" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/fixtures/{id}/statistics": { "get": { "operationId": "getFixtureStatistics", "tags": [ "football" ], "summary": "Get a fixture's statistics", "description": "The team and player statistics of a fixture as known at `known_at`: each value is a\n`st_` statistic record, citable by its own identifier and versioned, with its\nmetric, unit, period scope and definition version. Governed by the\n`statistics` dataset: the organization needs a current `statistics` grant (and the\n`read:entities` scope) whose competitions include the fixture's; an unknown fixture is\n`404`, a fixture outside the grant `403 not-entitled` (`restriction: competition`).\n\n- **Versions and `known_at`.** Every value is the highest version recorded by the\n cutoff; a correction in a newer capture is a new version (a later `known_at` serves\n it, an earlier one the version before), a retraction a version that removes the\n value. Values of a team that is not one of the fixture's sides as known at the cutoff\n are left out.\n- **Not tracked is not zero.** A metric the source did not send for a subject has no\n value here; it is never served as `0`. A source's explicit zero is served as `0`.\n- **Metrics** are the curated vocabulary (`StatisticMetric`), each with one unit\n (`count`, `percent` 0..100, `minutes`, `rating_0_10`: a source's own player rating).\n `definition_version` names the source definition the value was mapped under; values\n of two definitions are not comparable. It names the source, so it is present only\n where the value's source reference would be included (`read:sources` and the source's\n display right for statistics).\n- **Period scopes.** `first_half` and `second_half` are each half alone (the second\n half is not cumulative: a source period that turns out to be the match so far is not\n served as a half, so a fixture may have `first_half` and `as_reported` values without\n `second_half`); `as_reported` is the source's whole match where the source does not\n say whether extra time is included. Player statistics are `as_reported`.\n- **Identifiers.** `team_id` and `person_id` are the canonical identifiers at the\n cutoff: a value recorded under a team or person merged away since is served under the\n surviving identifier (one value per subject, metric, period scope and source). A player\n value whose player is known only from sources you may not be served is left out, as\n `GET /v1/persons/{id}` answers `404` for that person. `lineup_entry_id` names the\n player's entry of `GET /v1/fixtures/{id}/lineups` as served to the same caller at the\n same cutoff, else `null`.\n- **Filters.** `team_id` and `person_id` accept any identifier of the entity (compared\n as canonical at the cutoff; `team_id` keeps the side's own values and its players');\n `metric` takes one or more comma-separated codes (an unknown code is a `400`);\n `period_scope` one scope; `subject` `team` (the sides' own values) or `player`.\n- **Order.** Home side first; within a side its own values, then its players by person\n identifier; then by metric code and period scope.\n- **`status`.** `available`: at least one value is served. `unavailable`: no value\n matching the filters is known at the cutoff. `withheld`: matching values exist but no\n source of them may be served to you (nothing about them is disclosed). A value of a\n source without a display right for statistics is left out.\n- **Freshness delay.** A grant with a freshness delay is served what was known at\n `request time - delay` at the latest (the `knowledge` block names the cutoff used): the\n fixture, its sides and the fixtures merged into it as known then, and their values.\n- **Billing.** A response with no value served (`status` other than `available`) is\n recorded with 0 units and does not consume the daily allowance.\n\nSource references (`sources`, with `read:sources`) appear when values are served and\nfollow the source-reference rules for the `statistics` dataset.\n", "parameters": [ { "$ref": "#/components/parameters/FixturePathId" }, { "$ref": "#/components/parameters/KnownAt" }, { "name": "team_id", "in": "query", "description": "Only this side's values (its own and its players'); any identifier of the team (`tm_`).", "schema": { "$ref": "#/components/schemas/TeamId" } }, { "name": "person_id", "in": "query", "description": "Only this player's values; any identifier of the person (`psn_`).", "schema": { "$ref": "#/components/schemas/PersonId" } }, { "name": "metric", "in": "query", "description": "One or more comma-separated metric codes (`StatisticMetric`); an unknown code is a 400 naming `metric`.", "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,62}(,[a-z][a-z0-9_]{0,62})*$" } }, { "name": "period_scope", "in": "query", "description": "Only values of this period scope.", "schema": { "$ref": "#/components/schemas/StatisticPeriodScope" } }, { "name": "subject", "in": "query", "description": "`team` = only the sides' own values; `player` = only the players'.", "schema": { "type": "string", "enum": [ "team", "player" ] } } ], "responses": { "200": { "description": "The fixture's statistics as known at the cutoff.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FixtureStatistics" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableContent" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/fixtures/{id}/events": { "get": { "operationId": "getFixtureEvents", "tags": [ "football" ], "summary": "Get a fixture's match events", "description": "A fixture's match events (goals, own goals, penalties, cards, substitutions, VAR\ndecisions) as known at `known_at`, as `ev_` match events, each a citable record\nwith its own identifier and versions. Governed by the `events` dataset: the organization needs a current\n`events` grant (and the `read:entities` scope) whose competitions include the fixture's;\nan unknown fixture is `404`, a fixture outside the grant `403 not-entitled`\n(`restriction: competition`).\n\n- **Versions and `known_at`.** Every event is the highest version recorded by the\n cutoff; a correction is a new version of the same `ev_` (a goal re-classified as an own\n goal, a corrected minute), so an earlier `known_at` serves the version before. An\n event the source's newer capture of the match drops is retracted and left out from\n then on; one the source withdrew itself is served with `rescinded: true`.\n- **VAR.** A VAR decision is an event of its own (`kind: var_decision`, `detail` such as\n `goal_disallowed`); the goal it concerns is never edited, so a disallowed goal is the\n goal plus a later VAR decision.\n- **Sides and persons.** `team_id` is the side the event counts for: an own goal is filed\n under the side it benefits, and `person_team_id` names the scorer's own side (the team\n of his lineup entry, when the caller's `lineups` grant also serves the fixture, with no\n longer delay, and the entry's source may serve lineups to it). For a\n substitution `person_id` is the player coming on and `related_person_id` the one going\n off; for a goal the related person is the assist. Teams and persons are the canonical\n identifiers at the cutoff. An event naming a person known only from sources you may\n not be served is left out, as `GET /v1/persons/{id}` answers `404`.\n- **Order.** Match order: `minute`, `extra_minute` (none first), then the source's event\n order; a penalty shootout comes last. Each event the source reported is served once,\n also when two fixtures merged into one both recorded it.\n- **Filters.** `team_id` (events counting for that team), `person_id` (events naming the\n person as player or related player) and `kind`, all canonical at the cutoff; a filter\n that matches nothing on an `available` fixture serves `available` with no events.\n- **`status`.** `available`: the events are served. `unavailable`: no event is known for\n the fixture at the cutoff. `withheld`: events exist but a source of them holds no\n display right for events (`events` empty; nothing about them is disclosed). Sportmonks\n holds the display right.\n- **Freshness delay** and **billing** as for lineups: a grant with a delay is served what\n was known at `request time - delay` at the latest, and a response that is not\n `available` is recorded with 0 units.\n\nSource references (`sources`, with `read:sources`) appear on a served response and follow\nthe source-reference rules for events.\n", "parameters": [ { "$ref": "#/components/parameters/FixturePathId" }, { "$ref": "#/components/parameters/KnownAt" }, { "name": "team_id", "in": "query", "required": false, "description": "Only the events counting for this team (canonical at the cutoff).", "schema": { "$ref": "#/components/schemas/TeamId" } }, { "name": "person_id", "in": "query", "required": false, "description": "Only the events naming this person as the player or the related player (canonical at the cutoff).", "schema": { "$ref": "#/components/schemas/PersonId" } }, { "name": "kind", "in": "query", "required": false, "description": "Only the events of this kind.", "schema": { "$ref": "#/components/schemas/MatchEventKind" } } ], "responses": { "200": { "description": "The fixture's match events as known at the cutoff.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FixtureEvents" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableContent" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/fixtures/{id}/sidelined": { "get": { "operationId": "getFixtureSidelined", "tags": [ "football" ], "summary": "Get a fixture's sidelined players", "description": "The players of both sides the source listed as unavailable for the fixture, through\ninjury or suspension, or as doubtful for it (listed, but they may still play), as known at\n`known_at`: `sdl_` sidelined entries with the spell's start and end date, the\ngames it has cost and whether it is over. Governed by\nthe `events` dataset, with the access, versioning, identifier, delay and billing rules of\n`GET /v1/fixtures/{id}/events`; served where every source holds the display right for\nsidelined players (Sportmonks does).\n\n- **Coverage.** The source lists sidelined players for part of the fixtures only (in\n 2025/26 for 234 of 380 Premier League fixtures): `unavailable` means the source sent no\n list, not that every player was fit.\n- **Dates.** `end_date` null means the source does not know when the spell ends;\n `completed` is the source's flag as of its capture, not at the fixture's date.\n- **Order.** Injuries first, then suspensions, then doubtful players; within each by start\n date (none last).\n- **Filters.** `team_id` and `person_id`, canonical at the cutoff.\n", "parameters": [ { "$ref": "#/components/parameters/FixturePathId" }, { "$ref": "#/components/parameters/KnownAt" }, { "name": "team_id", "in": "query", "required": false, "description": "Only the entries of this team (canonical at the cutoff).", "schema": { "$ref": "#/components/schemas/TeamId" } }, { "name": "person_id", "in": "query", "required": false, "description": "Only the entries of this person (canonical at the cutoff).", "schema": { "$ref": "#/components/schemas/PersonId" } } ], "responses": { "200": { "description": "The fixture's sidelined players as known at the cutoff.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FixtureSidelined" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableContent" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/fixtures/{id}/officials": { "get": { "operationId": "getFixtureOfficials", "tags": [ "football" ], "summary": "Get a fixture's officials", "description": "The persons who officiated the fixture (the referee, the assistant referees, the fourth\nofficial) as known at `known_at`, as `mo_` match officials, each a citable record\nwith its own identifier and versions. Governed by the `context` dataset: the organization needs a\ncurrent `context` grant (and the `read:entities` scope) whose competitions include the\nfixture's; an unknown fixture is `404`, a fixture outside the grant `403 not-entitled`\n(`restriction: competition`).\n\n- **Versions and `known_at`.** Every official is the highest version recorded by the\n cutoff; an official the source's newer capture of the match no longer lists is\n retracted and left out from then on.\n- **Roles.** `referee`, `assistant_referee` (`role_order` 1 and 2 for the first and\n second assistant), `fourth_official`; `video_assistant` is in the vocabulary, but no\n source sends it today. Order: referee, assistants by `role_order`, fourth official.\n- **Identifiers.** `person_id` is the canonical person at the cutoff; a referee the\n source names is the same person as FootyStats' referee of that name. An official known\n only from sources you may not be served is left out, as `GET /v1/persons/{id}` answers\n `404`.\n- **Coverage.** The source lists officials from 2009/10, in some seasons only part of\n the roles: `unavailable` means no official is known for the fixture at the cutoff.\n- **`status`.** `available`: the officials are served. `withheld`: officials exist but\n a source of them holds no display right for officials (`officials` empty; nothing about\n them is disclosed). Sportmonks holds the display right.\n- **Freshness delay and billing** as for `GET /v1/fixtures/{id}/events`: a delayed grant\n is served what was known at `request time - delay`, and a response that is not\n `available` is recorded with 0 units.\n\nSource references (`sources`, with `read:sources`) appear on an `available` response and\nfollow the source-reference rules for officials.\n", "parameters": [ { "$ref": "#/components/parameters/FixturePathId" }, { "$ref": "#/components/parameters/KnownAt" } ], "responses": { "200": { "description": "The fixture's officials as known at the cutoff.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FixtureOfficials" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableContent" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/fixtures/{id}/conditions": { "get": { "operationId": "getFixtureConditions", "tags": [ "football" ], "summary": "Get a fixture's conditions", "description": "The conditions the fixture was played in (the attendance, whether the venue was\nneutral, the observed weather) as known at `known_at`, one `mc_` match\nconditions record per source. Governed by the `context` dataset, with the access,\nversioning, delay and billing rules of `GET /v1/fixtures/{id}/officials`; served where\nevery source holds the display right for conditions (Sportmonks and FootyStats do).\n\n- **One record per source.** Each source's report is its own record, served side by\n side. `source` names the record's provider where the caller may see source references\n (`read:sources` and the source's display right) and is left out otherwise. Rights are\n judged per source: a record whose source may not serve the caller is left out.\n- **One reconciled attendance.** `attendance` is the attendance of the first source, in\n the order Sportmonks then FootyStats, whose served record reports one at the cutoff; a\n withheld or missing source falls through to the next, any other source never supplies\n it, and when none does it is `null`. Attendance is served from 2026-11-01; for an\n earlier `known_at` it is `null`. `attendance_source` names that source on the terms of\n `source`. A FootyStats\n attendance between 1 and 999 (a figure in thousands) is treated as not reported.\n- **Values.** A value the source did not report is `null`; a later report without it\n keeps the known value. `attendance` 0 is a match behind closed doors.\n- **Weather.** The source's observed weather only, never a forecast; `basis` `current`\n is its reading at the match, `day` its day values when it has no such reading. The\n values are metric: degrees Celsius, wind speed in m/s, wind direction in degrees,\n pressure in hPa.\n- **`status`.** `available`: at least one record is served. `unavailable`: no record is\n known for the fixture at the cutoff. `withheld`: records exist but no source of them\n holds the right to serve conditions to this caller.\n", "parameters": [ { "$ref": "#/components/parameters/FixturePathId" }, { "$ref": "#/components/parameters/KnownAt" } ], "responses": { "200": { "description": "The fixture's conditions as known at the cutoff.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FixtureConditions" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableContent" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/competitions/{id}": { "get": { "operationId": "getCompetition", "tags": [ "football" ], "summary": "Get a competition", "description": "One competition by canonical or retired identifier, with its seasons. `name` is the\ndated display name at `valid_at` as known at `known_at`; a registered competition\nwithout a dated name at that date is still served, with `name` null and\n`name_status: unavailable` (never a 404). `include=provenance` adds, for each field\nwhose value is chosen among several sources, the source it was taken from (needs the\n`read:sources` scope; fields whose source holds no display right are `withheld`).\n`403 not-entitled` (`restriction: competition`) when the caller's `entities` grant\nnames competitions and excludes this one; unknown identifiers are `404`.\n", "parameters": [ { "$ref": "#/components/parameters/CompetitionPathId" }, { "$ref": "#/components/parameters/ValidAt" }, { "$ref": "#/components/parameters/KnownAt" }, { "$ref": "#/components/parameters/Include" } ], "responses": { "200": { "description": "The competition as known at the cutoff.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompetitionDetail" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableContent" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/seasons/{id}": { "get": { "operationId": "getSeason", "tags": [ "football" ], "summary": "Get a season", "description": "One season (edition of a competition) with its stages, its default stage and the teams\nentered in it (`team_ids`). Fixtures of the season\nare listed with `GET /v1/fixtures?competition_id=&season_id=`. Authorized through the\nseason's competition.\n", "parameters": [ { "$ref": "#/components/parameters/SeasonPathId" }, { "$ref": "#/components/parameters/KnownAt" }, { "$ref": "#/components/parameters/Include" } ], "responses": { "200": { "description": "The season as known at the cutoff.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeasonDetail" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableContent" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/stages/{id}": { "get": { "operationId": "getStage", "tags": [ "football" ], "summary": "Get a stage", "description": "One structural part of a season (regular season, group, knockout round). Every season has\nexactly one default stage; a fixture always belongs to a stage. Authorized through the\nseason's competition.\n", "parameters": [ { "$ref": "#/components/parameters/StagePathId" }, { "$ref": "#/components/parameters/KnownAt" }, { "$ref": "#/components/parameters/Include" } ], "responses": { "200": { "description": "The stage as known at the cutoff.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Stage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableContent" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/clubs/{id}": { "get": { "operationId": "getClub", "tags": [ "football" ], "summary": "Get a club", "description": "One club (the organisation) with the teams it fields (`team_ids`). `name` follows the\ndated-name rules of competitions (`null` with `name_status: unavailable` when no\ndated name exists at `valid_at`). A club is linked to the competitions its teams entered\nor played in; a competition-limited grant must name one of them.\n", "parameters": [ { "$ref": "#/components/parameters/ClubPathId" }, { "$ref": "#/components/parameters/ValidAt" }, { "$ref": "#/components/parameters/KnownAt" }, { "$ref": "#/components/parameters/Include" } ], "responses": { "200": { "description": "The club as known at the cutoff.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Club" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableContent" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/venues/{id}": { "get": { "operationId": "getVenue", "tags": [ "football" ], "summary": "Get a venue", "description": "One venue with its dated name at `valid_at` (`null` with `name_status: unavailable`\nwhen none exists), territory, city and optional coordinates (exact decimal strings).\nA venue is linked to the competitions of the fixtures played there; a venue without\nfixtures is served only by an unrestricted grant.\n", "parameters": [ { "$ref": "#/components/parameters/VenuePathId" }, { "$ref": "#/components/parameters/ValidAt" }, { "$ref": "#/components/parameters/KnownAt" }, { "$ref": "#/components/parameters/Include" } ], "responses": { "200": { "description": "The venue as known at the cutoff.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Venue" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableContent" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/results/{id}": { "get": { "operationId": "getResult", "tags": [ "football" ], "summary": "Get a result", "description": "The result of a fixture (`res_`, a citable record with its own identifier): the\ncurrent version recorded by `known_at` at the top level and every version recorded by\nthen in `versions` (oldest first; a correction is a new version, a retraction a version\nwith `retracted: true`). `status` is the sibling that says why scores are null\n(`pending` = not yet, `provisional` = reported but not settled, `final` = settled).\nA result is a record, not an entity that can be merged: there is no `resolution` object\nand the result is authorized through its fixture's competition. A result identifier whose first\nversion was recorded after the cutoff is `404`.\n", "parameters": [ { "$ref": "#/components/parameters/ResultPathId" }, { "$ref": "#/components/parameters/KnownAt" }, { "$ref": "#/components/parameters/Include" } ], "responses": { "200": { "description": "The result as known at the cutoff.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableContent" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/coverage": { "get": { "operationId": "getCoverage", "tags": [ "access" ], "summary": "Dataset coverage visible to the caller", "description": "What the caller can obtain: per dataset and competition, the covered period,\nterritory, sampling resolution, history watermark and status (`available`,\n`partial`, `restricted` by the caller's grant or because no covering source may be\ndisplayed, `unsupported` by the platform, `unavailable` right now). A `restricted`\nitem discloses nothing beyond its status: its period, sampling and `watermark_at` are\nnull and there are no source references. No item names a competition your entity reads\ndo not serve. The match facts (`lineups`, `statistics`, `events`, `context`) have one item\nper competition (no territory) whose watermark is the newest version the item's covering\nsources recorded for its fixtures, counting only the covering sources you may be shown.\nStable order: `dataset`, then `competition_id`, then `territory`. Source\nreferences appear where source rights permit.\n", "parameters": [ { "name": "competition_id", "in": "query", "description": "Competition identifier (`cmp_`).", "schema": { "$ref": "#/components/schemas/CompetitionId" } }, { "name": "dataset", "in": "query", "schema": { "$ref": "#/components/schemas/Dataset" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "One page of coverage entries.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoveragePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableContent" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/me/entitlements": { "get": { "operationId": "getMyEntitlements", "tags": [ "access" ], "summary": "Effective entitlements of the caller", "description": "The access OddsFinder derived for your credential: principal, organization, scopes,\nthe versions of your grants, source rights and access policy, and the dataset grants\nwith their competition, territory, freshness-delay and lookback limits.\nIt takes no query parameter: any is a `400 invalid-request`, and `known_at` or\n`valid_at` a `422 unsupported-historical-capability` (the context is the current\none). The call consumes no allowance but counts towards the per-minute rate limit\nlike every request.\n", "responses": { "200": { "description": "Effective entitlements.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entitlements" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableContent" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/me/usage": { "get": { "operationId": "getMyUsage", "tags": [ "access" ], "summary": "Metered usage and quota of the caller's organization", "description": "Logical metered requests for the caller's organization (or the user alone when\nthere is none) in `[from, to)`; default is the current allowance period. The\nwindow is bounded to 93 days. Server-side retries and cache hits are reported\nseparately and never counted twice. `limits` reports every limit that applies to\nthe caller. The call consumes no allowance but counts towards the per-minute rate\nlimit like every request.\n", "parameters": [ { "name": "from", "in": "query", "schema": { "$ref": "#/components/schemas/Timestamp" } }, { "name": "to", "in": "query", "schema": { "$ref": "#/components/schemas/Timestamp" } } ], "responses": { "200": { "description": "Usage summary.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableContent" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } } }, "components": { "securitySchemes": { "userAccessToken": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "A user access token (JWT) issued by OddsFinder sign-in, validated for its signature, issuer, audience and expiry." }, "customerApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "An OddsFinder customer API key issued to an API client of your organization; it can be revoked and is limited to its scopes." } }, "x-problem-types": [ { "slug": "invalid-request", "status": 400, "title": "Invalid request", "description": "Malformed path/query/header value, unknown query parameter, or malformed/expired cursor. `errors` lists each offending parameter." }, { "slug": "unauthenticated", "status": 401, "title": "Authentication required", "description": "No credential, or an invalid, expired or revoked credential. `WWW-Authenticate` names the accepted schemes." }, { "slug": "forbidden", "status": 403, "title": "Forbidden", "description": "The principal or client scope does not permit the operation at all." }, { "slug": "not-entitled", "status": 403, "title": "Not entitled", "description": "A grant, source-rights, territory, lookback or freshness restriction denies this request; `restriction` names it." }, { "slug": "not-found", "status": 404, "title": "Not found", "description": "No such path, or no entity with that identifier is visible to the caller at the requested knowledge cutoff." }, { "slug": "method-not-allowed", "status": 405, "title": "Method not allowed", "description": "The path exists but not for this method." }, { "slug": "invalid-range", "status": 422, "title": "Invalid range", "description": "A well-formed window is inverted, wider than the operation's bound, or otherwise too large for the operation to answer." }, { "slug": "unsupported-historical-capability", "status": 422, "title": "Unsupported historical capability", "description": "A `valid_at`, `known_at` or other time parameter this operation does not support or cannot answer faithfully (for example a `known_at` earlier than the retained correction history). Today's state is never served instead." }, { "slug": "rate-limited", "status": 429, "title": "Rate limited", "description": "The `requests_per_minute` rate limit is used up for the calendar minute, the organization's or, for a caller without an organization, the default per-caller limit; `limit_kind` (`requests_per_minute`) and `limit` name it and `Retry-After` is the end of the minute. Every request counts towards it, failed ones (403, 404, other 4xx, 5xx, a refusal by a daily allowance), `/v1/me/*` and paths without an operation included, so a credential missing the operation's scope receives this problem instead of `403 not-entitled` once its minute is used; a refusal by the rate limit itself does not count, except for a caller without an organization, whose refusals count towards its minute too (it is still refused only until the minute ends). No usage is metered for the rejected request. When a daily allowance is exhausted too, the answer is `quota-exceeded`." }, { "slug": "quota-exceeded", "status": 429, "title": "Quota exceeded", "description": "A daily allowance of the organization (`requests_per_day`, or a per-dataset allowance) is exhausted for its UTC day; `limit_kind` and `limit` name it and `Retry-After` is the end of the latest-ending exhausted period. No usage is metered for the rejected request. A daily allowance counts the requests in flight and the served ones (a failed request releases what it reserved); metered usage counts served requests only. A used-up per-minute rate limit alone is `rate-limited`." }, { "slug": "internal-error", "status": 500, "title": "Internal error", "description": "Unexpected failure; `request_id` identifies the server-side record." }, { "slug": "unavailable", "status": 503, "title": "Service unavailable", "description": "A service this operation depends on is temporarily unavailable; nothing is served in its place." }, { "slug": "policy-unavailable", "status": 503, "title": "Access policy unavailable", "description": "Your access, quota or usage records cannot be checked right now, so the request is refused rather than served unchecked." } ], "parameters": { "PersonPathId": { "name": "id", "in": "path", "required": true, "description": "Canonical or retired person identifier (`psn_`); another kind's prefix or an undecodable body is a 400 naming `id`.", "schema": { "$ref": "#/components/schemas/PersonId" } }, "TeamPathId": { "name": "id", "in": "path", "required": true, "description": "Canonical or retired team identifier (`tm_`); another kind's prefix or an undecodable body is a 400 naming `id`.", "schema": { "$ref": "#/components/schemas/TeamId" } }, "FixturePathId": { "name": "id", "in": "path", "required": true, "description": "Canonical or retired fixture identifier (`fx_`); another kind's prefix or an undecodable body is a 400 naming `id`.", "schema": { "$ref": "#/components/schemas/FixtureId" } }, "CompetitionPathId": { "name": "id", "in": "path", "required": true, "description": "Canonical or retired competition identifier (`cmp_`); another kind's prefix or an undecodable body is a 400 naming `id`.", "schema": { "$ref": "#/components/schemas/CompetitionId" } }, "SeasonPathId": { "name": "id", "in": "path", "required": true, "description": "Season identifier (`ssn_`); another kind's prefix or an undecodable body is a 400 naming `id`.", "schema": { "$ref": "#/components/schemas/SeasonId" } }, "StagePathId": { "name": "id", "in": "path", "required": true, "description": "Stage identifier (`stg_`); another kind's prefix or an undecodable body is a 400 naming `id`.", "schema": { "$ref": "#/components/schemas/StageId" } }, "ClubPathId": { "name": "id", "in": "path", "required": true, "description": "Canonical or retired club identifier (`clb_`); another kind's prefix or an undecodable body is a 400 naming `id`.", "schema": { "$ref": "#/components/schemas/ClubId" } }, "VenuePathId": { "name": "id", "in": "path", "required": true, "description": "Canonical or retired venue identifier (`ven_`); another kind's prefix or an undecodable body is a 400 naming `id`.", "schema": { "$ref": "#/components/schemas/VenueId" } }, "ResultPathId": { "name": "id", "in": "path", "required": true, "description": "Result record identifier (`res_`); another kind's prefix or an undecodable body is a 400 naming `id`.", "schema": { "$ref": "#/components/schemas/ResultId" } }, "Include": { "name": "include", "in": "query", "description": "Optional blocks to add to a single-entity read. `provenance` names, for each field whose value is chosen among several sources, the source report it was taken from as known at `known_at`; it needs the `read:sources` scope (`403 not-entitled`, `restriction: scope` otherwise), and a field is `withheld` when its source holds no display right.", "schema": { "type": "string", "enum": [ "provenance" ] } }, "Cursor": { "name": "cursor", "in": "query", "description": "Opaque page cursor from a previous `page.next_cursor`; filters must be repeated unchanged.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,512}$" } }, "Limit": { "name": "limit", "in": "query", "description": "Maximum items per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, "ValidAt": { "name": "valid_at", "in": "query", "description": "Business-effective instant (UTC); default is the request time.", "schema": { "$ref": "#/components/schemas/Timestamp" } }, "KnownAt": { "name": "known_at", "in": "query", "description": "Knowledge cutoff (UTC); the answer reflects only what OddsFinder had recorded by this instant. Default is the request time. Must not be in the future.", "schema": { "$ref": "#/components/schemas/Timestamp" } } }, "headers": { "RequestId": { "description": "Server-generated identifier of the logical request (the `request_id` of a problem and of the usage record). Every `/v1` response carries it.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "RetryAfter": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 0 } }, "WWWAuthenticate": { "description": "Accepted authentication schemes.", "required": true, "schema": { "type": "string" } } }, "responses": { "BadRequest": { "description": "Malformed parameter or cursor (`invalid-request`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Unauthorized": { "description": "Missing or invalid credential (`unauthenticated`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Forbidden": { "description": "Operation not permitted (`forbidden`) or restricted by grants/rights (`not-entitled`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "NotFound": { "description": "Unknown identifier at the requested cutoff (`not-found`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "UnprocessableContent": { "description": "Well-formed but unanswerable (`invalid-range`, `unsupported-historical-capability`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "TooManyRequests": { "description": "The per-minute rate limit is used up (`rate-limited`) or a daily allowance is exhausted (`quota-exceeded`). Failed requests (403, 404, other 4xx, 5xx) use up the per-minute rate limit too.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "InternalError": { "description": "Unexpected failure (`internal-error`); `request_id` identifies the server-side record.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "ServiceUnavailable": { "description": "A service this operation depends on, or the access check, is temporarily unavailable (`unavailable`, `policy-unavailable`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "schemas": { "Id": { "type": "string", "description": "OddsFinder identifier, `_`, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. `Resolution` uses this generic form because its identifiers are of the resource's kind.", "pattern": "^[a-z]+_[1-9][0-9]{0,18}$" }, "PersonId": { "type": "string", "description": "Person identifier (`psn_`).", "pattern": "^psn_[1-9][0-9]{0,18}$" }, "ClubId": { "type": "string", "description": "Club identifier (`clb_`).", "pattern": "^clb_[1-9][0-9]{0,18}$" }, "TeamId": { "type": "string", "description": "Team identifier (`tm_`).", "pattern": "^tm_[1-9][0-9]{0,18}$" }, "CompetitionId": { "type": "string", "description": "Competition identifier (`cmp_`).", "pattern": "^cmp_[1-9][0-9]{0,18}$" }, "SeasonId": { "type": "string", "description": "Season identifier (`ssn_`).", "pattern": "^ssn_[1-9][0-9]{0,18}$" }, "FixtureId": { "type": "string", "description": "Fixture identifier (`fx_`).", "pattern": "^fx_[1-9][0-9]{0,18}$" }, "DecisionId": { "type": "string", "description": "Identifier of a merge or reversal decision (`dec_`), a record you can cite.", "pattern": "^dec_[1-9][0-9]{0,18}$" }, "SourcePart": { "type": "string", "description": "A source provider or namespace name (`footystats`, `football`).", "pattern": "^[a-z][a-z0-9_]*$" }, "NameStatus": { "type": "string", "description": "Says why a nullable `name` is or is not served: `known` = a dated name applies at `valid_at` as known at the cutoff; `unavailable` = the entity exists but has no dated name at that date (for example a team known from a source that reports no names); `withheld` = a name exists but the rights of its sources do not allow serving it to you. An entity is never a 404 for lacking a name.", "enum": [ "known", "unavailable", "withheld" ] }, "RequestId": { "type": "string", "format": "uuid", "description": "Server-generated request identifier (UUID); not an entity identifier.", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "OrganizationId": { "type": "string", "format": "uuid", "description": "Account identifier of an organization (UUID); organizations are accounts, not football entities.", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "Timestamp": { "type": "string", "format": "date-time", "description": "RFC 3339 instant in UTC with `Z` suffix; optional fractional seconds up to microseconds.", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]{1,6})?Z$" }, "NullableTimestamp": { "description": "A `Timestamp`, or `null` when unknown; the owning object says why.", "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "Date": { "type": "string", "format": "date", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, "AssociationCode": { "type": "string", "description": "FIFA member-association code (`ENG`, `SCO`, `WAL`, `NIR` exist; `GBR` does not). Football nationality and the country of a competition or team use this list, never ISO 3166-1. Commercial territories (`Territory`) are ISO 3166-1 alpha-2.", "pattern": "^[A-Z]{3}$" }, "Organiser": { "type": "string", "description": "Who organises a competition or registers a side. `national_association` means the sibling `association_code` names the member association; a confederation or `FIFA` organises competitions that have no country and the sibling is `null`.", "enum": [ "national_association", "UEFA", "CONMEBOL", "CONCACAF", "AFC", "CAF", "OFC", "FIFA" ] }, "Territory": { "type": "string", "description": "Territory a site or grant applies to (ISO 3166-1 alpha-2).", "pattern": "^[A-Z]{2}$" }, "Role": { "type": "string", "enum": [ "coach", "player", "referee" ] }, "Dataset": { "type": "string", "description": "The datasets access is granted for. `coverage` and `account` are governed by scope only and never appear in an organization's grants or in coverage items. `lineups` (team sheets, `GET /v1/fixtures/{id}/lineups`), `statistics` (player and team match statistics, `GET /v1/fixtures/{id}/statistics`) and `events` (match events and sidelined players, `GET /v1/fixtures/{id}/events` and `/sidelined`) and `context` (officials and conditions, `GET /v1/fixtures/{id}/officials` and `/conditions`) are granted per organization like `entities` and read with the `read:entities` scope.", "enum": [ "entities", "lineups", "statistics", "events", "context", "coverage", "account" ] }, "Knowledge": { "type": "object", "description": "The effective knowledge cutoff of the response. Under a grant freshness delay it is never later than the request time minus the delay, whatever `known_at` asked for.", "required": [ "known_at", "as_requested" ], "properties": { "known_at": { "$ref": "#/components/schemas/Timestamp" }, "as_requested": { "type": "boolean", "description": "True when the caller supplied `known_at`; false when it defaulted to the request time." } } }, "Resolution": { "type": "object", "description": "How the requested identifier resolved. Present whenever the requested identifier is not the canonical one, and optional otherwise.", "required": [ "requested_id", "canonical_id", "status" ], "properties": { "requested_id": { "$ref": "#/components/schemas/Id" }, "canonical_id": { "$ref": "#/components/schemas/Id" }, "status": { "type": "string", "description": "`canonical`: the requested identifier is the identity itself; `alias`: it was retired by a merge decision and resolves to `canonical_id`.", "enum": [ "canonical", "alias" ] }, "decision_id": { "oneOf": [ { "$ref": "#/components/schemas/DecisionId" }, { "type": "null" } ] }, "decided_at": { "$ref": "#/components/schemas/NullableTimestamp" } } }, "FilterResolution": { "type": "object", "description": "How each identifier filter of a list read resolved at `known_at`, by parameter name; present when a supplied filter names a registered entity the caller is served and its grant admits (an entity outside a competition restriction, or one the single read answers as unknown, is not echoed and the filter applies as given). A retired identifier (`status` `alias`) filters, and for a competition is authorized, as its `canonical_id`; list items themselves never carry a resolution.", "additionalProperties": false, "properties": { "team_id": { "$ref": "#/components/schemas/Resolution" }, "competition_id": { "$ref": "#/components/schemas/Resolution" }, "season_id": { "$ref": "#/components/schemas/Resolution" } } }, "SourceReference": { "type": "object", "required": [ "source", "observed_at", "recorded_at", "precision" ], "properties": { "source": { "type": "string", "description": "Source namespace (for example `footystats`).", "pattern": "^[a-z][a-z0-9_]{1,63}$" }, "observed_at": { "$ref": "#/components/schemas/NullableTimestamp" }, "recorded_at": { "$ref": "#/components/schemas/Timestamp" }, "precision": { "type": "string", "description": "Precision of the source timestamp; `unknown` when the source gave none.", "enum": [ "unknown", "day", "hour", "minute", "second", "millisecond" ] } } }, "SourceReferences": { "type": "object", "description": "Source references, or an explicit statement that they are withheld by source rights or unknown.", "required": [ "status", "items" ], "properties": { "status": { "type": "string", "enum": [ "included", "withheld", "unknown" ] }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/SourceReference" } } } }, "Page": { "type": "object", "required": [ "next_cursor", "limit" ], "properties": { "next_cursor": { "description": "Cursor for the next page, or `null` on the last page.", "oneOf": [ { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,512}$" }, { "type": "null" } ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 } } }, "Problem": { "type": "object", "description": "RFC 9457 Problem Details with OddsFinder extension members.", "required": [ "type", "title", "status" ], "properties": { "type": { "type": "string", "pattern": "^urn:oddsfinder:problem:[a-z][a-z0-9-]*$" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "detail": { "type": "string" }, "instance": { "type": "string", "description": "Request path." }, "request_id": { "$ref": "#/components/schemas/RequestId" }, "errors": { "type": "array", "description": "Per-parameter detail for `invalid-request`.", "items": { "type": "object", "required": [ "location", "name", "message" ], "properties": { "location": { "type": "string", "enum": [ "path", "query", "header", "body" ] }, "name": { "type": "string" }, "message": { "type": "string" } } } }, "restriction": { "type": "string", "description": "For `not-entitled`: which restriction denied the request.", "enum": [ "scope", "dataset", "competition", "territory", "lookback", "freshness", "source_rights" ] }, "retry_after_seconds": { "type": "integer", "minimum": 0 } }, "additionalProperties": true }, "Season": { "type": "object", "required": [ "id", "label", "starts_on", "ends_on" ], "properties": { "id": { "$ref": "#/components/schemas/SeasonId" }, "label": { "type": "string" }, "starts_on": { "$ref": "#/components/schemas/Date" }, "ends_on": { "$ref": "#/components/schemas/Date" } } }, "Competition": { "type": "object", "required": [ "id", "name", "name_status", "association_code", "organiser", "competition_kind", "tier", "seasons" ], "properties": { "id": { "$ref": "#/components/schemas/CompetitionId" }, "name": { "description": "The display name at the date (names are dated, and a sponsor rename never changes the identifier); `null` with `name_status: unavailable` when no dated name exists.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "name_status": { "$ref": "#/components/schemas/NameStatus" }, "association_code": { "description": "Member association of a national competition; `null` when a confederation or FIFA organises it (see `organiser`).", "oneOf": [ { "$ref": "#/components/schemas/AssociationCode" }, { "type": "null" } ] }, "organiser": { "$ref": "#/components/schemas/Organiser" }, "competition_kind": { "type": "string", "description": "The kind of competition.", "enum": [ "league", "cup", "international", "friendly" ] }, "tier": { "description": "1 = top division; `null` when unknown (no sibling status exists yet).", "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 20 }, { "type": "null" } ] }, "seasons": { "type": "array", "items": { "$ref": "#/components/schemas/Season" } }, "sources": { "$ref": "#/components/schemas/SourceReferences" } } }, "CompetitionDetail": { "description": "A single competition read; list items carry no `resolution`, `knowledge` or `provenance`.", "allOf": [ { "$ref": "#/components/schemas/Competition" }, { "type": "object", "required": [ "resolution", "knowledge" ], "properties": { "resolution": { "$ref": "#/components/schemas/Resolution" }, "knowledge": { "$ref": "#/components/schemas/Knowledge" }, "provenance": { "$ref": "#/components/schemas/Provenance" } } } ] }, "CompetitionPage": { "type": "object", "required": [ "items", "page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Competition" } }, "page": { "$ref": "#/components/schemas/Page" } } }, "PersonRole": { "type": "object", "description": "A dated role or appointment. `to` is `null` while current.", "required": [ "role", "team_id", "from", "to" ], "properties": { "role": { "$ref": "#/components/schemas/Role" }, "team_id": { "oneOf": [ { "$ref": "#/components/schemas/TeamId" }, { "type": "null" } ] }, "competition_id": { "oneOf": [ { "$ref": "#/components/schemas/CompetitionId" }, { "type": "null" } ] }, "from": { "$ref": "#/components/schemas/Date" }, "to": { "oneOf": [ { "$ref": "#/components/schemas/Date" }, { "type": "null" } ] } } }, "Person": { "type": "object", "required": [ "id", "name", "name_status", "full_name", "first_name", "last_name", "aliases", "height_cm", "weight_kg", "birth_country_code", "position", "detailed_position", "preferred_foot", "birth_place", "contract_until", "roles", "knowledge" ], "properties": { "id": { "$ref": "#/components/schemas/PersonId" }, "name": { "description": "The familiar name the person is known by (Rodri); the legal name is `full_name`. `null` with `name_status: unavailable` when the person has no name yet (a referee or coach whose source gives no name), which is not a 404.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "name_status": { "$ref": "#/components/schemas/NameStatus" }, "full_name": { "description": "The full legal name (Rodrigo Hernández Cascante for `name` Rodri); `null` when no servable source supplies it.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "first_name": { "description": "First name; `null` when no servable source supplies it.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "last_name": { "description": "Last name; `null` when no servable source supplies it.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "aliases": { "description": "Every other spelling a servable source gave for the person (Savio, Sávio Moreira de Oliveira for `name` Savinho), including those given for a person merged into this one while the merge stands, without `name` and `full_name`; a spelling stops being an alias when its source no longer maps the person or corrects it. For search and matching. Empty when there is none.", "type": "array", "items": { "type": "string" } }, "association_code": { "description": "Football nationality as a FIFA member-association code; `null` when unknown.", "oneOf": [ { "$ref": "#/components/schemas/AssociationCode" }, { "type": "null" } ] }, "born_on": { "oneOf": [ { "$ref": "#/components/schemas/Date" }, { "type": "null" } ] }, "height_cm": { "description": "Height in centimetres; `null` when unknown.", "oneOf": [ { "type": "integer", "minimum": 140, "maximum": 215 }, { "type": "null" } ] }, "weight_kg": { "description": "Weight in kilograms; `null` when unknown.", "oneOf": [ { "type": "integer", "minimum": 45, "maximum": 120 }, { "type": "null" } ] }, "birth_country_code": { "description": "Country of birth as a FIFA code (not the football nationality, which is `association_code`); `null` when unknown.", "oneOf": [ { "$ref": "#/components/schemas/AssociationCode" }, { "type": "null" } ] }, "position": { "description": "A player's main position; `null` when unknown or never a player.", "oneOf": [ { "type": "string", "enum": [ "goalkeeper", "defender", "midfielder", "attacker" ] }, { "type": "null" } ] }, "detailed_position": { "description": "A player's detailed position, always one of `position`'s (a source's detailed position of another main position is not served); `null` when unknown or never a player.", "oneOf": [ { "type": "string", "enum": [ "goalkeeper", "centre_back", "left_back", "right_back", "defensive_midfield", "central_midfield", "attacking_midfield", "left_midfield", "right_midfield", "left_wing", "right_wing", "second_striker", "centre_forward" ] }, { "type": "null" } ] }, "preferred_foot": { "description": "Preferred foot; `null` when unknown.", "oneOf": [ { "type": "string", "enum": [ "left", "right", "both" ] }, { "type": "null" } ] }, "birth_place": { "description": "Place of birth as the source names it; `null` when unknown.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "contract_until": { "description": "End of the current club contract; `null` when unknown.", "oneOf": [ { "$ref": "#/components/schemas/Date" }, { "type": "null" } ] }, "roles": { "type": "array", "items": { "$ref": "#/components/schemas/PersonRole" } }, "resolution": { "$ref": "#/components/schemas/Resolution" }, "knowledge": { "$ref": "#/components/schemas/Knowledge" }, "sources": { "$ref": "#/components/schemas/SourceReferences" }, "provenance": { "$ref": "#/components/schemas/Provenance" } } }, "PersonPage": { "type": "object", "required": [ "items", "page", "knowledge" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Person" } }, "page": { "$ref": "#/components/schemas/Page" }, "knowledge": { "$ref": "#/components/schemas/Knowledge" }, "resolution": { "$ref": "#/components/schemas/FilterResolution" } } }, "Team": { "type": "object", "required": [ "id", "name", "name_status", "kind", "club_id", "association_code", "organiser", "knowledge" ], "properties": { "id": { "$ref": "#/components/schemas/TeamId" }, "name": { "description": "The display name at `valid_at` as known at the cutoff; `null` with `name_status: unavailable` when no dated name exists, which is not a 404.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "name_status": { "$ref": "#/components/schemas/NameStatus" }, "kind": { "type": "string", "description": "The kind of side.", "enum": [ "senior_men", "senior_women", "reserve", "youth", "national_men", "national_women", "national_youth" ] }, "club_id": { "description": "Owning club for club sides (`clb_`); `null` for national teams.", "oneOf": [ { "$ref": "#/components/schemas/ClubId" }, { "type": "null" } ] }, "association_code": { "description": "Member association the side is registered with; `null` only for a representative side of a confederation or FIFA (see `organiser`).", "oneOf": [ { "$ref": "#/components/schemas/AssociationCode" }, { "type": "null" } ] }, "organiser": { "$ref": "#/components/schemas/Organiser" }, "resolution": { "$ref": "#/components/schemas/Resolution" }, "knowledge": { "$ref": "#/components/schemas/Knowledge" }, "sources": { "$ref": "#/components/schemas/SourceReferences" }, "provenance": { "$ref": "#/components/schemas/Provenance" } } }, "KickoffRevision": { "type": "object", "description": "One fixture revision, a citable record with its own `rev_` identifier; it carries the state it set.", "required": [ "id", "revision_no", "kickoff_at", "kickoff_precision", "status", "recorded_at", "reason" ], "properties": { "id": { "$ref": "#/components/schemas/RevisionId" }, "revision_no": { "type": "integer", "minimum": 1, "description": "Sequential per fixture; revision 1 is always `initial`." }, "kickoff_at": { "$ref": "#/components/schemas/Timestamp" }, "kickoff_precision": { "type": "string", "enum": [ "day", "hour", "minute", "second", "millisecond" ] }, "status": { "type": "string", "description": "The fixture status the revision set.", "enum": [ "scheduled", "postponed", "in_play", "finished", "cancelled", "abandoned" ] }, "recorded_at": { "$ref": "#/components/schemas/Timestamp" }, "reason": { "type": "string", "description": "Why the revision was recorded; revision 1 is `initial`.", "enum": [ "initial", "kickoff_correction", "postponement", "status_change", "venue_change", "participant_change", "stage_change", "result_correction" ] } } }, "Fixture": { "type": "object", "required": [ "id", "competition_id", "season_id", "stage_id", "home_team_id", "away_team_id", "kickoff_at", "kickoff_precision", "status", "venue", "venue_id", "kickoff_revisions", "result", "knowledge" ], "properties": { "id": { "$ref": "#/components/schemas/FixtureId" }, "competition_id": { "$ref": "#/components/schemas/CompetitionId" }, "season_id": { "$ref": "#/components/schemas/SeasonId" }, "stage_id": { "description": "The stage the fixture belongs to as known at the cutoff (never null; the season's default stage until the fixture is assigned to another).", "$ref": "#/components/schemas/StageId" }, "venue": { "description": "The venue name as the source reported it; `null` when no source reported one.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "venue_id": { "description": "The venue, once the reported name is matched to one; `null` until then.", "oneOf": [ { "$ref": "#/components/schemas/VenueId" }, { "type": "null" } ] }, "result": { "description": "The highest result version recorded by the cutoff; `null` when no result record is known yet.", "oneOf": [ { "$ref": "#/components/schemas/ResultSummary" }, { "type": "null" } ] }, "provenance": { "$ref": "#/components/schemas/Provenance" }, "home_team_id": { "$ref": "#/components/schemas/TeamId" }, "away_team_id": { "$ref": "#/components/schemas/TeamId" }, "kickoff_at": { "description": "Kickoff as known at the cutoff. Always present; `kickoff_precision` says how much of it is confirmed.", "$ref": "#/components/schemas/Timestamp" }, "kickoff_precision": { "type": "string", "description": "Precision of `kickoff_at`: `minute`/`second`/`millisecond` are confirmed instants, `hour`/`day` mean only that part is known and `kickoff_at` is the start of it (an early listing with the date only).", "enum": [ "day", "hour", "minute", "second", "millisecond" ] }, "status": { "type": "string", "description": "The fixture's status as known at the cutoff.", "enum": [ "scheduled", "postponed", "in_play", "finished", "cancelled", "abandoned" ] }, "kickoff_revisions": { "type": "array", "description": "Every kickoff revision recorded by the cutoff, oldest first.", "items": { "$ref": "#/components/schemas/KickoffRevision" } }, "resolution": { "$ref": "#/components/schemas/Resolution" }, "knowledge": { "$ref": "#/components/schemas/Knowledge" }, "sources": { "$ref": "#/components/schemas/SourceReferences" } } }, "FixturePage": { "type": "object", "required": [ "items", "page", "knowledge" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Fixture" } }, "page": { "$ref": "#/components/schemas/Page" }, "knowledge": { "$ref": "#/components/schemas/Knowledge" }, "resolution": { "$ref": "#/components/schemas/FilterResolution" } } }, "SeasonDetail": { "description": "A single season read.", "allOf": [ { "$ref": "#/components/schemas/Season" }, { "type": "object", "required": [ "competition_id", "default_stage_id", "stages", "team_ids", "resolution", "knowledge" ], "properties": { "competition_id": { "$ref": "#/components/schemas/CompetitionId" }, "default_stage_id": { "description": "The stage created with the season; every season has exactly one.", "$ref": "#/components/schemas/StageId" }, "stages": { "type": "array", "items": { "$ref": "#/components/schemas/Stage" } }, "team_ids": { "type": "array", "description": "Teams entered in the season, by identifier.", "items": { "$ref": "#/components/schemas/TeamId" } }, "resolution": { "$ref": "#/components/schemas/Resolution" }, "knowledge": { "$ref": "#/components/schemas/Knowledge" }, "sources": { "$ref": "#/components/schemas/SourceReferences" }, "provenance": { "$ref": "#/components/schemas/Provenance" } } } ] }, "Stage": { "type": "object", "required": [ "id", "season_id", "label", "kind", "is_default", "ordinal", "parent_stage_id" ], "properties": { "id": { "$ref": "#/components/schemas/StageId" }, "season_id": { "$ref": "#/components/schemas/SeasonId" }, "label": { "type": "string", "description": "Structural label (`Regular season`, `Group B`); a source's round label (matchday 12) is not a stage." }, "kind": { "type": "string", "description": "The kind of stage.", "enum": [ "regular_season", "main_draw", "group", "qualifying", "knockout_round", "playoff", "final" ] }, "is_default": { "type": "boolean" }, "ordinal": { "type": "integer", "minimum": 1, "maximum": 32767 }, "parent_stage_id": { "description": "`null` for a top-level stage (the default stage always is).", "oneOf": [ { "$ref": "#/components/schemas/StageId" }, { "type": "null" } ] }, "resolution": { "$ref": "#/components/schemas/Resolution" }, "knowledge": { "$ref": "#/components/schemas/Knowledge" }, "provenance": { "$ref": "#/components/schemas/Provenance" } } }, "Club": { "type": "object", "required": [ "id", "name", "name_status", "association_code", "founded_year", "team_ids", "knowledge" ], "properties": { "id": { "$ref": "#/components/schemas/ClubId" }, "name": { "description": "The display name at `valid_at` as known at the cutoff; `null` with `name_status: unavailable` when no dated name exists.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "name_status": { "$ref": "#/components/schemas/NameStatus" }, "association_code": { "description": "Member association the club is affiliated to; `null` when unknown.", "oneOf": [ { "$ref": "#/components/schemas/AssociationCode" }, { "type": "null" } ] }, "founded_year": { "oneOf": [ { "type": "integer", "minimum": 1800, "maximum": 2100 }, { "type": "null" } ] }, "team_ids": { "type": "array", "description": "The sides the club fields.", "items": { "$ref": "#/components/schemas/TeamId" } }, "resolution": { "$ref": "#/components/schemas/Resolution" }, "knowledge": { "$ref": "#/components/schemas/Knowledge" }, "sources": { "$ref": "#/components/schemas/SourceReferences" }, "provenance": { "$ref": "#/components/schemas/Provenance" } } }, "Coordinate": { "type": "string", "description": "WGS84 coordinate in decimal degrees as an exact decimal string with up to six fraction digits, never a JSON number.", "pattern": "^-?[0-9]{1,3}\\.[0-9]{1,6}$" }, "Venue": { "type": "object", "required": [ "id", "name", "name_status", "territory", "city", "latitude", "longitude", "capacity", "opened_year", "timezone", "knowledge" ], "properties": { "id": { "$ref": "#/components/schemas/VenueId" }, "name": { "description": "The display name at `valid_at` as known at the cutoff (sponsor names are display names of their period); `null` with `name_status: unavailable` when no dated name exists.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "name_status": { "$ref": "#/components/schemas/NameStatus" }, "territory": { "description": "ISO 3166-1 alpha-2 (a commercial territory, not an association code); `null` when unknown.", "oneOf": [ { "$ref": "#/components/schemas/Territory" }, { "type": "null" } ] }, "city": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "latitude": { "oneOf": [ { "$ref": "#/components/schemas/Coordinate" }, { "type": "null" } ] }, "longitude": { "oneOf": [ { "$ref": "#/components/schemas/Coordinate" }, { "type": "null" } ] }, "capacity": { "oneOf": [ { "type": "integer", "minimum": 0, "maximum": 500000 }, { "type": "null" } ] }, "opened_year": { "oneOf": [ { "type": "integer", "minimum": 1800, "maximum": 2100 }, { "type": "null" } ] }, "timezone": { "description": "IANA zone name, for presenting local kickoffs; `null` when unknown.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "resolution": { "$ref": "#/components/schemas/Resolution" }, "knowledge": { "$ref": "#/components/schemas/Knowledge" }, "sources": { "$ref": "#/components/schemas/SourceReferences" }, "provenance": { "$ref": "#/components/schemas/Provenance" } } }, "Score": { "type": "object", "description": "A score pair for one period; both sides or neither (the owning `status` says why a pair is `null`).", "required": [ "home", "away" ], "properties": { "home": { "type": "integer", "minimum": 0, "maximum": 99 }, "away": { "type": "integer", "minimum": 0, "maximum": 99 } } }, "ResultSummary": { "type": "object", "description": "One version of a fixture's result. `score_ft` is full time (regulation including stoppage); `score_et` the aggregate after extra time, `score_pens` the shoot-out; `null` pairs mean not applicable or not yet reported, as `status` and `result_kind` say.", "required": [ "id", "version", "status", "result_kind", "score_ht", "score_ft", "score_et", "score_pens", "retracted", "decided_at", "recorded_at" ], "properties": { "id": { "$ref": "#/components/schemas/ResultId" }, "version": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "description": "`pending` = not yet (no kind, no scores); `provisional` = reported but not settled; `final` = settled (`decided_at` set).", "enum": [ "pending", "provisional", "final" ] }, "result_kind": { "description": "How the match was decided (`played`, `awarded`, `annulled`, `abandoned`); `null` exactly while `status` is `pending`.", "oneOf": [ { "type": "string", "enum": [ "played", "awarded", "annulled", "abandoned" ] }, { "type": "null" } ] }, "score_ht": { "oneOf": [ { "$ref": "#/components/schemas/Score" }, { "type": "null" } ] }, "score_ft": { "oneOf": [ { "$ref": "#/components/schemas/Score" }, { "type": "null" } ] }, "score_et": { "oneOf": [ { "$ref": "#/components/schemas/Score" }, { "type": "null" } ] }, "score_pens": { "oneOf": [ { "$ref": "#/components/schemas/Score" }, { "type": "null" } ] }, "retracted": { "type": "boolean", "description": "True when this version retracts the result." }, "decided_at": { "description": "Settlement time; `null` while pending (and optionally while provisional).", "$ref": "#/components/schemas/NullableTimestamp" }, "recorded_at": { "$ref": "#/components/schemas/Timestamp" } } }, "Result": { "allOf": [ { "$ref": "#/components/schemas/ResultSummary" }, { "type": "object", "required": [ "fixture_id", "versions", "knowledge" ], "properties": { "fixture_id": { "$ref": "#/components/schemas/FixtureId" }, "versions": { "type": "array", "description": "Every version recorded by the cutoff, oldest first; the top-level fields repeat the last one.", "minItems": 1, "items": { "$ref": "#/components/schemas/ResultSummary" } }, "knowledge": { "$ref": "#/components/schemas/Knowledge" }, "sources": { "$ref": "#/components/schemas/SourceReferences" }, "provenance": { "$ref": "#/components/schemas/Provenance" } } } ] }, "FixtureLineups": { "type": "object", "description": "A fixture's two sides with their team sheets as known at the cutoff (`GET /v1/fixtures/{id}/lineups`).", "required": [ "fixture_id", "sides", "knowledge" ], "properties": { "fixture_id": { "$ref": "#/components/schemas/FixtureId" }, "sides": { "type": "array", "description": "The home side, then the away side.", "minItems": 2, "maxItems": 2, "items": { "$ref": "#/components/schemas/LineupSide" } }, "knowledge": { "$ref": "#/components/schemas/Knowledge" }, "resolution": { "$ref": "#/components/schemas/Resolution" } } }, "LineupSide": { "type": "object", "description": "One side's team sheet. `entries` is empty unless `status` is `available`.", "required": [ "team_id", "side", "status", "sheet_complete", "formation", "formation_status", "coaches", "entries" ], "properties": { "team_id": { "$ref": "#/components/schemas/TeamId" }, "side": { "type": "string", "enum": [ "home", "away" ] }, "status": { "type": "string", "description": "`available` = the entries are served; `unavailable` = no entry is known for the side at the cutoff; `withheld` = entries exist but a source of the side holds no display right for lineups.", "enum": [ "available", "unavailable", "withheld" ] }, "sheet_complete": { "type": "boolean", "description": "True when every source of the served entries sends complete team sheets, so a player a newer sheet left out is no longer listed, and the entries name eleven starters. False otherwise, and always for a side that is not `available`. When false, the sheet may be short, as the source's own record of a match can be, or a player named in an earlier snapshot of the sheet and dropped later may still be listed. A newer sheet naming a player not yet matched to a person removes nobody until that player is matched, so until then that player is missing and one the sheet dropped may be listed, whatever the value." }, "formation": { "description": "The side's formation (`4-2-3-1`, outfield lines from defence to attack) as its source wrote it; `null` with `formation_status` `unavailable` when no formation the caller may be served is known.", "oneOf": [ { "type": "string", "pattern": "^[1-9](-[1-9]){1,5}$" }, { "type": "null" } ] }, "formation_status": { "type": "string", "description": "`known` = `formation` is served; `unavailable` = no formation is known for the side at the cutoff, or its source may not serve lineups to this caller.", "enum": [ "known", "unavailable" ] }, "coaches": { "type": "array", "description": "The side's coaches at the cutoff from sources that may serve lineups to the caller (usually one); empty when none is known.", "items": { "$ref": "#/components/schemas/LineupCoach" } }, "entries": { "type": "array", "description": "Starters first, then the bench; within each by position (goalkeeper, defender, midfielder, attacker, none) and shirt number (none last).", "items": { "$ref": "#/components/schemas/LineupEntry" } }, "sources": { "$ref": "#/components/schemas/SourceReferences" } } }, "LineupCoach": { "type": "object", "description": "A coach of the side, the highest version of the coach record recorded by the cutoff.", "required": [ "id", "version", "person_id", "recorded_at" ], "properties": { "id": { "$ref": "#/components/schemas/LineupCoachId" }, "version": { "type": "integer", "minimum": 1 }, "person_id": { "description": "The canonical person at the cutoff (a coach recorded under a person merged away since is served under the survivor).", "$ref": "#/components/schemas/PersonId" }, "recorded_at": { "$ref": "#/components/schemas/Timestamp" } } }, "LineupEntry": { "type": "object", "description": "One person's place on the side's sheet, the highest version of the lineup entry recorded by the cutoff.", "required": [ "id", "version", "person_id", "role", "bench_status", "position", "jersey_number", "formation_field", "formation_position", "recorded_at" ], "properties": { "id": { "$ref": "#/components/schemas/LineupEntryId" }, "version": { "type": "integer", "minimum": 1 }, "person_id": { "description": "The canonical person at the cutoff (an entry recorded under a person merged away since is served under the survivor).", "$ref": "#/components/schemas/PersonId" }, "role": { "type": "string", "description": "`starter` = in the named eleven, `bench` = named among the substitutes (`bench_status` says whether he came on).", "enum": [ "starter", "bench" ] }, "bench_status": { "description": "Whether a bench player came on, from the fixture's substitution events at the cutoff: `substitute` = he came on, `unused_substitute` = no event names him coming on, `unknown` = the events say nothing to this caller (the fixture is not finished or has no events, a substitution names no player, or the caller may not be served them). `null` for a starter.", "oneOf": [ { "type": "string", "enum": [ "substitute", "unused_substitute", "unknown" ] }, { "type": "null" } ] }, "position": { "description": "The position the sheet gave the player; `null` means unavailable (no source reported one).", "oneOf": [ { "type": "string", "enum": [ "goalkeeper", "defender", "midfielder", "attacker" ] }, { "type": "null" } ] }, "jersey_number": { "description": "The shirt number on the sheet; `null` means unavailable.", "oneOf": [ { "type": "integer", "minimum": 0, "maximum": 99 }, { "type": "null" } ] }, "formation_field": { "description": "The player's slot on the formation grid (`row:col`, row 1 the goalkeeper's); `null` for a bench player or when no source reported one (unavailable).", "oneOf": [ { "type": "string", "pattern": "^[0-9]{1,2}:[0-9]{1,2}$" }, { "type": "null" } ] }, "formation_position": { "description": "The source's formation position number of the slot (1 the goalkeeper); `null` like `formation_field`.", "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 30 }, { "type": "null" } ] }, "recorded_at": { "description": "When the platform recorded this version (`known_at` compares against it).", "$ref": "#/components/schemas/Timestamp" } } }, "MatchEventKind": { "type": "string", "description": "Match event kinds: `goal`, `own_goal`, `penalty_goal` (scored), `penalty_missed` (missed or saved; `detail` `penalty_saved` when saved), `yellow_card`, `second_yellow` (the second yellow, which sends the player off), `red_card` (a straight red), `substitution`, `var_decision` (a decision of its own, never an edit of the event it concerns), `shootout_goal`, `shootout_missed`.", "enum": [ "goal", "own_goal", "penalty_goal", "penalty_missed", "yellow_card", "second_yellow", "red_card", "substitution", "var_decision", "shootout_goal", "shootout_missed" ] }, "FixtureEvents": { "type": "object", "description": "A fixture's match events as known at the cutoff (`GET /v1/fixtures/{id}/events`).", "required": [ "fixture_id", "status", "events", "knowledge" ], "properties": { "fixture_id": { "$ref": "#/components/schemas/FixtureId" }, "status": { "type": "string", "description": "`available` = the events are served; `unavailable` = no event is known for the fixture at the cutoff; `withheld` = events exist but a source of them holds no display right for events.", "enum": [ "available", "unavailable", "withheld" ] }, "events": { "type": "array", "description": "In match order (minute, extra minute, then the source's event order); empty unless `status` is `available`.", "items": { "$ref": "#/components/schemas/MatchEvent" } }, "sources": { "$ref": "#/components/schemas/SourceReferences" }, "knowledge": { "$ref": "#/components/schemas/Knowledge" }, "resolution": { "$ref": "#/components/schemas/Resolution" } } }, "MatchEvent": { "type": "object", "description": "One match event, the highest version recorded by the cutoff.", "required": [ "id", "version", "kind", "detail", "team_id", "side", "period", "minute", "extra_minute", "person_id", "person_team_id", "related_person_id", "result", "info", "injured", "on_bench", "rescinded", "recorded_at" ], "properties": { "id": { "$ref": "#/components/schemas/MatchEventId" }, "version": { "type": "integer", "minimum": 1 }, "kind": { "$ref": "#/components/schemas/MatchEventKind" }, "detail": { "description": "The detail of the event from the source's sub type: `header`, `right_foot_shot`, `penalty_saved`, `goal_disallowed`, `goal_awarded`, `card_adjusted`, `red_card_cancelled`, `card_withdrawn`; more codes may be added. `null` means unavailable (none given, or not mapped yet).", "oneOf": [ { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$" }, { "type": "null" } ] }, "team_id": { "description": "The side the event counts for (an own goal is filed under the side it benefits), canonical at the cutoff.", "$ref": "#/components/schemas/TeamId" }, "side": { "type": "string", "description": "Whether `team_id` is the home or the away side.", "enum": [ "home", "away" ] }, "period": { "type": "string", "description": "The period of play, from the regulation clock minute (up to 45 first half, up to 90 second half, later extra time) and `penalty_shootout` for shootout kicks.", "enum": [ "first_half", "second_half", "extra_time", "penalty_shootout" ] }, "minute": { "type": "integer", "minimum": 0, "maximum": 200, "description": "Regulation clock minute (45+2 is minute 45 with `extra_minute` 2)." }, "extra_minute": { "description": "Stoppage minutes past `minute`; `null` when the event was not in stoppage time.", "oneOf": [ { "type": "integer", "minimum": 0, "maximum": 60 }, { "type": "null" } ] }, "person_id": { "description": "The player the event is about (the scorer, the booked player; for a substitution the player coming on), canonical at the cutoff; `null` when the source names no player (a card shown to a coach, a VAR decision).", "oneOf": [ { "$ref": "#/components/schemas/PersonId" }, { "type": "null" } ] }, "person_team_id": { "description": "The team of `person_id`'s lineup entry on the fixture (the scorer's own side for an own goal); `null` when no lineup entry the caller may be served names him, or the caller holds no `lineups` grant for the fixture (or one with a longer delay than its `events` grant).", "oneOf": [ { "$ref": "#/components/schemas/TeamId" }, { "type": "null" } ] }, "related_person_id": { "description": "The assist of a goal, the player going off in a substitution; `null` when there is none.", "oneOf": [ { "$ref": "#/components/schemas/PersonId" }, { "type": "null" } ] }, "result": { "description": "The score (home-away) after a goal as the source reported it; `null` for other events.", "oneOf": [ { "type": "string", "pattern": "^[0-9]{1,2}-[0-9]{1,2}$" }, { "type": "null" } ] }, "info": { "description": "The source's short description verbatim (`Foul`, `Header`); `null` when none.", "oneOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "injured": { "description": "The source's flag that the event involved an injury; `null` when the source did not say.", "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "on_bench": { "description": "The source's flag that the person was on the bench; `null` when the source did not say.", "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "rescinded": { "description": "The source's own flag that it withdrew the event; `null` when the source did not say.", "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "recorded_at": { "description": "When the platform recorded this version (`known_at` compares against it).", "$ref": "#/components/schemas/Timestamp" } } }, "FixtureSidelined": { "type": "object", "description": "A fixture's sidelined players as known at the cutoff (`GET /v1/fixtures/{id}/sidelined`).", "required": [ "fixture_id", "status", "entries", "knowledge" ], "properties": { "fixture_id": { "$ref": "#/components/schemas/FixtureId" }, "status": { "type": "string", "description": "`available` = the entries are served; `unavailable` = no entry is known for the fixture at the cutoff (the source sent no list, which does not mean every player was fit); `withheld` = entries exist but a source of them holds no right to serve sidelined players to this caller.", "enum": [ "available", "unavailable", "withheld" ] }, "entries": { "type": "array", "description": "Injuries first, then suspensions, then doubtful players; within each by start date (none last); empty unless `status` is `available`.", "items": { "$ref": "#/components/schemas/SidelinedEntry" } }, "sources": { "$ref": "#/components/schemas/SourceReferences" }, "knowledge": { "$ref": "#/components/schemas/Knowledge" }, "resolution": { "$ref": "#/components/schemas/Resolution" } } }, "SidelinedEntry": { "type": "object", "description": "One person unavailable or doubtful for the fixture, the highest version of the sidelined entry recorded by the cutoff.", "required": [ "id", "version", "person_id", "team_id", "side", "category", "start_date", "end_date", "games_missed", "completed", "recorded_at" ], "properties": { "id": { "$ref": "#/components/schemas/SidelinedEntryId" }, "version": { "type": "integer", "minimum": 1 }, "person_id": { "description": "The sidelined person, canonical at the cutoff.", "$ref": "#/components/schemas/PersonId" }, "team_id": { "description": "The person's side, canonical at the cutoff.", "$ref": "#/components/schemas/TeamId" }, "side": { "type": "string", "enum": [ "home", "away" ] }, "category": { "type": "string", "description": "`injury`, `suspended` or `doubtful` (the source lists the person as sidelined, but he may still play).", "enum": [ "injury", "suspended", "doubtful" ] }, "start_date": { "description": "The day the spell began; `null` means unavailable.", "oneOf": [ { "$ref": "#/components/schemas/Date" }, { "type": "null" } ] }, "end_date": { "description": "The day the spell ended or is expected to end; `null` when the source does not know.", "oneOf": [ { "$ref": "#/components/schemas/Date" }, { "type": "null" } ] }, "games_missed": { "description": "The games the spell has cost as of the source's capture; `null` means unavailable.", "oneOf": [ { "type": "integer", "minimum": 0, "maximum": 32767 }, { "type": "null" } ] }, "completed": { "description": "The source's flag that the spell is over as of its capture (not at the fixture's date); `null` means unavailable.", "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "recorded_at": { "description": "When the platform recorded this version (`known_at` compares against it).", "$ref": "#/components/schemas/Timestamp" } } }, "FixtureOfficials": { "type": "object", "description": "A fixture's officials as known at the cutoff (`GET /v1/fixtures/{id}/officials`).", "required": [ "fixture_id", "status", "officials", "knowledge" ], "properties": { "fixture_id": { "$ref": "#/components/schemas/FixtureId" }, "status": { "type": "string", "description": "`available` = the officials are served; `unavailable` = no official is known for the fixture at the cutoff; `withheld` = officials exist but a source of them holds no right to serve officials to this caller.", "enum": [ "available", "unavailable", "withheld" ] }, "officials": { "type": "array", "description": "Referee, assistant referees by `role_order`, fourth official, video assistant; empty unless `status` is `available`.", "items": { "$ref": "#/components/schemas/MatchOfficial" } }, "sources": { "$ref": "#/components/schemas/SourceReferences" }, "knowledge": { "$ref": "#/components/schemas/Knowledge" }, "resolution": { "$ref": "#/components/schemas/Resolution" } } }, "MatchOfficial": { "type": "object", "description": "One official of the fixture, the highest version recorded by the cutoff.", "required": [ "id", "version", "person_id", "role", "role_order", "recorded_at" ], "properties": { "id": { "$ref": "#/components/schemas/MatchOfficialId" }, "version": { "type": "integer", "minimum": 1 }, "person_id": { "description": "The official, canonical at the cutoff.", "$ref": "#/components/schemas/PersonId" }, "role": { "type": "string", "enum": [ "referee", "assistant_referee", "fourth_official", "video_assistant" ] }, "role_order": { "description": "1 and 2 for the first and second assistant referee; `null` for a role held once (not applicable).", "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 9 }, { "type": "null" } ] }, "recorded_at": { "description": "When the platform recorded this version (`known_at` compares against it).", "$ref": "#/components/schemas/Timestamp" } } }, "FixtureConditions": { "type": "object", "description": "A fixture's conditions as known at the cutoff (`GET /v1/fixtures/{id}/conditions`), one record per source.", "required": [ "fixture_id", "status", "conditions", "attendance", "knowledge" ], "properties": { "fixture_id": { "$ref": "#/components/schemas/FixtureId" }, "status": { "type": "string", "description": "`available` = at least one record is served; `unavailable` = no record is known for the fixture at the cutoff; `withheld` = records exist but no source of them holds the right to serve conditions to this caller.", "enum": [ "available", "unavailable", "withheld" ] }, "conditions": { "type": "array", "description": "One record per source whose source may serve the caller; empty unless `status` is `available`.", "items": { "$ref": "#/components/schemas/MatchConditions" } }, "attendance": { "description": "The reconciled attendance, taken from the first served record, in the order Sportmonks then FootyStats, that reports one; `null` when none does (unavailable).", "oneOf": [ { "type": "integer", "minimum": 0, "maximum": 200000 }, { "type": "null" } ] }, "attendance_source": { "type": "string", "description": "The provider whose record supplied `attendance`; present only with the `read:sources` scope and when that source holds a display right for conditions." }, "sources": { "$ref": "#/components/schemas/SourceReferences" }, "knowledge": { "$ref": "#/components/schemas/Knowledge" }, "resolution": { "$ref": "#/components/schemas/Resolution" } } }, "MatchConditions": { "type": "object", "description": "One source's conditions of the fixture, the highest version of its record recorded by the cutoff.", "required": [ "id", "version", "attendance", "neutral_venue", "weather", "recorded_at" ], "properties": { "id": { "$ref": "#/components/schemas/MatchConditionId" }, "version": { "type": "integer", "minimum": 1 }, "source": { "type": "string", "description": "The record's provider (`sportmonks`, `footystats`); present only with the `read:sources` scope and when the source holds a display right for conditions, left out otherwise." }, "attendance": { "description": "The crowd the source reported; `null` means unavailable.", "oneOf": [ { "type": "integer", "minimum": 0, "maximum": 200000 }, { "type": "null" } ] }, "neutral_venue": { "description": "Whether the match was played at a neutral venue; `null` means unavailable.", "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "weather": { "description": "The source's observed weather; `null` when the record holds none.", "oneOf": [ { "$ref": "#/components/schemas/MatchWeather" }, { "type": "null" } ] }, "recorded_at": { "description": "When the platform recorded this version (`known_at` compares against it).", "$ref": "#/components/schemas/Timestamp" } } }, "MatchWeather": { "type": "object", "description": "One weather reading of the source; a value it did not report is `null`.", "required": [ "basis", "temperature_c", "feels_like_c", "wind_speed", "wind_direction_deg", "humidity_pct", "pressure_hpa", "clouds_pct", "description" ], "properties": { "basis": { "type": "string", "description": "`current` = the source's observation at the match; `day` = its day values, when it has no such observation.", "enum": [ "current", "day" ] }, "temperature_c": { "description": "Air temperature, degrees Celsius.", "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "feels_like_c": { "description": "Felt temperature, degrees Celsius.", "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "wind_speed": { "description": "Wind speed in m/s.", "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "wind_direction_deg": { "description": "Wind direction in degrees.", "oneOf": [ { "type": "integer", "minimum": 0, "maximum": 360 }, { "type": "null" } ] }, "humidity_pct": { "oneOf": [ { "type": "integer", "minimum": 0, "maximum": 100 }, { "type": "null" } ] }, "pressure_hpa": { "oneOf": [ { "type": "integer", "minimum": 800, "maximum": 1100 }, { "type": "null" } ] }, "clouds_pct": { "oneOf": [ { "type": "integer", "minimum": 0, "maximum": 100 }, { "type": "null" } ] }, "description": { "description": "The source's short description (`light rain`) verbatim.", "oneOf": [ { "type": "string" }, { "type": "null" } ] } } }, "ProvenanceField": { "type": "object", "description": "The source report that supplied one field's value at the cutoff, chosen by OddsFinder's ranking of sources. `known`: the report named here supplied the value; `unavailable`: every ranked source reported only nulls; `no_observation`: no ranked source has reported the field (a value curated by OddsFinder is not a source report; a reported value outside the field's range or vocabulary, or a detailed position of another main position, counts as none); `withheld`: the source that supplied the value holds no display right for this dataset. A source that may not be shown outside OddsFinder at all is never named: when it supplied the value, the field reads as the other ranked sources leave it (`unavailable` or `no_observation`), as if that source had not reported it.", "required": [ "status", "provider", "namespace", "source_time", "source_time_precision", "observed_at", "recorded_at" ], "properties": { "status": { "type": "string", "enum": [ "known", "unavailable", "no_observation", "withheld" ] }, "provider": { "oneOf": [ { "$ref": "#/components/schemas/SourcePart" }, { "type": "null" } ] }, "namespace": { "oneOf": [ { "$ref": "#/components/schemas/SourcePart" }, { "type": "null" } ] }, "source_time": { "$ref": "#/components/schemas/NullableTimestamp" }, "source_time_precision": { "oneOf": [ { "type": "string", "enum": [ "unknown", "day", "hour", "minute", "second", "millisecond" ] }, { "type": "null" } ] }, "observed_at": { "$ref": "#/components/schemas/NullableTimestamp" }, "recorded_at": { "$ref": "#/components/schemas/NullableTimestamp" } }, "if": { "properties": { "status": { "const": "known" } } }, "then": { "properties": { "provider": { "$ref": "#/components/schemas/SourcePart" }, "namespace": { "$ref": "#/components/schemas/SourcePart" }, "observed_at": { "$ref": "#/components/schemas/Timestamp" }, "recorded_at": { "$ref": "#/components/schemas/Timestamp" } } }, "else": { "properties": { "provider": { "type": "null" }, "namespace": { "type": "null" }, "source_time": { "type": "null" }, "observed_at": { "type": "null" }, "recorded_at": { "type": "null" } } } }, "Provenance": { "type": "object", "description": "`include=provenance`: for every field whose value OddsFinder chooses among several sources, the source report its ranking of sources selects among those recorded by the cutoff. The served value is in the body; this block says where it came from. `policy` identifies the ranking used (sport and version).", "required": [ "policy", "fields" ], "properties": { "policy": { "type": "object", "required": [ "sport", "version" ], "properties": { "sport": { "type": "string", "pattern": "^[a-z][a-z_]*$" }, "version": { "type": "integer", "minimum": 1 } } }, "fields": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ProvenanceField" } } } }, "CoverageItem": { "type": "object", "required": [ "dataset", "competition_id", "territory", "from", "to", "status", "sampling_resolution_seconds", "watermark_at" ], "properties": { "dataset": { "$ref": "#/components/schemas/Dataset" }, "competition_id": { "description": "`null` means every competition.", "oneOf": [ { "$ref": "#/components/schemas/CompetitionId" }, { "type": "null" } ] }, "territory": { "oneOf": [ { "$ref": "#/components/schemas/Territory" }, { "type": "null" } ] }, "from": { "$ref": "#/components/schemas/NullableTimestamp" }, "to": { "$ref": "#/components/schemas/NullableTimestamp" }, "status": { "type": "string", "description": "`available`; `partial` (gaps inside the period, or only some covering sources may be displayed); `restricted` (limited by the caller's grant, or no covering source may be displayed; its period, sampling and `watermark_at` are then null and no source references are given); `unsupported` (the platform does not offer it); `unavailable` (temporarily cannot be served).", "enum": [ "available", "partial", "restricted", "unsupported", "unavailable" ] }, "sampling_resolution_seconds": { "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "watermark_at": { "$ref": "#/components/schemas/NullableTimestamp" }, "sources": { "$ref": "#/components/schemas/SourceReferences" } } }, "CoveragePage": { "type": "object", "required": [ "items", "page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CoverageItem" } }, "page": { "$ref": "#/components/schemas/Page" } } }, "Principal": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "user", "api_client" ] }, "id": { "type": "string", "minLength": 1 } } }, "DatasetGrant": { "type": "object", "required": [ "dataset", "competition_ids", "territories", "freshness_delay_seconds", "lookback_days" ], "properties": { "dataset": { "$ref": "#/components/schemas/Dataset" }, "competition_ids": { "description": "`null` means every competition.", "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/CompetitionId" } }, { "type": "null" } ] }, "territories": { "description": "`null` means no territory restriction.", "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/Territory" } }, { "type": "null" } ] }, "freshness_delay_seconds": { "type": "integer", "minimum": 0 }, "lookback_days": { "description": "`null` means unlimited history depth.", "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] } } }, "Entitlements": { "type": "object", "required": [ "principal", "organization_id", "scopes", "grant_version", "source_rights_version", "policy_version", "territory", "freshness_delay_seconds", "lookback_days", "datasets" ], "properties": { "principal": { "$ref": "#/components/schemas/Principal" }, "organization_id": { "oneOf": [ { "$ref": "#/components/schemas/OrganizationId" }, { "type": "null" } ] }, "scopes": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_:.-]*$" } }, "grant_version": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "source_rights_version": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "policy_version": { "type": "string" }, "territory": { "description": "Cross-dataset summary (the first territory any grant names); each read applies its own dataset's grant in `datasets[].territories`.", "oneOf": [ { "$ref": "#/components/schemas/Territory" }, { "type": "null" } ] }, "freshness_delay_seconds": { "description": "Cross-dataset summary (the largest delay of any grant); each read applies its own dataset's grant in `datasets[].freshness_delay_seconds`.", "type": "integer", "minimum": 0 }, "lookback_days": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "datasets": { "type": "array", "items": { "$ref": "#/components/schemas/DatasetGrant" } } } }, "Usage": { "type": "object", "required": [ "principal", "organization_id", "from", "to", "requests", "quota", "limits", "policy_version" ], "properties": { "principal": { "$ref": "#/components/schemas/Principal" }, "organization_id": { "oneOf": [ { "$ref": "#/components/schemas/OrganizationId" }, { "type": "null" } ] }, "from": { "$ref": "#/components/schemas/Timestamp" }, "to": { "$ref": "#/components/schemas/Timestamp" }, "requests": { "type": "object", "description": "Logical requests in the window. `metered` counts billable units once per logical request, however often it was retried; `cached` and `rejected` are reported separately and not metered.", "required": [ "metered", "cached", "rejected" ], "properties": { "metered": { "type": "integer", "minimum": 0 }, "cached": { "type": "integer", "minimum": 0 }, "rejected": { "type": "integer", "minimum": 0 } } }, "quota": { "type": "object", "required": [ "limit", "remaining", "resets_at" ], "properties": { "limit": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "remaining": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "resets_at": { "$ref": "#/components/schemas/NullableTimestamp" } } }, "limits": { "type": "array", "description": "Every limit that applies to the caller, in the order `requests_per_minute`, `requests_per_day`, then any per-dataset allowance, each in its window that contains the usage window's last instant (pass `to` just after the current instant for the current minute). An organization lists its configured limits (`requests_per_minute` counts every request, the allowances only requests in flight or served); a caller without an organization lists the default per-caller `requests_per_minute`, counting its recorded requests (refusals included, so `used` may exceed `limit`) and this one. `quota` repeats the `requests_per_day` entry.", "items": { "$ref": "#/components/schemas/LimitUsage" } }, "policy_version": { "type": "string" } } }, "LimitUsage": { "type": "object", "required": [ "limit_kind", "limit", "used", "remaining", "window_start", "resets_at" ], "properties": { "limit_kind": { "type": "string", "enum": [ "requests_per_minute", "requests_per_day" ] }, "limit": { "type": "integer", "minimum": 0 }, "used": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "minimum": 0 }, "window_start": { "$ref": "#/components/schemas/Timestamp" }, "resets_at": { "$ref": "#/components/schemas/Timestamp" } } }, "FixtureStatistics": { "type": "object", "description": "A fixture's team and player statistics as known at the cutoff (`GET /v1/fixtures/{id}/statistics`).", "required": [ "fixture_id", "status", "statistics", "knowledge" ], "properties": { "fixture_id": { "$ref": "#/components/schemas/FixtureId" }, "status": { "type": "string", "description": "`available` = at least one value is served; `unavailable` = no value matching the filters is known at the cutoff; `withheld` = matching values exist but no source of them holds a display right for statistics.", "enum": [ "available", "unavailable", "withheld" ] }, "statistics": { "type": "array", "description": "Home side first; a side's own values, then its players by person identifier; then metric and period scope. Empty unless `status` is `available`.", "items": { "$ref": "#/components/schemas/StatisticValue" } }, "knowledge": { "$ref": "#/components/schemas/Knowledge" }, "resolution": { "$ref": "#/components/schemas/Resolution" }, "sources": { "$ref": "#/components/schemas/SourceReferences" } } }, "StatisticValue": { "type": "object", "description": "One value of a side or one of its players, the highest version recorded by the cutoff.", "required": [ "id", "version", "team_id", "person_id", "lineup_entry_id", "metric", "unit", "period_scope", "value", "recorded_at" ], "properties": { "id": { "$ref": "#/components/schemas/StatisticObservationId" }, "version": { "type": "integer", "minimum": 1 }, "team_id": { "description": "The side the value belongs to, canonical at the cutoff.", "$ref": "#/components/schemas/TeamId" }, "person_id": { "description": "The player the value describes (canonical at the cutoff); `null` for the side's own value (not applicable).", "oneOf": [ { "$ref": "#/components/schemas/PersonId" }, { "type": "null" } ] }, "lineup_entry_id": { "description": "The player's lineup entry as `GET /v1/fixtures/{id}/lineups` serves it to the same caller at the same cutoff; `null` for a team value or when no served entry names him.", "oneOf": [ { "$ref": "#/components/schemas/LineupEntryId" }, { "type": "null" } ] }, "metric": { "$ref": "#/components/schemas/StatisticMetric" }, "unit": { "type": "string", "description": "The metric's unit; `percent` is 0..100 as the source sends it, `rating_0_10` a source's own player rating.", "enum": [ "count", "percent", "minutes", "rating_0_10" ] }, "period_scope": { "$ref": "#/components/schemas/StatisticPeriodScope" }, "value": { "type": "number", "description": "The value as the source sent it (a value with more than four decimals is rounded to four)." }, "definition_version": { "type": "string", "description": "The source definition the value was mapped under (`sportmonks.1`); values of two definitions are not comparable. It names the source, so it follows the source-reference rules of `sources`, per value; it is present only with the `read:sources` scope and when the value's source holds a display right for statistics, and left out otherwise." }, "recorded_at": { "description": "When the platform recorded this version (`known_at` compares against it).", "type": "string" } } }, "StatisticPeriodScope": { "type": "string", "description": "The part of the match a value covers. `first_half` and `second_half` are each half alone; `as_reported` is the source's whole match where the source does not say whether extra time is included.", "enum": [ "first_half", "second_half", "regulation_time", "regulation_and_extra_time", "including_penalties", "pre_match", "as_reported" ] }, "StatisticMetric": { "type": "string", "description": "A metric code of the curated statistics vocabulary; each metric has one unit.", "enum": [ "goals", "own_goals", "assists", "shots_total", "shots_on_target", "shots_off_target", "shots_blocked", "shots_inside_box", "shots_outside_box", "goal_attempts", "hit_woodwork", "big_chances_created", "big_chances_missed", "chances_created", "key_passes", "passes", "passes_accurate", "passes_accurate_percentage", "passes_successful", "passes_successful_percentage", "passes_final_third", "backward_passes", "long_balls", "long_balls_won", "long_balls_won_percentage", "long_passes", "long_passes_successful", "long_passes_successful_percentage", "through_balls", "through_balls_won", "crosses_total", "crosses_accurate", "crosses_accurate_percentage", "ball_possession", "attacks", "dangerous_attacks", "ball_safe", "touches", "turnovers", "possession_lost", "dispossessed", "duels_total", "duels_won", "duels_lost", "duels_won_percentage", "aerials_total", "aerials_won", "aerials_lost", "aerials_won_percentage", "successful_headers", "dribbles_attempted", "dribbles_successful", "dribbles_successful_percentage", "dribbled_past", "tackles", "tackles_won", "tackles_won_percentage", "last_man_tackles", "interceptions", "clearances", "blocks", "ball_recoveries", "offsides_provoked", "errors_leading_to_shot", "saves", "saves_inside_box", "punches", "high_claims", "goals_conceded", "goalkeeper_goals_conceded", "goal_kicks", "fouls_committed", "fouls_drawn", "yellow_cards", "second_yellow_cards", "red_cards", "offsides", "corners", "free_kicks", "throw_ins", "substitutions", "injuries", "minutes_played", "cumulative_minutes_played", "rating" ] }, "StageId": { "type": "string", "description": "Stage identifier (`stg_`).", "pattern": "^stg_[1-9][0-9]{0,18}$" }, "VenueId": { "type": "string", "description": "Venue identifier (`ven_`).", "pattern": "^ven_[1-9][0-9]{0,18}$" }, "MatchEventId": { "type": "string", "description": "Match event identifier (`ev_`).", "pattern": "^ev_[1-9][0-9]{0,18}$" }, "LineupEntryId": { "type": "string", "description": "Lineup entry identifier (`lu_`).", "pattern": "^lu_[1-9][0-9]{0,18}$" }, "StatisticObservationId": { "type": "string", "description": "Statistic observation identifier (`st_`).", "pattern": "^st_[1-9][0-9]{0,18}$" }, "ResultId": { "type": "string", "description": "Result identifier (`res_`).", "pattern": "^res_[1-9][0-9]{0,18}$" }, "SidelinedEntryId": { "type": "string", "description": "Sidelined entry identifier (`sdl_`).", "pattern": "^sdl_[1-9][0-9]{0,18}$" }, "MatchOfficialId": { "type": "string", "description": "Match official identifier (`mo_`).", "pattern": "^mo_[1-9][0-9]{0,18}$" }, "MatchConditionId": { "type": "string", "description": "Match condition identifier (`mc_`).", "pattern": "^mc_[1-9][0-9]{0,18}$" }, "LineupCoachId": { "type": "string", "description": "Lineup coach identifier (`lc_`).", "pattern": "^lc_[1-9][0-9]{0,18}$" }, "RevisionId": { "type": "string", "description": "Revision identifier (`rev_`).", "pattern": "^rev_[1-9][0-9]{0,18}$" } } } }