Market definitions are useful before prices arrive
An odds integration needs to know which market a quoted selection belongs to. The pregame-markets operation supplies market identifiers and descriptive labels so your application can maintain that mapping explicitly instead of inferring it from a bookmaker name or a price. The account sample returned populated market definitions, establishing that this dictionary can be delivered. It does not establish a current quote for every listed market, any particular bookmaker or every football match. Keep the dictionary as reference data and price availability as a separate result of an enabled quote request. That distinction prevents a market selector from advertising content your account cannot actually retrieve.
Requesting and storing the pregame dictionary
Use an authenticated GET request to /api/v1/football/pregame-markets. There are no query parameters, and the operation requires Growth or Pro with service activation. Supply X-API-Key from your server and retain the returned data and meta envelope for inspection. The gateway uses a one-hour cache, which suits a reference-data refresh rather than per-visitor polling. Save the last valid mapping atomically and keep its retrieval time. A temporary error should not remove every market label from already stored quotes. Treat source attributes and record nesting as supplied rather than inventing a fixed normalized schema from a single example.
curl --fail-with-body 'https://footballapi.net/api/v1/football/pregame-markets' -H "X-API-Key: $FOOTBALLAPI_KEY"Join by market ID rather than display wording
Use the supplied market identifier as the stored key and its label as presentation. Labels can be revised, translated or abbreviated, while a familiar phrase may refer to different periods or handicaps. A market called match winner must not automatically be assumed to include extra time; inspect the definition and the associated quote context. Keep any local editorial label separate so a wording change does not break joins to saved odds history. When an unfamiliar market ID appears, retain it for later mapping rather than assigning the nearest familiar name. A visibly unknown category is less misleading than a confident label attached to the wrong wager.
Markets, selections and lines are different levels
A market groups possible outcomes, while an individual selection and any associated line define the quoted option. For a three-way result market, home, draw and away are separate selections; a total-goals market can also depend on a numeric threshold. Do not collapse several lines into one price just because their labels share the same words. Preserve market ID, selection identity, period, line and bookmaker with each saved quote when those fields are supplied. Your comparison table should place genuinely comparable selections together, and keep suspended or unavailable quotes distinct from a decimal zero that could be mistaken for a real offered price.
Using a definition in a bounded odds request
The market dictionary provides identifiers for the pregame odds operation's market filter. Actual odds delivery remains separately enabled and should only be requested through the current API contract. Combine an allowed market filter with a bounded match or competition scope rather than fetching an unrestricted price catalogue when the interface needs one game. Keep the market dictionary out of the match-click request path by preparing it in advance. If a selected market has no prices in a valid quote response, show its absence honestly; retrying the dictionary will not manufacture a bookmaker price or resolve an account that lacks the necessary quote service.
Pregame markets do not unlock live-odds services
Pregame definitions belong to the pre-match odds family. They are not proof that a separately configured in-play dictionary, live-odds transport or settlement service is active. Those services can use their own identifiers, connection details and access prerequisites. Even an inplay-mapping record is only a mapping, not a streaming token or a successful live subscription. Keep each product's activation status separate in your code and customer documentation. Some live services require registering the application's public server IP addresses through FootballAPI.net; retrieving this ordinary REST dictionary neither completes that registration nor authorizes a different transport to begin delivering data.
Preserve definitions alongside saved odds history
When your product records historical quotes, retain enough definition context to interpret them later. A renamed label should not make an older comparison unreadable, and a removed mapping should not cause historical rows to join to an unrelated market. You can keep a current dictionary plus dated label snapshots or a controlled mapping revision, depending on your reporting needs. Store the original market identifier on every quote regardless of the display strategy. Historical prices also need their own timestamps and status; the time you last refreshed the dictionary is not the time a bookmaker changed a price or the moment a market became suspended.
Use odds-derived tips without confusing their inputs
A market definition cannot generate a prediction by itself. If your application creates a match-winner tip from available 1X2 prices, use the actual saved selection prices and document your calculation separately from the dictionary. Odds-implied probabilities are not independently measured model confidence, and a market's presence in the definitions says nothing about the accuracy of a forecast. Avoid turning the source's market ordering into a recommendation or treating an absent price as the least likely outcome. Keep tips, market labels, player performance ratings and settlement results as distinct concepts, even when they appear together on the same football match page.
Checking a market mapping before comparison goes live
Test your parser with an empty dictionary, one definition, an unfamiliar optional attribute and a renamed label. Validate the relationship between a chosen definition and actual quote records from an enabled service before displaying several bookmakers side by side. Check period and line handling with particular care: a visually tidy table can still compare different products if these dimensions are dropped. Your error handling should retain previously valid labels, reject malformed responses and report credential-free request information. Where you cannot establish equivalence between two selections, keep them separate rather than combining their prices into a supposedly best-price result.
Reference-data access and a useful refresh policy
A successful dictionary request participates in normal account usage, but it does not represent a purchase of every associated odds product. Build a small background refresh job, alert on meaningful mapping changes and share the stored version across readers and workers. Record unresolved IDs encountered in real quotes so you can decide whether a controlled refresh is needed, rather than polling the dictionary continuously throughout every game. The API reference remains the authority for the published operation, request headers and errors. The separate bookmaker dictionary supplies the other side of your reference mapping, while the odds availability guide explains why definitions and current deliverable prices must remain distinct.
Questions developers ask
- Does the market dictionary return current odds?
- No. It returns definitions and identifiers; quote delivery is a separate enabled operation.
- Can I use these IDs for the pregame market filter?
- Use them with the pregame odds contract's market filter, retaining selection, period and line context.
- Does a listed market guarantee coverage for a game?
- No. Confirm actual prices for the requested fixture and bookmaker.
- Does this activate in-play odds or settlements?
- No. Those services have separate activation and connection requirements.
- How often should definitions refresh?
- The gateway cache is one hour. Save reference data in the background rather than fetching it for every visitor.
Guides and documentation
Check the plan before you write the integration.
Starter £29, Growth £99, Pro £249 per month. Starter only: 7 days free, once per account, card required. Then £29/month unless cancelled. No VAT currently charged. Existing EUR subscriptions are unchanged.