Collect and store odds
Save current prices as they arrive, import recorded changes and join both to results.
Set up the example
Download the Python script or run the command below. It uses Python 3.10 or later and creates sockodds.sqlite in your working directory. Set SOCKODDS_API_KEY privately in the environment where you run it. The quickstart shows how to get a key and discover leagues and event IDs.
curl -fsS https://sockodds.com/examples/sockodds-store.py -o sockodds-store.py
python3 sockodds-store.py --help
Record current prices on Rookie
Run the later job every five minutes and the near job every two minutes. Use your scheduler of choice and keep one job per window running at a time. Both commands page through the same /v1/odds list endpoint across all leagues available to your key.
python3 sockodds-store.py record later
python3 sockodds-store.py record near
| Job | Time until scheduled start | Cadence |
|---|---|---|
later | 3 to 24 hours | Every 5 minutes |
near | 0 to 3 hours | Every 2 minutes |
Add --league nfl to start with one league. Add --alternates if you need alternate lines as well. Those add data to each page. The script fixes the time window at the start of each run, then follows the same filters through every page. Each successful page uses one Rookie request, including an empty page. If a run reports Monthly allowance reached, pause scheduled runs until the next UTC month or a plan change. On Rate limit reached, the script waits for Retry-After and retries up to twice. Plans and limits
The database saves each observation with its original observed_at timestamp. When a poll sees the same observation again, the insert leaves the existing row in place. If a bookmaker quote is absent, the script adds no row for it. Expect gaps whenever the API has no quote, the poller is offline, or a price changes between polls. Rookie collects prices from the time you start polling. Source updates have their own cadence.
Backfill recorded price changes on Pro
For one event, copy its ev_ ID from the playground or GET /v1/events. Replace the values below with that ID and the UTC observation interval you want. The start is included and the end is excluded.
python3 sockodds-store.py backfill "$EVENT_ID" "$FROM_UTC" "$TO_UTC"
The script splits the interval into windows of up to 24 hours and saves each page before requesting the next. It marks a window complete only after all pages are stored. Rerun with the same arguments after an interruption. Completed windows are skipped and a partially imported window starts again with duplicate rows ignored. Add --refresh to reread completed windows and capture late rows. Start and end inputs accept ISO timestamps with a timezone, such as 2026-11-01T00:00:00Z.
The source column keeps polled snapshots and Pro history changes distinct. A history row with kind = 'withdrawn' has no decimal price and marks an explicit withdrawal. An empty poll or a missing stretch of history adds no withdrawal. Check recording dates and known gaps before choosing a backfill range.
Download league history in bulk
Use archive for a league and inclusive range of UTC dates. It saves the daily Parquet files under sockodds-history/<league>/. The example below requests the first week of November for the NFL.
python3 sockodds-store.py archive nfl 2026-11-01 2026-11-07
The downloader lists published files, saves each one only after its SHA-256 matches the listing, and skips files you already have with the same checksum. It downloads one file at a time. For recent days that are still outside the archive, use backfill for the events you need. The Parquet files are ready to query directly in a tool such as DuckDB. History file availability and columns
SELECT * FROM read_parquet('sockodds-history/nfl/*.parquet') LIMIT 10;
Join prices to results
Fetch the graded outcomes for an event into the same SQLite database. Run the command again as more markets settle or results are corrected.
python3 sockodds-store.py results "$EVENT_ID"
Query the observations with their latest stored verdict. Join on the event and outcome IDs. A blank verdict means you have no stored grade for that outcome yet. For backtests, choose a single odds source per analysis and limit prices to observations available at your decision time. Include withdrawals when reconstructing whether a recorded selection was available at that time.
SELECT o.observed_at, o.bookmaker, o.outcome_id, o.decimal_odds, r.verdict
FROM odds AS o
LEFT JOIN results AS r
ON r.event_id = o.event_id AND r.outcome_id = o.outcome_id
WHERE o.source = 'history' AND o.available = 1
ORDER BY o.observed_at;
For the fields and grade meanings, see Results. When using a coding assistant, give it the Markdown version of this guide and the AI starter pack along with your plan, leagues and storage needs.