Everybody starts the same way. A rule like "do not open a position within fifteen minutes of a high impact release" needs to know when the releases are, so somebody writes a scraper against a public calendar page. It works for a month, the page markup changes, the scraper returns an empty list, and the news filter silently stops filtering. A proper feed exists precisely so that failure mode is visible instead of silent.
What is in a row
Feeds differ in wrapping, not much in substance. The core columns are the event name, the country or currency it applies to, a scheduled timestamp, an importance rating, and the three numbers: previous, forecast, actual. Good feeds add several things that turn out to matter more than the headline value.
- A stable event identifier. Without it you cannot join this month's release to last month's, and you will be matching on strings that change wording.
- The reference period. A payrolls number published in one month describes the previous month. Any analysis that ignores this misaligns the whole series.
- A revised previous. Statistical agencies revise. A release where the headline beats expectations but the prior month is revised down is a different event from one where it is not.
- Publication timestamp. Not when the release was scheduled, but when the value actually appeared in the feed. This is the field that makes honest testing possible.
- Units and scale. Percent, thousands, index points, month on month against year on year. Mixing them produces nonsense comparisons.
Time is the part that breaks
Store everything in UTC and convert at the edge. This sounds obvious and is violated constantly, usually because a provider returns local times for the releasing country and the consumer assumes they are already normalised. The damage arrives on daylight saving weekends, when the US and Europe change clocks on different dates and a fixed offset in your code is wrong for a couple of weeks each spring and autumn.
Two more time traps. Scheduled times move: central bank statements and some releases shift, and a feed that only updates once a day will hold a stale time. And a release can arrive slightly early or late relative to schedule, so any rule that blocks trading around an event should key off a window around the scheduled time and then confirm against the publication timestamp rather than assuming they coincide. The behaviour of price around those moments is a separate subject, covered in news trading and the spike.
Polling, push and rate limits
Split the two jobs. The forward schedule is slow moving, so fetch it a few times a day, cache it, and diff against what you already had so that a changed time raises a notification instead of quietly overwriting. The actual value is time critical, and if anything automated depends on it, take a push channel: a webhook, a websocket or whatever the provider offers. Polling once a second to catch a release is a good way to burn a rate limit and still be second.
Whatever the delivery, treat it as unreliable. Deduplicate on the event identifier plus the release timestamp, because retried webhooks arrive twice. Verify signatures if the provider signs them. And never let calendar delivery drive an irreversible action without a sanity check, a lesson that applies to any inbound automation, as we set out in webhook automation from TradingView alerts.
Impact ratings are editorial. Two providers will label the same release differently, and a rating can change between the time you cached the row and the time the event fires. Build your own list of events that matter to your instruments.
Matching across providers
Nobody agrees on event names. One feed says "Non-Farm Employment Change", another says "Nonfarm Payrolls", a third abbreviates. There is no universal identifier across vendors, so if you use two sources for redundancy you need a mapping table: country plus your own canonical event code, populated by hand once and maintained when a new indicator appears. Fuzzy string matching alone will eventually pair the wrong two rows, and the failure is silent because both rows look plausible.
The same problem shows up when reconciling against a public calendar people can see. If your client-facing widget disagrees with what a trader reads on the ForexFactory calendar, support tickets follow, and the answer is nearly always a naming mismatch or a timezone conversion rather than bad data. Our overview of calendar tools and feeds compares what the common sources publish.
Store the history, not just the current state
The single most useful design decision is to keep every version of every row with the time you received it, and never update in place. That gives you an as-of view: what did the system know at 13:29 on the day of the release. Without it, a backtest that filters on economic data is reading revised figures and consensus forecasts that were updated after the fact, which is the calendar version of looking at tomorrow's newspaper.
An append-only table also makes operational questions answerable. Why did the news filter not fire, why did this event move by an hour, when did the forecast change. Both a prop firm enforcing news trading restrictions and a broker showing a calendar inside its trading terminal need that audit trail, because the alternative is arguing with a client about what the schedule said three weeks ago with no evidence either way.
One last position: do not put business rules in the calendar layer. The feed's job is to say what happened and when. Whether that means a trader is blocked, a position is closed or an alert is sent belongs in the rules engine, where it can be changed without touching the data pipeline.
"Every calendar bug I have debugged was a timezone or a name mismatch. Neither of them looks like a bug until somebody's news filter does nothing on payrolls day."
— Alex Onta, Executive Director, SINGUARD
Key Takeaways
- The valuable fields are the unglamorous ones: stable event id, reference period, revised previous, publication time.
- Normalise to UTC at ingestion, and never hardcode an offset that daylight saving will break twice a year.
- Poll the schedule and take a push channel for actual values, with deduplication on id plus timestamp.
- Keep an append-only history so you can reconstruct what the system knew at any moment.
Frequently Asked Questions
What fields does an economic calendar API usually return?
Typically an event name, the country or currency it belongs to, a scheduled timestamp, an importance or impact rating, and the previous, forecast and actual values with units. Better feeds add a revised previous value, a release period such as the month the data refers to, and a stable identifier for the event series so you can join releases of the same indicator over time.
Should I poll a calendar API or use push delivery?
Poll the schedule, push the results. The forward calendar changes slowly, so fetching it a few times a day and caching it is enough. The actual value appears in a specific second and matters immediately, so a webhook or streaming channel is worth it if anything automated depends on the number. Polling every second to catch a release wastes your rate limit and still arrives late.
Are impact or importance ratings standardised?
No. High, medium and low are editorial judgements made by each provider, and two feeds will disagree about the same release. If a rule in your system depends on impact, define your own list of events that matter to the instruments you trade and match on the event identifier, rather than trusting a colour that can change without notice.