RaceHooks offers an F1 data API, and the feed catalog is how we split up a race weekend. We didn't start from a list of every signal we could publish. We started from the questions people ask during a session, gave each kind of question its own family, and put every feed in one consistent shape. Here are the nine families, the rules under them, and why almost none of it is specific to Formula 1.
The nine families
Every feed belongs to exactly one family. Each family answers one question:
| Family | The question it answers |
|---|---|
| Session core | Is there a session, and what state is it in? |
| Timing | Who is where, and how fast? |
| Strategy | Tyres, stints, pit stops: what is each car's race plan doing? |
| Race control | What has the referee said? |
| Race events | What just happened: overtakes, pit stops, retirements, fastest laps |
| Weather | What are the conditions, and where are they going? |
| Telemetry | The deep per-car record, after the session |
| Results | What did it all count for: classification and standings |
| Analytics | What happens next: the model layer |
We split them this way because the jobs are different. A timing screen shows you what is happening. A strategy call guesses what will happen. An overtake is an event, a thing that happened once, so it gets its own family with a shape for "do something when this occurs" instead of "render this table."
Weather sits apart from timing because conditions change on their own schedule and have their own forward question. Our rain forecast lives there, next to the observations it builds on. Analytics gets a family too. A probability is a different kind of statement from a measurement: it comes with model context, so it gets a schema that carries it.
The rules every payload follows
The family tells you where a feed lives. Five rules tell you what a payload looks like when it arrives, and they're why RaceHooks integrations stay small.
-
Payloads describe the race. Every field is about the session, the cars or the track. You won't find pipeline names or wire formats in the JSON. If it isn't a fact about racing, we leave it out.
-
One envelope everywhere. Every delivery is
{ feed, sessionId, utc, ... }, with the body indata(ordrivers, for per-driver arrays). Because of thefeedfield, one endpoint can take twenty subscriptions and route them with a single switch. -
We own the ids. A circuit is
{ id: "monaco", name: "Monaco" }. A session id names the event and the session, not an opaque number. Ids are stable, readable slugs you can log, join on and cache for years. -
A driver looks the same in every feed. You always get the full
DriverRef: number, driver id, constructor id, three-letter code, name and team. That holds in a timing row, a pit event and a win-probability estimate. No feed uses a short form, and you never join back to a lookup feed to find out who car 4 is. -
A feed ships finished or not at all. If a signal would go out as a raw blob with no shape and no consistent ids, we don't ship it. Some feeds are direct observations. Many are things we compute: the race-events stream is built from what's happening on track, the analytics feeds come from our models, and the weather forecast is ours.
The catalog keeps growing, but the rules stay fixed. Your parsing, routing and driver handling are written once, so each new feed you subscribe to takes a fraction of the work the first one did.
Why none of this says Formula 1
Look at the table again. Timing, stints, race control, weather, classification: every racing series has them. We built it that way on purpose.
A NASCAR stage end would be a race event. An IndyCar pit cycle would be strategy. A caution is race control, whatever the flag rules look like. If we add another series, its sessions go into the same families with the same envelope and the same ids, so code you write against RaceHooks today would mostly carry over. Formula 1 is live now. We're looking at other series, and they'd use this structure rather than a new one.
That's also why the catalog is organized by question and not by series. Who's leading, who's pitting, what did race control just do, is rain coming, who won: you ask those in every paddock.
Each family has its own reference page under /docs/feeds, and the shared envelope and ids are documented there once.
RaceHooks groups its feeds by the question they answer: nine families, one envelope, one set of ids. Code you write for the F1 feeds doesn't assume Formula 1.