# 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](https://sockodds.com/examples/sockodds-store.py) 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](https://sockodds.com/docs/quickstart/) shows how to get a key and discover leagues and event IDs.

```bash
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.

```bash
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](https://sockodds.com/docs/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](https://sockodds.com/account/#api-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.

```bash
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](https://sockodds.com/docs/history/#how-far-back-it-goes) 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.

```bash
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](https://sockodds.com/docs/history/#whole-days-as-files)

```sql
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.

```bash
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.

```sql
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](https://sockodds.com/docs/results/). When using a coding assistant, give it [the Markdown version of this guide](https://sockodds.com/docs/collect-and-store-odds.md) and the [AI starter pack](https://sockodds.com/ai-context.md) along with your plan, leagues and storage needs.
