Odds API Use Cases: Three Practical Workflows

Choose a use case before choosing a route

PhotonOdds exposes event, odds, history, and signal routes under /api/v1. The useful starting question is what your application needs to show or record. A current comparison view, an update monitor, and a historical analysis job need different request patterns and different checks on the returned data.

Application	Start with	Keep in your own system
Event-level odds comparison	GET /events/{id}/odds or /events/{id}/odds/best	Event ID, market identity, bookmaker, price, observation time
Price-change monitor	GET /odds/changes	Processed update IDs, cursor, observation time
Recorded market review	GET /events/{id}/odds/history	Event and selection identifiers, recorded sequence, query time

The API response-shapes guide details how those routes group their data.

Start with one user question for each screen or job. “What prices are available for this event?” is a current comparison question. “What changed since my last successful check?” is a monitoring question. “How did this selection's recorded price develop?” is a history question. Those questions can share event IDs and market vocabulary without forcing every feature through one large response or one polling schedule.

Sketch the output before writing a client. For a comparison view, the output is a row per comparable selection and bookmaker. For a monitor, it is an update record and a reason for human review. For a history job, it is a time-ordered set of observations with a clear source. This makes it easier to request only the data the feature uses and to identify which missing field should block publication of a result.

Build an odds comparison view

Discover events with GET /events or GET /events/search?q=, then request one event's odds. Display the event, market, period, and line alongside each bookmaker quote so unlike selections are not compared as if they were identical. If the view needs the best quote for each outcome in one market, use /events/{id}/odds/best; spread, total, and Asian-handicap requests require a line.

The API key's bookmaker scope limits which quotes can appear. A missing bookmaker is not evidence that it has no market. Show the price's observed_at time and let readers check the current market independently. Freshness and latency explains why that timestamp matters.

Model a comparison row with an event ID, bookmaker slug, market type, period, optional line, outcome, odds, and observation time. The market identity fields are part of the comparison key. Two “home” outcomes should only sit together when they refer to the same event and market definition. A total at one line is not interchangeable with a total at another line; a full-time price is not the same as a first-half price. When the market identity differs, put the records in separate groups even if the prices look close.

Decide what the view does with unavailable or old data. An empty set may mean that the selected bookmakers do not currently return that market through the key's scope. A stale row should show its observation time or disappear according to your own policy, instead of retaining a former quote without context. Keep a clear “last checked” time for the request itself as well. That time helps diagnose a failed refresh, while observed_at describes when the source record was observed.

The best-odds route can simplify a narrow comparison, but it does not replace validation. It returns a bookmaker and observation time with each selected quote. If you display only the largest number and omit those fields, a reader cannot tell where it came from or how old it is. Treat the result as a data view for inspection, not as a claim that the price can be accepted at that moment.

Monitor changes for human review

Use GET /odds/changes when your application needs updates rather than repeated full snapshots. Filter by the sport, event, market, or selected bookmakers relevant to the monitor. Process each returned change, then save meta.cursor only after the batch has been stored successfully. On restart, resume from the saved cursor and handle repeated records idempotently.

Illustrative example. A research dashboard follows one event's full-time moneyline and records a change when one bookmaker's home quote moves from 2.10 to 2.05. It stores the event ID, bookmaker, market, period, outcome, update ID, observed time, and the time its own service received the update. Its review panel shows those fields and asks a person to check the current market. The prices are invented for illustration. The move alone does not establish why it happened or whether either quote remains available.

An update monitor needs a processing boundary. Save the change record first and advance the cursor only after every item in that response has been handled. Use the update ID to avoid a duplicate alert or duplicate database row if a page is replayed after a restart. Keep the cursor with its filters. Changing the watched market or bookmaker set starts a new query; reusing the old cursor with a different scope can produce an invalid-cursor response.

The monitor's rule is separate from its ingestion. It can record every received change while notifying a reviewer only when the application-specific rule matches and the record passes freshness and identity checks. That separation makes it possible to inspect false positives without altering the source data. When the notification channel fails, retain the processed observation and surface the delivery failure; do not silently mark it as reviewed.

For implementation details on polling frequency, reconnects, and plan-dependent WebSocket access, see polling, changes, and WebSockets. A change alert is a radar, not a bet instruction.

Review recorded market movement

For an event and selection you already know, GET /events/{id}/odds/history retrieves recorded odds history. Use it to study the order and timing of observations or audit what your application saw. Keep the bookmaker, market, period, line, and outcome together when analysing a sequence; mixing different selections can create a misleading movement chart.

History describes records, not prices currently available to a bettor. If a downstream report calculates movement or compares books, retain the source observation times and document the calculation. Building an odds-monitoring bot covers validation and recovery when an integration runs continuously.

A history workflow starts with a specific question, such as how the recorded price for one outcome changed before an event. Query by event, bookmaker, market, and outcome; then separate returned movements by period and line where relevant. Keep the full selection attached to every stored movement. If you later combine several bookmakers, describe whether the chart shows separate series, a chosen reference, or a calculated aggregate. Do not imply that a single curve is one bookmaker's sequence when it is assembled from several sources.

Store the raw returned odds string and observation time alongside any conversion you make for a chart. A plotted percentage, movement size, or interval is a derived value that your application owns. Retaining the input makes a report auditable and helps you correct a calculation without fetching a changed dataset later. Record when the job requested the history, too, since two reports built at different times may cover different recorded observations.

Do not turn the history endpoint into a source of currently actionable prices. Historical records can support a post-event review, quality check, or research workflow, but they cannot establish what a bookmaker would have accepted at a past timestamp. A careful report states what was observed and how the data was selected, then leaves causal claims and wagering decisions out of the chart.

Design the shared data and failure rules

These three use cases benefit from the same small set of integration rules. Store stable event and bookmaker identifiers, preserve market identity, retain source timestamps, and record your own request or receipt time. Validate the data shape before writing it. A transport success with an empty array, an unexpected market, or a missing timestamp may be a valid API response but an invalid input for a particular feature.

Plan for a key's bookmaker scope and hourly request capacity. Choose filters that match the feature, reuse stored observations where appropriate, and inspect capacity headers rather than scheduling around a guessed quota. On 429, honor Retry-After and stop concurrent workers using the same key from immediately retrying. A paid route or WebSocket transport may require a plan entitlement; the REST change feed is the appropriate baseline when polling meets the application's needs.

Give each job a visible failure state. A comparison view should be able to say it has no current records for that selection. A monitor should expose when its cursor last advanced and whether notification delivery failed. A history report should identify the selection and time range actually returned. These details keep a reader from mistaking silence or an old record for a complete view of the market.

Match the integration to the available API plan

Authenticate with a server-side X-API-Key, inspect the key's capacity headers, and handle 429 with Retry-After. If you have not made a request yet, begin with the PhotonOdds API quickstart. Some routes and transports depend on plan entitlement and bookmaker scope, so check the current contract before committing a production workflow. The Odds API overview explains the available product options and links to the reference documentation.

Choose one of the three jobs, write down its output fields and empty state, and validate one real response from the key you intend to use. Then add the route-specific cursor or history handling that job requires. This keeps a comparison screen from accidentally behaving like a change consumer, and gives a reviewer enough context to interpret every displayed observation. PhotonOdds supplies market data and analytical signals; the application remains responsible for presentation, persistence, and human review.

18+ only. Betting carries risk. Odds data and signals do not guarantee an outcome or a return.

18+ only. Betting carries risk. PhotonOdds provides analytical and educational tools, not a promise of profit or a recommendation to place a bet. If gambling is causing harm, see Responsible Gambling.