PhotonOdds Odds API Response Shapes

Choose the narrowest response that fits

PhotonOdds exposes several REST views of odds data. Use the documented route that matches the question your application needs to answer:

Need	Route
Several events	GET /api/v1/odds
One event, grouped by bookmaker	GET /api/v1/events/{id}/odds
Best quoted odds for one event and market	GET /api/v1/events/{id}/odds/best
Recorded history for one event	GET /api/v1/events/{id}/odds/history
Changes since a cursor	GET /api/v1/odds/changes

The examples below mirror the public API contract, but event IDs, bookmaker names, prices, and timestamps are illustrative. Check the published API schema before relying on a field in production.

Bulk and event odds

GET /api/v1/odds returns a data array of events plus pagination metadata. Each event groups its available markets under the selected bookmakers. Use filters such as event_ids, sport, bookmakers, and market to keep a bulk response scoped to your application.

For one event, GET /api/v1/events/{id}/odds returns one data object with its event_id and bookmakers:

{
  "data": {
    "event_id": "evt_123",
    "bookmakers": [
      {
        "slug": "example-book",
        "name": "Example Book",
        "markets": []
      }
    ]
  }
}

The contract does not promise an account-specific maximum stake or a calculated staleness field in these responses. Store the documented observed_at value when it is present, then decide in your own application how old a record may be for the task at hand. Understanding Freshness and Latency gives that design decision useful context.

Best odds and history

For a single event and market, GET /api/v1/events/{id}/odds/best returns data.best_odds. Spread, total, and Asian-handicap requests also require a line parameter.

{
  "data": {
    "event_id": "evt_123",
    "market": "moneyline",
    "period": "full_time",
    "line": null,
    "best_odds": [
      {
        "outcome": "home",
        "odds": "2.10",
        "bookmaker": "example-book",
        "observed_at": "2026-07-31T14:32:00Z"
      }
    ]
  }
}

Use GET /api/v1/events/{id}/odds/history when you need the recorded sequence for one event. History is useful for analysis and auditing, but it is not a promise that a past or currently displayed price can still be accepted.

Build around changes, not assumptions

GET /api/v1/odds/changes is the REST change feed. Start with the filters your application needs, persist its cursor, and request later changes with that cursor. Each item identifies the event, bookmaker, market, outcome, odds, and observed time.

Treat the feed as a way to keep your local view current. A price change is an observation to review, not a recommendation to place a bet. Handle missing or delayed records defensively, and always validate requests, response errors, and rate-limit headers as described in Developer API Authentication and Rate Limits.

Configure this in PhotonOdds

Create and manage scoped credentials in the Developer portal, then test against the published schema before connecting a production job.

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.