Build with AI · Soccer Data docs

Give your AI coding tool the full Soccer Data reference and a good starting prompt, and let it write the integration.

AI coding tools such as Claude Code, Codex, Cursor and Lovable can build a working Soccer Data integration in minutes, as long as they know the real endpoints. Without a reference they guess, and guessed parameter names fail. This page shows how to give them what they need.

Why this works

We publish the whole documentation, including every endpoint with its parameters, response fields and an example, as one plain-text file:

https://soccer-data.co/llms.txt

An assistant that reads this file uses the exact paths and parameter names. And when it does slip, the API helps it recover: an unknown parameter returns 400 UNKNOWN_PARAMETER with the closest valid name and the full list of accepted parameters in the message, which is enough for most tools to fix the call themselves.

Set up in three steps

1. Create a key and store it safely

Create an account and copy the key you're given at sign-up (you can create more on the API keys page). Put it in a .env file at the root of your project, and make sure git ignores that file:

echo 'SOCCER_DATA_KEY=YOUR_API_KEY' >> .env
echo '.env' >> .gitignore

Warning Never paste your key into the chat with your assistant, and never let it end up in browser code. Keep it in .env or your tool's secrets settings, and have only your server read it.

2. Give the assistant the reference

Either paste the URL https://soccer-data.co/llms.txt into your prompt, or save a copy inside your project so the assistant can read it offline:

mkdir -p docs
curl -o docs/soccer-data-llms.txt https://soccer-data.co/llms.txt

3. Start with a clear prompt

The Build with AI page in your dashboard has a starter prompt with your base URL and the reference link already filled in, plus ideas to build. Copy it, describe what you want, and send it. If you'd rather write your own, these are the rules worth giving the assistant:

I'm building with the Soccer Data football API.
Read the reference first: https://soccer-data.co/llms.txt

Rules:
- Base URL: https://api.soccer-data.co/v1
- Send the key in the X-Api-Key header. Read it from the SOCCER_DATA_KEY
  environment variable on the server. Never put it in browser code, in
  NEXT_PUBLIC_ or VITE_ variables, or in git.
- The frontend calls my own server route; only that route calls Soccer Data.
- Ids are strings like team_... or match_.... Look them up with the search
  parameter on /competitions, /teams and /players. Never invent them.
- Dates use date_from and date_to (YYYY-MM-DD). There is no date parameter.
- /matches lists the latest kickoff first. For upcoming matches use
  status=scheduled and sort=utc_date.
- Lists are paged with page and per_page (up to 100). Stop at meta.total_pages.
- Errors look like {"error": {"code", "message", "status_code"}}. Branch on code.
- 400 UNKNOWN_PARAMETER means a wrong parameter name: use the one the message suggests.
- On 429 or 503, wait for the seconds in the Retry-After header, then retry.
- Cache responses. There are no webhooks, so poll live data only while a match is live.
- Check flags such as has_player_stats, xg_available, shotmap_available and
  odds_available before calling endpoints that depend on them.
- History depth differs by competition: check /coverage/leagues.

First test: fetch Arsenal's next match (team_id team_f0ibhxdw7hs5).

What I want to build:
[describe it here]

Tool by tool

Most tools read a notes file from your project on every session. Put the rules above in that file so you don't have to repeat them.

Tool	Setup
Claude Code	Save the reference and `.env` in the project first, put the rules in `CLAUDE.md` at the root, then run `claude`. You can also block it from reading `.env` by adding deny rules for `./.env` and `./.env.*` in `.claude/settings.json`.
Codex	Download the reference and create `.env` before you start, because the default sandbox has no network access. Put the rules in `AGENTS.md`. To let it make test calls, approve the network request when it asks, or set `network_access = true` under `[sandbox_workspace_write]` in `~/.codex/config.toml`.
Cursor	Save the reference, create `.env` and put the rules in `AGENTS.md`. Mention `@docs/soccer-data-llms.txt` in chat to point at the reference. Don't add the reference file to `.gitignore`: Cursor leaves ignored files out of what it can see.
Lovable	Paste the rules into Project settings, under Knowledge. Store the key with the Add secret form, not in chat, and call the API from a server function or Edge Function.
v0, Replit and other builders	Use the tool's secrets or environment settings for the key. Avoid `NEXT_PUBLIC_` and `VITE_` variables, since those end up in browser code.

Ideas to try

A live scores widget for today's Premier League matches that only refreshes while games are in play.
A league table page built from the current season's standings.
A fantasy points calculator that scores players from a finished match's player stats.
An xG shot map for a match, shown only when shotmap_available is true.
An odds comparison for the weekend's fixtures that skips matches without prices.

Tips

Paste errors back. If a call fails, give the assistant the full error JSON. The message usually says exactly what to change.
Use real ids. Get them from a search request, and include them in your prompt.
Watch your limits. A retry loop or a tight polling loop can use up a day's requests quickly. Ask the assistant to cache responses and to respect Retry-After. Your usage page shows what's been spent.
Check coverage first. Before building something that needs xG, player stats or odds, make sure the competition has them. See Coverage.

Next steps

Quickstart: the same first requests, by hand.
Find any ID: every way to look up ids.
Errors: what each error code means.
API reference: every endpoint.