Head-to-head data in a football API

A head-to-head request needs both team identifiers. Order may matter for how the response labels home and away, so read the schema in the playground and decide on a consistent convention in your code. Most sites request the pairing with the upcoming fixture's home team first, so the summary reads naturally from the home side's perspective.

Cache the result per pairing. Head-to-head history changes only when the two teams meet again, which may be once or twice a season. A single refresh after each meeting keeps it current, and every preview page for that pairing can reuse the cached copy.

Store the pairing under a key that sorts the two identifiers, so a request for A against B and B against A resolve to the same cached history, then apply your home and away labelling when rendering.

Expect a list of previous meetings with dates, competitions, venues and scores, plus summary counts of wins for each side, draws and goals. Some responses separate meetings by venue so you can show home and away records. The exact sections can vary, which is why we document them through the schema rather than promising a fixed shape.

Older meetings may lack details such as venue or competition stage. Show what exists and avoid filling gaps from memory or other sources unless you can cite them.

Head-to-head records are interesting and often misleading. A run of results from a decade ago says little about two squads that have since changed completely. Present the history clearly as history: list recent meetings first, show dates prominently and let readers judge relevance for themselves.

Avoid headlines that turn the record into a prediction. We do not publish betting tips or forecasts of results, and a sentence such as history favours the home side can easily be read as one. Describe what happened, not what will happen.

A compact visual, such as a row of small result markers for the last five meetings with dates beneath, often communicates more than a paragraph and is less likely to be over-interpreted.

Head-to-head data works best alongside current context. Show each team's position from the standings feed and their recent form so readers can weigh old meetings against present reality. Link each past meeting to its match page if you hold one, and link both team names to their pages by identifier.

If either team has changed its name or identity over the years, the identifier keeps the history joined. Display the name as it appears in the current team record, and consider a small note if older meetings were played under a former name.

Test a pairing with a long history, a pairing that has met only once, and a pairing that has never met. The last case should produce a clear empty state rather than an error. Also test teams from different competitions that met in a cup, since those meetings are easy to overlook if you filter by league.

Record the raw responses from these tests and keep them as fixtures for your own automated tests. If the response shape changes later, your tests will tell you before your readers do.

Because head-to-head data changes rarely, it is cheap to maintain. Build the cache lazily: request a pairing the first time a preview page needs it, then refresh only after the two teams meet. For a league of twenty teams, that is at most a few hundred pairings in a season, most of which need just one or two requests.

Use the planner to forecast calls across all feeds. Compare daily successful requests with Starter's 5,000, Growth's 25,000 or Pro's 250,000 inclusion. A monthly total is a projection, not a monthly allowance. Spread requests below the shared 100-request/second safety ceiling, and cache each team-pair result rather than fetching it once per page view.

The best previews combine data and judgement without blurring them. Use the head-to-head summary as a factual box, and keep any opinion clearly separated in your own words. Readers trust sites that show their sources, so a line noting where the meeting history comes from and when it was last refreshed is a small but meaningful touch.

Keep the box short on mobile. Five recent meetings and a three-number summary are usually enough; link to a full history page for readers who want more.

If you show recent meetings as coloured markers, give each a text label such as win, draw or loss from the home side's perspective, plus the score and date. Colour alone fails readers with colour vision deficiency and screen reader users. A small table beneath the markers provides the same information in an accessible form.