Football in-play ID mapping API

Different services describe the same real football match from different angles. A fixture system schedules it, a scores system follows its state, and an in-play system, where one is used, deals with events during the match. Each system may assign its own identifier. Those identifiers are not interchangeable, and treating one as another produces failures at best and wrong matches at worst.

The in-play mapping feed relates the relevant fixture and in-play identifier systems. It takes no parameters and is cached for about five minutes. Responses use the standard envelope, with data holding the mapping as supplied and meta recording the feed, UTC fetch time, cache time and qualification. Identifiers on both sides are strings. Read a sample to see how pairs are represented before writing a mapping.

We want to be completely clear on this point. Access to the mapping feed does not enable any in-play service. It does not switch on streaming, WebSocket delivery or the ball tracker area of this site, and it does not imply that any of those are included in your plan. Those are separate products with their own activation and, where applicable, IP approval. A data subscription alone activates none of them.

The mapping is useful if you already hold, or are separately approved for, data keyed in the in-play system and need to join it to fixtures. If you do not, the mapping may have little practical use for you, and you should talk to support about your actual goal before relying on it.

Store the mapping in its own table with two clearly named columns, one per identifier system, plus the time you last saw each pair. Never merge the two identifiers into a single generic id column. Your fixtures table keeps its fixture identifier; any in-play data you hold keeps its in-play identifier; the mapping table joins them.

Refresh the mapping regularly on match days, because new pairs appear as matches approach. Keep pairs you have seen even if they drop out of a later response; a match that has finished may leave the mapping while your stored in-play data still needs joining.

Even a correct mapping deserves validation in your system. For a new pair, check that the fixture side refers to a match you hold and that its teams and date are consistent with whatever you hold on the in-play side. Flag pairs where one side maps to several identifiers on the other, which can be legitimate in edge cases such as replays but should be reviewed.

Validation is cheap compared with the cost of attaching events to the wrong match. A score centre showing a goal in a match that has not kicked off is the kind of error readers remember.

The mapping covers fixture and in-play identifiers. It is not a universal translation table. The match detail service, for example, uses a static_id together with a league identifier, taken from score or statistics responses, and neither an ordinary match identifier nor an in-play identifier will work there. Competition, team and player identifiers are separate again.

A good habit is to name every identifier column after its system and never reuse a column for another kind. When someone asks which ID to use, the column name answers.

With a five-minute cache, polling more often than that returns the same body. On match days, refreshing every ten or fifteen minutes in the hours before kick-off is usually enough to pick up new pairs. On quiet days, a few refreshes suffice. Store first-seen and last-seen times so you can tell when a pair appeared and whether it is still current.

Pairs tend to appear as a match approaches and may leave the response some time after it ends. That lifecycle is set by the source and is not something we certify, so build your storage to cope with any reasonable pattern. Insert pairs when first seen, update the last-seen time on each refresh, and never delete a pair because it disappeared. Historical joins between fixture data and any in-play data you hold depend on pairs that are no longer current.

If a fixture identifier later appears with a different in-play identifier, keep both pairs and flag the change for review. A rescheduled or replayed match can legitimately produce a new pair, and your editorial or operations team should decide which one applies.

Mapping bugs are subtle because they rarely cause errors; they cause wrong joins. Build tests from saved responses: a mapping sample, a fixture sample for the same day and, if you hold in-play data, a sample of that too. Assert that each mapped pair links matches with consistent teams and dates. Run the tests whenever you change mapping code, and add a new sample whenever you encounter an edge case in production.

These tests are cheap to maintain and catch the kind of error that would otherwise surface as a reader complaint about events attached to the wrong game.

If you are evaluating the mapping because you hope to use in-play data, start with support rather than with code. Describe the product you have in mind, the competitions and the kind of in-play information you expect to need. We will tell you plainly whether that is something we can offer, what separate activation or approval would apply and whether the mapping is actually the right starting point. That conversation costs nothing and can save weeks of building around an assumption.

Most mapping errors start with an ambiguous column called id. Name columns after their system, such as fixture_match_id and inplay_match_id, in your database, your code and your logs. When an engineer reads a query months later, the names make the join obvious and an accidental swap stands out immediately. The habit costs nothing and removes a whole class of silent errors.

The in-play mapping feed is a global service that is not included in Starter. It requires Growth at EUR 99 a month or Pro at EUR 249, plus activation of this mapping service for your account. That activation applies to the mapping only.

Polling every fifteen minutes through a match day is under a hundred successful requests. Above the daily inclusion of 25,000 on Growth or 250,000 on Pro, requests cost EUR 0.002 each on the monthly EUR invoice; failed and denied requests are not billed. No free trial is offered.