openapi: 3.2.0 info: title: 5DollarFootballAPI — Football Data Fixtures API version: 1.0.0 summary: 'Football (soccer) data: live scores, fixtures, standings, corner and card statistics, and odds.' description: 'The 5DollarFootballAPI is a read-only REST API. Every response is JSON with a top-level "success" flag. All timestamps are UTC (ISO-8601). The base URL is https://api.5dollarfootballapi.com/v1. Authenticate every request with your API key in an Authorization header: `Authorization: Bearer fb_live_your_key`. You can also send it as `X-API-Key`. Get a key by creating a free account — no card required. Keys are shown once; store them securely and never embed them in public client-side code. Each plan has a per-minute rate window — short parallel bursts are fine as long as the minute total holds, and there are no daily caps or monthly pools. Every response includes `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` for the current window. When you exceed the limit you get HTTP 429 with a `Retry-After` header — back off and retry. List endpoints accept `page` (default 1) and `per_page` (default 50, max 100), and return a `pagination` object: `{ page, per_page, count, has_more }`. Keep requesting the next page while `has_more` is true. The underlying set can change between two page requests (a match kicks off or finishes); for the volatile live view, request `status=live` with a large `per_page` (up to 500) so a single page holds everything. Errors return `{ "success": 0, "error": { ... } }` with an HTTP status. The error object has a machine-readable `type` and `code`, a human `message`, an optional `param`, a `doc_url`, and a `request_id` to quote in support. We never return a silent `200` with empty data for a missing resource — you get a proper 404.' termsOfService: https://5dollarfootballapi.com/terms contact: name: 5DollarFootballAPI support url: https://5dollarfootballapi.com/contact email: contact@5dollarfootballapi.com servers: - url: https://api.5dollarfootballapi.com/v1 description: Production security: - bearerAuth: [] - apiKeyHeader: [] tags: - name: fixtures description: 'Matches: the daily window and per-fixture detail — events, statistics, odds and odds history.' paths: /fixtures: get: operationId: fixtures summary: List fixtures description: 'The window view: fixtures and results for a time window of up to 24 hours (default: today UTC), or every in-play match with ?status=live. For a whole season or one team''s matches, see /v1/leagues/{id}/fixtures and /v1/teams/{id}/fixtures. Add ?include=odds,events,stats to expand every row in place — one call per screen, not one call per match. How far back you can query follows your plan: 3 months on Free, 12 months on Pro, back to 2014 on Ultra.' tags: - fixtures parameters: - name: start_time in: query required: false description: Window start as a unix timestamp (seconds, UTC), inclusive. Defaults to 00:00 UTC today; if only end_time is sent, defaults to 24h before it. schema: type: integer - name: end_time in: query required: false description: Window end as a unix timestamp (seconds, UTC), exclusive. Defaults to start_time + 24h. The window may span at most 24 hours — pick any day boundary in any timezone. schema: type: integer - name: league in: query required: false description: Filter by league id. schema: type: integer - name: status in: query required: false description: all | scheduled | live | finished. Defaults to all. "live" returns every in-play match right now, regardless of date. schema: type: string - name: include in: query required: false description: Comma list of odds | events | stats — expands each fixture with the Bet365 market lines (paid plans), the event timeline, and the in-play statistics, in the same shapes as the per-fixture endpoints. Caps per_page at 50. schema: type: string - name: esports in: query required: false description: true | false. Defaults to false (real football only); true returns esoccer (e-football) matches instead. schema: type: boolean - name: lang in: query required: false description: Localize team & league names (21 languages besides English, e.g. zh-cn, ja, es, de, pt). Missing translations fall back to English. schema: type: string - name: page in: query required: false description: Pagination (per_page max 100; 50 with include; 500 with status=live, so one page holds every live match). schema: type: integer - name: per_page in: query required: false description: Pagination (per_page max 100; 50 with include; 500 with status=live, so one page holds every live match). schema: type: integer responses: '200': description: Success headers: X-RateLimit-Limit: description: Requests allowed in the current window. schema: type: integer X-RateLimit-Remaining: description: Requests left in the current window. schema: type: integer X-RateLimit-Reset: description: Unix timestamp when the window resets. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/SuccessEnvelope' example: success: 1 data: - id: 197590518 league: id: 43659 name: USA USL Cup teams: home: id: 51386 name: Birmingham Legion FC away: id: 58558 name: Tulsa kickoff_utc: '2026-07-12T00:00:00+00:00' kickoff_ts: 1783814400 status: finished goals: home: 3 away: 1 corners: home: 13 away: 4 cards: home: yellow: 1 red: 0 away: yellow: 4 red: 0 odds: 1x2: opening: home: 1.53 draw: 3.75 away: 5 closing: home: 1.18 draw: 5.5 away: 15 inplay: null asian_handicap: opening: -0.25 closing: -0.5 inplay: -1 goal_line: opening: 2.5 closing: 2.75 inplay: 3 corner_line: opening: 9.5 closing: 10 inplay: 10.5 corner_asian: opening: 0 closing: -0.5 inplay: null card_line: opening: 4.5 closing: 5 inplay: null card_asian: opening: 0 closing: 0 inplay: null asian_handicap_half: closing: -0.25 inplay: null goal_line_half: closing: 1.25 inplay: 1.5 corner_line_half: closing: 4.5 inplay: 5 statistics: attacks: home: 24 away: 30 dangerous_attacks: home: 11 away: 14 shots_on_target: home: 3 away: 5 shots_off_target: home: 4 away: 2 possession: home: 51 away: 49 first_half: attacks: home: 15 away: 18 dangerous_attacks: home: 6 away: 8 shots_on_target: home: 1 away: 2 shots_off_target: home: 2 away: 0 possession: home: 50 away: 50 events: - type: goal minute: 20 team: away count: 1 - type: corner minute: 23 team: home count: 1 - type: yellow_card minute: 41 team: home count: 1 - type: period_score minute: null team: null period: first_half score: home: 0 away: 1 - type: missed_penalty minute: 55 team: away - type: substitution minute: 63 team: away player_in: R. Silva player_out: J. Costa - type: red_card minute: 78 team: away - type: period_score minute: null team: null period: second_half score: home: 3 away: 1 pagination: page: 1 per_page: 50 count: 1 has_more: true '400': description: Invalid parameter. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '403': description: The resource is outside your plan. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer '500': description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' externalDocs: description: Endpoint reference url: https://5dollarfootballapi.com/docs/fixtures /fixtures/{id}: get: operationId: fixture summary: Get a fixture description: A single fixture with goals, corners, cards and odds lines. Add ?include=events,stats to fold the event timeline and in-play statistics into the same call. tags: - fixtures parameters: - name: id in: path required: true description: Fixture id. schema: type: integer - name: include in: query required: false description: Comma list of events | stats — adds the event timeline and in-play statistics, in the same shapes as the per-fixture endpoints. schema: type: string - name: lang in: query required: false description: Localize the team & league names (21 languages, English fallback). schema: type: string responses: '200': description: Success headers: X-RateLimit-Limit: description: Requests allowed in the current window. schema: type: integer X-RateLimit-Remaining: description: Requests left in the current window. schema: type: integer X-RateLimit-Reset: description: Unix timestamp when the window resets. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/SuccessEnvelope' example: success: 1 data: id: 197590518 league: id: 43659 name: USA USL Cup teams: home: id: 51386 name: Birmingham Legion FC away: id: 58558 name: Tulsa kickoff_utc: '2026-07-12T00:00:00+00:00' kickoff_ts: 1783814400 status: finished round: 12 league_season_id: 141207 goals: home: 3 away: 1 half_home: 1 half_away: 1 corners: home: 13 away: 4 half_home: 6 half_away: 2 cards: home: yellow: 1 red: 0 away: yellow: 4 red: 0 odds: 1x2: opening: home: 1.53 draw: 3.75 away: 5 closing: home: 1.18 draw: 5.5 away: 15 inplay: null asian_handicap: opening: -0.5 closing: -0.75 inplay: -1 goal_line: opening: 2.5 closing: 2.75 inplay: 3 corner_line: opening: 9.5 closing: 10 inplay: 10.5 corner_asian: opening: 0 closing: -0.5 inplay: null card_line: opening: 4.5 closing: 5 inplay: null card_asian: opening: 0 closing: 0 inplay: null asian_handicap_half: closing: -0.25 inplay: null goal_line_half: closing: 1.25 inplay: 1.5 corner_line_half: closing: 4.5 inplay: 5 statistics: attacks: home: 24 away: 30 dangerous_attacks: home: 11 away: 14 shots_on_target: home: 3 away: 5 shots_off_target: home: 4 away: 2 possession: home: 51 away: 49 first_half: attacks: home: 15 away: 18 dangerous_attacks: home: 6 away: 8 shots_on_target: home: 1 away: 2 shots_off_target: home: 2 away: 0 possession: home: 50 away: 50 events: - type: goal minute: 20 team: away count: 1 - type: corner minute: 23 team: home count: 1 - type: yellow_card minute: 41 team: home count: 1 - type: period_score minute: null team: null period: first_half score: home: 1 away: 1 - type: missed_penalty minute: 55 team: away - type: substitution minute: 63 team: away player_in: R. Silva player_out: J. Costa - type: red_card minute: 78 team: away - type: period_score minute: null team: null period: second_half score: home: 3 away: 1 '400': description: Invalid parameter. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '403': description: The resource is outside your plan. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: No such resource. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer '500': description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' externalDocs: description: Endpoint reference url: https://5dollarfootballapi.com/docs/fixture /fixtures/{id}/odds: get: operationId: odds summary: Fixture odds description: 'Full prices for every market, one entry per requested bookmaker — each of opening, closing and in-play carries the line and both prices. Bet365 (the default) serves eleven markets: 1X2 plus Asian handicap, goal, corner, corner-Asian and card lines — full-time and half-time — and both-teams-to-score. Add more books with ?bookmakers=bet365,pinnacle,… (GET /v1/bookmakers) — they carry 1X2, Asian handicap, goal line and corner line where recorded. Bookmakers beyond bet365 require the Ultra plan.' tags: - fixtures parameters: - name: id in: path required: true description: Fixture id. schema: type: integer - name: bookmakers in: query required: false description: Comma list of bookmaker slugs, default bet365 — e.g. bet365,pinnacle,1xbet. One odds entry per bookmaker; slugs come from GET /v1/bookmakers. Non-bet365 slugs need the Ultra plan. schema: type: string - name: market in: query required: false description: 1x2 | asian | goalline | corner | corner_asian | cards | cards_asian | asian_half | goalline_half | corner_half | btts. schema: type: string responses: '200': description: Success headers: X-RateLimit-Limit: description: Requests allowed in the current window. schema: type: integer X-RateLimit-Remaining: description: Requests left in the current window. schema: type: integer X-RateLimit-Reset: description: Unix timestamp when the window resets. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/SuccessEnvelope' example: success: 1 data: fixture_id: 197590518 bookmakers: - id: 281 name: Bet 365 slug: bet365 odds: 1x2: opening: home: 1.53 draw: 3.75 away: 5 closing: home: 1.18 draw: 5.5 away: 15 inplay: null asian_handicap: opening: line: -0.25 home: 1.95 away: 1.85 closing: line: -0.5 home: 2.02 away: 1.78 inplay: line: -1 home: 1.9 away: 1.9 goal_line: opening: line: 2.5 over: 1.9 under: 1.9 closing: line: 2.75 over: 1.85 under: 1.95 inplay: line: 3 over: 2.05 under: 1.75 corner_line: opening: line: 9.5 over: 1.85 under: 1.85 closing: line: 10 over: 1.9 under: 1.8 inplay: line: 10.5 over: 2 under: 1.7 corner_asian: opening: line: 0 home: 1.875 away: 1.875 closing: null inplay: null card_line: opening: line: 4.5 over: 1.95 under: 1.75 closing: line: 5 over: 1.85 under: 1.85 inplay: null card_asian: opening: line: 0 home: 1.9 away: 1.8 closing: null inplay: null asian_handicap_half: opening: line: -0.25 home: 1.98 away: 1.82 closing: line: -0.25 home: 2.05 away: 1.75 inplay: null goal_line_half: opening: line: 1 over: 1.95 under: 1.85 closing: line: 1.25 over: 2 under: 1.8 inplay: line: 1.5 over: 2.1 under: 1.7 corner_line_half: opening: line: 4.5 over: 1.85 under: 1.85 closing: line: 4.5 over: 1.9 under: 1.8 inplay: line: 5 over: 2 under: 1.7 btts: opening: 'yes': 1.8 'no': 1.95 closing: 'yes': 1.72 'no': 2.05 inplay: null '400': description: Invalid parameter. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '403': description: The resource is outside your plan. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: No such resource. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer '500': description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' externalDocs: description: Endpoint reference url: https://5dollarfootballapi.com/docs/odds /fixtures/{id}/odds/history: get: operationId: oddsHistory summary: Odds movement history description: 'The full pre-match and in-play tick history for one market — every recorded price/line change with the score at that moment. Bet365 (the default) carries twelve markets: 1X2, Asian handicap, goal line and corner line (each full-time and half-time), plus corner Asian handicap, card line, card Asian handicap and both-teams-to-score. Any other bookmaker (?bookmaker=, one at a time) carries 1x2, asian, goalline and corner. Ultra plan and above.' tags: - fixtures parameters: - name: id in: path required: true description: Fixture id. schema: type: integer - name: bookmaker in: query required: false description: One bookmaker slug, default bet365 (see GET /v1/bookmakers). Non-bet365 books carry 1x2, asian, goalline and corner. schema: type: string - name: market in: query required: true description: 1x2 | asian | goalline | corner | 1x2_half | asian_half | goalline_half | corner_half | corner_asian | cards | cards_asian | btts. schema: type: string - name: page in: query required: false description: Pagination (per_page default 100, max 500). Ticks are ordered oldest first. schema: type: integer - name: per_page in: query required: false description: Pagination (per_page default 100, max 500). Ticks are ordered oldest first. schema: type: integer responses: '200': description: Success headers: X-RateLimit-Limit: description: Requests allowed in the current window. schema: type: integer X-RateLimit-Remaining: description: Requests left in the current window. schema: type: integer X-RateLimit-Reset: description: Unix timestamp when the window resets. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/SuccessEnvelope' example: success: 1 data: fixture_id: 197864561 bookmaker: id: 281 name: Bet 365 slug: bet365 market: asian ticks: - minute: null line: -1.5 home: 1.8 away: 2 score: home: null away: null recorded_at: '2026-07-16T23:33:40+00:00' - minute: null line: -1.5 home: 1.875 away: 1.925 score: home: null away: null recorded_at: '2026-07-17T09:12:04+00:00' - minute: null line: -1.75 home: 1.8 away: 2 score: home: null away: null recorded_at: '2026-07-17T14:40:51+00:00' - minute: null line: -1.75 home: 1.825 away: 1.975 score: home: null away: null recorded_at: '2026-07-17T18:55:19+00:00' - minute: 2 line: -1.75 home: 1.85 away: 1.95 score: home: 0 away: 0 recorded_at: '2026-07-17T19:02:35+00:00' - minute: 14 line: -1.5 home: 1.9 away: 1.9 score: home: 0 away: 0 recorded_at: '2026-07-17T19:14:48+00:00' - minute: 23 line: -1 home: 1.875 away: 1.925 score: home: 1 away: 0 recorded_at: '2026-07-17T19:23:57+00:00' - minute: 38 line: -1.25 home: 1.95 away: 1.85 score: home: 1 away: 0 recorded_at: '2026-07-17T19:38:20+00:00' - minute: 51 line: -0.75 home: 1.9 away: 1.9 score: home: 2 away: 0 recorded_at: '2026-07-17T20:06:11+00:00' - minute: 64 line: -0.5 home: 1.85 away: 1.95 score: home: 2 away: 1 recorded_at: '2026-07-17T20:19:44+00:00' - minute: 79 line: -0.25 home: 1.975 away: 1.825 score: home: 2 away: 1 recorded_at: '2026-07-17T20:34:29+00:00' pagination: page: 1 per_page: 100 count: 11 has_more: false '400': description: Invalid parameter. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '403': description: The resource is outside your plan. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: No such resource. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer '500': description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' externalDocs: description: Endpoint reference url: https://5dollarfootballapi.com/docs/odds-history /fixtures/{id}/events: get: operationId: events summary: Fixture events description: 'The chronological match timeline: goals, corners, yellow and red cards, substitutions, missed penalties, and half-time / full-time period scores — corners included, which most football APIs leave out.' tags: - fixtures parameters: - name: id in: path required: true description: Fixture id. schema: type: integer responses: '200': description: Success headers: X-RateLimit-Limit: description: Requests allowed in the current window. schema: type: integer X-RateLimit-Remaining: description: Requests left in the current window. schema: type: integer X-RateLimit-Reset: description: Unix timestamp when the window resets. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/SuccessEnvelope' example: success: 1 data: fixture_id: 197590518 events: - type: corner minute: 3 team: home count: 1 - type: goal minute: 4 team: home count: 1 - type: yellow_card minute: 27 team: away count: 1 - type: period_score minute: null team: null period: first_half score: home: 1 away: 0 - type: missed_penalty minute: 49 team: away - type: substitution minute: 60 team: home player_in: R. Lewis player_out: J. Cole - type: red_card minute: 78 team: away - type: period_score minute: null team: null period: second_half score: home: 2 away: 1 '400': description: Invalid parameter. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '403': description: The resource is outside your plan. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: No such resource. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer '500': description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' externalDocs: description: Endpoint reference url: https://5dollarfootballapi.com/docs/events /fixtures/{id}/statistics: get: operationId: statistics summary: Fixture statistics description: 'Live match statistics: attacks, shots and possession — with first-half splits.' tags: - fixtures parameters: - name: id in: path required: true description: Fixture id. schema: type: integer responses: '200': description: Success headers: X-RateLimit-Limit: description: Requests allowed in the current window. schema: type: integer X-RateLimit-Remaining: description: Requests left in the current window. schema: type: integer X-RateLimit-Reset: description: Unix timestamp when the window resets. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/SuccessEnvelope' example: success: 1 data: fixture_id: 197590518 statistics: attacks: home: 112 away: 88 dangerous_attacks: home: 54 away: 39 shots_on_target: home: 6 away: 3 shots_off_target: home: 7 away: 5 possession: home: 58 away: 42 first_half: attacks: home: 47 away: 40 dangerous_attacks: home: 23 away: 18 shots_on_target: home: 2 away: 1 shots_off_target: home: 3 away: 2 possession: home: 55 away: 45 '400': description: Invalid parameter. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '403': description: The resource is outside your plan. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: No such resource. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer '500': description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' externalDocs: description: Endpoint reference url: https://5dollarfootballapi.com/docs/statistics components: schemas: SuccessEnvelope: type: object description: Every successful response. `data` is the endpoint payload — see the example on each operation. List endpoints add `pagination`. required: - success - data properties: success: type: integer const: 1 data: description: 'Endpoint payload: an object, or an array of objects on list endpoints.' oneOf: - type: object - type: array items: type: object pagination: $ref: '#/components/schemas/Pagination' Pagination: type: object description: Returned by list endpoints. Keep requesting pages while `has_more` is true. properties: page: type: integer per_page: type: integer count: type: integer description: Rows on this page. has_more: type: boolean ErrorEnvelope: type: object description: Every error response. The status code and `error.code` identify the failure; `message` is for humans. required: - success - error properties: success: type: integer const: 0 error: type: object required: - type - code - message properties: type: type: string description: Error family, e.g. authentication_error. code: type: string description: Machine-readable code, e.g. missing_api_key. message: type: string param: type: - string - 'null' description: The parameter at fault, when one applies. doc_url: type: string request_id: type: string description: Quote this in support requests. securitySchemes: bearerAuth: type: http scheme: bearer description: 'Send your key as `Authorization: Bearer `.' apiKeyHeader: type: apiKey in: header name: X-API-Key description: Alternative to the Authorization header. externalDocs: description: Full documentation url: https://5dollarfootballapi.com/docs