Batch requests

Following a set of matches — a weekend’s fixtures, an accumulator, the games one club played last month — does not need one request each. Pass the ids together and take one response.

curl "https://api.footballsoccerapi.com/v1/matches?ids=mt_0CXSZRJ-mt_087EP2A-mt_2A0Z362" \
  -H "X-API-Key: YOUR_KEY"

Up to fifty ids in one request, separated by a dash. The response is the ordinary match list, so everything you already do with it still works.

Why it is worth doing

Fifty separate requests mean fifty round trips, fifty connections and fifty chances for one of them to fail. One request means one of each. The rate limit charge is the same either way — see limits — so this is about speed and reliability rather than about quota.

We learned this on our own side rather than in theory: switching one of our own collectors from per-match to batched turned a day of fetching into fifteen minutes, for exactly the same data.

Filters still apply

Every other parameter composes with ids, which is useful more often than it sounds. Ask for a set and keep only the ones that finished:

https://api.footballsoccerapi.com/v1/matches?ids=ID-ID-ID&status=finished

Or a set with a price on them:

https://api.footballsoccerapi.com/v1/matches?ids=ID-ID-ID&has_prices=true

A bad id is refused, not dropped

Send an id that does not decode and the whole request fails with 400 invalid_id, naming the one at fault.

That is deliberate, and it is the opposite of what several APIs do. Silently returning the forty-nine that worked gives you a response that looks complete and is not — you would find that in production, weeks later, as a gap in something you had already shipped. Better to fail on the request you can still fix.

Duplicates are fine and are collapsed. Sending the same id three times returns it once.

When not to use it

ids is for a set you already know. For walking a competition, a season or the whole archive, use the cursor instead — it is built for volume and does not ask you to know what you want before you ask for it.

The rule of thumb: if you are generating the id list from a previous response, you probably want the cursor. If it came from your own database, ids is right.

Limits

Fifty per request. Beyond that you would be paging, and the cursor does it better.

Each id costs one call against your rate limit. Asking for fifty matches in one request costs fifty, the same as asking for them one at a time. We would rather say that plainly than have you discover it from a 429.

What batching saves is round trips, not quota. Fifty requests means fifty connections, fifty lots of latency and fifty chances for one to fail halfway; one request means none of that. On a slow connection or from a serverless function that is the difference between a page that loads and one that times out.

Charging per record is deliberate. A limit that counted requests would measure how many connections you opened rather than how much data you took, and would let a free key pull fifty times its intended volume by batching. We would rather the limit meant something.

meta.count tells you how many came back, which will be fewer than you asked for if some of those matches fall outside your plan’s window.