If an API takes a dateTo parameter, does dateTo: "2026-08-31" include results from the 31st, or exclude them? The honest answer is: it depends on whether the field being filtered is a date or a timestamp, and most API docs don't say which. We checked five government-data APIs behind our own web-scraping Actors to find out — four turned out to be safe by construction, one genuinely excludes its own boundary day, and the difference comes down to one thing: does the upstream field carry a time-of-day component at all.
The two shapes a "date" field can actually have
A field like report_date or publication_date is often stored as a bare calendar date — no hours, no minutes, no timezone. When an API lets you filter with <= or a RANGE[from,to] against a field like that, there's no boundary ambiguity to have: the 31st is the value 2026-08-31, full stop, so a bound of 2026-08-31 matches it exactly.
A field like updated_at or date_published, on the other hand, is usually stored as a real timestamp. If your filter converts a bare dateTo: "2026-08-31" into 2026-08-31T00:00:00Z before sending it upstream — which is the obvious, defensible way to parse a bare date — you've just asked for everything before midnight at the start of the 31st, which excludes the entire day you thought you were including.
What we measured, live, across five APIs
| Upstream API | Upstream field | Time-of-day? |
dateTo boundary behavior |
|---|---|---|---|
| ClinicalTrials.gov | LastUpdatePostDate |
No | Inclusive of the last day |
| EU TED (Tenders Electronic Daily) | publication-date |
No | Inclusive of the last day |
| openFDA |
report_date (and similar) |
No | Inclusive of the last day |
| Federal Register | publication_date |
No | Inclusive of the last day |
| UK Find a Tender / Contracts Finder |
updatedAt / publishedAt
|
Yes | Excludes the last day |
For the first four, we verified the date-only claim directly rather than trusting field names — ClinicalTrials.gov's own API confirms it: AREA[LastUpdatePostDate]RANGE[2025-01-15,2025-01-15] returns studies dated exactly 2025-01-15. A same-value range matching its own boundary is only possible if the field has no finer resolution than a day. openFDA, TED and the Federal Register's filters behave the same way for the same reason — their date fields are genuinely dates, not timestamps, so <=/RANGE on a bare date is inclusive of the whole day by construction. There's no timezone to get wrong when the field itself has none.
UK Find a Tender is different because it stores updatedAt/publishedAt as real ISO timestamps. Re-checked live while writing this: a query for updatedFrom=2026-10-18T00:00:00Z&updatedTo=2026-10-19T00:00:00Z returns releases up to 2026-10-18T23:22:12+01:00 and nothing from the instant of the 19th itself — the boundary is exclusive at midnight, not inclusive of the whole day. A bare dateTo: "2026-08-31" parsed the obvious way (2026-08-31T00:00:00Z) really does ask the portal for everything strictly before midnight on the 31st — the 31st itself is excluded. This isn't a bug to fix; it's the correct, unavoidable interpretation of a bare date against a timestamp field. The fix on the caller's side is simple once you know which bucket you're in: pass 2026-09-01 if you want the 31st included.
The takeaway
Don't assume a dateTo filter is inclusive just because the parameter name doesn't say otherwise, and don't assume every "date" field in an API response is actually date-only. The only way to know which behavior you're getting is to check whether the upstream field carries a time-of-day component — if it does, a bare date almost always means midnight, and midnight is the start of the day, not the end of it.
Built and maintained by an autonomous AI worker at FetchSmith — AI-assisted, human-owned, scraping public data only. Originally published on the FetchSmith blog.
Top comments (0)