Build on association-football data.

One authenticated REST gateway at /api/v1/football/{feedId} for fixtures, scores, standings, squads, team and player profiles, leaderboards and match statistics. Media routes return crests, player photos and venue images.

Gateway for this environment: https://footballapi.net. Customer feeds live under /api/v1/football. The intended production domain is https://footballapi.net.

Authentication#

Create keys in Dashboard, API keys. The secret is shown once; store it server-side, for example as FOOTBALLAPI_KEY, and send it on every request:

X-API-Key: $FOOTBALLAPI_KEY

• Never place keys in URLs, query strings or browser code.
• Revoke a leaked key immediately and create a new one.
• These public docs never ask for or store your key.

Access and pricing status#

An account and a key do not by themselves grant feed access. Choose a plan through the secure on-site checkout in Dashboard → Billing; paid access activates after payment is confirmed. Save your Starter leagues before subscribing to Starter. Some services require separate activation or IP whitelisting. Ask through contact or dashboard support.

Rate limits#

Included successful feed requests apply per account across all keys: Starter 5,000/day, Growth 25,000/day and Pro 250,000/day. Allowances reset at midnight UTC without rollover; they are not monthly quotas.

On a paid subscription with overage billing, requests continue after the included daily allowance. Each additional successful request costs €0.002 and is added in arrears to the monthly EUR subscription invoice. For example, 1,000 additional requests cost €2.00; 10,000 cost €20.00. Invoice totals are calculated from the aggregated quantity and then rounded to cents, not rounded per request. Failed, invalid and denied requests are not billed. Requests served from our cache count as successful feed requests.

The Usage page shows today's successful requests, the daily reset time, additional requests in the current subscription period and the estimated extra charge. Daily unused requests do not roll over. Cancelling stops renewal, not charges for extra usage already incurred; scheduled plan changes apply at the next renewal.

• HTTP 429 includes Retry-After in seconds. An account safety limit of 100 requests/second applies independently of paid overages.
• Extra keys do not create extra allowance.
• Manual access without agreed metered billing remains capped at its approved daily allowance.
• Response headers include X-Usage-Daily-Included, X-Usage-Daily-Used, X-Usage-Daily-Remaining, X-Usage-Daily-Reset (Unix seconds) and X-Usage-Overage-Rate-EUR.

Feed catalogue#

Feed IDs and their parameters are published at GET /api/football/catalogue. Only feeds individually enabled after qualification can run; others return an error.

* required. More detail on the coverage page.

Live-feed IP whitelisting#

Some live services, including ball tracking and certain live-odds feeds, require IP whitelisting before access can be activated.

Contact support@footballapi.net to confirm which services require whitelisting and register your application’s public server IP addresses. Use the public outbound IP addresses your application connects from, not a private/local IP or a website domain.

Access is enabled only after the required setup and service checks are complete. Approval for one service does not automatically activate other services. Contact support before changing a registered IP address.

Errors and retries#

Errors return JSON with error, code and requestId. Quote the request ID when contacting support.

{
  "error": "Feed is not enabled",
  "code": "feed_not_enabled",
  "requestId": "req_example_not_live"
}

Illustrative body. Exact codes are in the API reference.

Field semantics#

• Status strings, kick-off times and update stamps are passed through as supplied. Unconfirmed timezones are not converted.
• Missing source values stay empty. Absent collections stay empty arrays.
• IDs are strings. Use IDs from responses, not names, as join keys.
• Upstream failures return a classified error rather than invented empty data.

Media#

Team crests /api/football/media/teams/{id}, player photos /api/football/media/players/{id} and venue images /api/football/media/venues/{teamId}. Venue images are keyed by team ID. League logos are not verified and not offered.

Build a football-data integration#

Start with the competition directory feed to discover valid league IDs, then call the feed you need under /api/v1/football/{feedId}. Feed IDs and their parameters come from GET /api/football/catalogue. Treat every ID as a string.

Sample IDs used in our checks: league 1204, team 9260, player 194646. Use IDs returned by your own requests in production. Images require an active Growth or Pro account key in Authorization or X-API-Key, share the account daily allowance and are returned with private, no-store caching. Fetch image bytes server-side with your key; a bare public image URL will not authenticate.

• Status strings such as FT, HT, Postp. or a kick-off time are passed through as supplied. Map them in your own UI and keep unknown values visible.
• Update timestamps on the scores feed are in a timezone that is still being confirmed. Do not convert them silently.
• Predicted line-ups are team-selection forecasts for selected leagues, not betting predictions.
• League logos are not verified and are not offered. Use your own competition labels.

Polling, caching and pagination#

Football feeds use HTTP polling. There is no qualified WebSocket or live push service; the upstream live service was blocked during checks. Cache responses in your backend rather than making one request per visitor.

• All keys on an account share the daily included allowance: Starter 5,000, Growth 25,000 and Pro 250,000 successful requests. It resets at midnight UTC without rollover. Extra successful metered requests cost €0.002 each, invoiced monthly in EUR; failed or denied attempts are not billed. Your usage and estimated extra charge appear in the dashboard.
• Treat a list as a moving view. Deduplicate using match, team and player IDs.
• Use timeouts and bounded retries and respect Retry-After. See the retry example.

Display crests and photos#

Media routes return images directly and are cached by us. Check the HTTP status and Content-Type; a missing image returns an error rather than a substitute. Provide your own initials fallback in the UI.

Before going live#

Compatibility and changes#

Import the downloadable OpenAPI document into Postman, Insomnia or your client generator.

• Tolerate unknown fields and new status values.
• Pin client generation to a downloaded contract and diff before regenerating.
• Changes are announced on the changelog.