Skip to main content

​
Overview

All data in our system is stored in UTC, but our processing runs on an EST (Eastern Standard Time) schedule. Understanding how date ranges work is critical to querying the correct data for your use case.
Incorrect timezone handling is the most common cause of missing or unexpected data in API responses. Please read this guide carefully.

​
System Behavior

​
Data Processing Schedule

Our system processes data according to the EST timezone:
  • The “day” of January 1st EST starts at 00:00 EST (05:00 UTC)
  • The “day” of January 1st EST ends at 23:59 EST (04:59 UTC next day)
All data is stored with UTC timestamps in our database.

​
Date Format Support

The API accepts dates in multiple formats:
  1. Date only (recommended for daily queries): 2025-01-01
  2. Date and time without timezone: 2025-01-01T00:00:00
  3. Date and time with UTC timezone: 2025-01-01T05:00:00Z

​
How Dates Are Interpreted

​
Without Timezone Specification

When you provide a date without a timezone (no Z suffix), the API interprets it as EST: 
{
  "start_date": "2025-01-01",
  "end_date": "2025-01-31"
}
What happens:
  • 2025-01-01 → Interpreted as 2025-01-01T00:00:00 EST → Converted to 2025-01-01T05:00:00Z UTC
  • 2025-01-31 → Interpreted as 2025-01-31T00:00:00 EST → Converted to 2025-01-31T05:00:00Z UTC
This matches how our system defines “days” and is the recommended approach for most use cases.

​
With UTC Timezone (Z suffix)

When you provide a date with the Z suffix, the API interprets it as literal UTC: 
{
  "start_date": "2025-01-01T00:00:00Z",
  "end_date": "2025-02-01T00:00:00Z"
}
What happens:
  • 2025-01-01T00:00:00Z → Used as-is in UTC
  • 2025-02-01T00:00:00Z → Used as-is in UTC
Using UTC timestamps (with Z) requires you to manually convert from EST to UTC. This approach exists for backwards compatibility but is not recommended for new integrations.

​
Examples

​
Correct: Query January 2025 data (EST days)

{
  "start_date": "2025-01-01",
  "end_date": "2025-02-01"
}
This returns all data from:
  • Start: January 1st, 00:00 EST (05:00 UTC on Jan 1st)
  • End: February 1st, 00:00 EST (05:00 UTC on Feb 1st)
The range is inclusive (<=), but since data typically doesn’t have timestamps exactly at 00:00, this effectively captures all of January.

​
Incorrect: Query January 2025 with UTC midnight

{
  "start_date": "2025-01-01T00:00:00Z",
  "end_date": "2025-02-01T00:00:00Z"
}
This returns data from:
  • Start: December 31st, 19:00 EST (00:00 UTC on Jan 1st)
  • End: January 31st, 19:00 EST (00:00 UTC on Feb 1st)
Problem: You’re missing 5 hours at the start and including 5 hours you don’t want at the end.

​
Correct: Query January 2025 with UTC (manual conversion)

If you must use UTC timestamps, you need to account for the EST offset: 
{
  "start_date": "2025-01-01T05:00:00Z",
  "end_date": "2025-02-01T05:00:00Z"
}
This correctly captures all of January (EST days), but requires manual timezone math.

​
Time Ranges

​
Date-only format defaults to midnight

When using date-only format, times default to 00:00:00: 
{
  "start_date": "2025-01-01"  // Equivalent to 2025-01-01T00:00:00 EST
}

​
Specifying exact times

You can specify exact times for more granular queries: 
{
  "start_date": "2025-01-01T08:00:00",  // 8 AM EST
  "end_date": "2025-01-01T17:00:00"     // 5 PM EST
}
This queries data from 8 AM to 5 PM EST on January 1st.

​
Date range behavior

Date ranges are inclusive on both ends (start <= x <= end): 
{
  "start_date": "2025-01-01",
  "end_date": "2025-01-02"
}
This includes:
  • All of January 1st (from 00:00 EST onwards)
  • January 2nd at exactly 00:00 EST
  • Since data is timestamped throughout the day, there typically isn’t data exactly at 00:00, so in practice this captures all of January 1st
To query a single day, set end_date to the next day at 00:00.

​
Best Practices

Recommended: Use date-only format without timezone for daily queries
{
  "start_date": "2025-01-01",
  "end_date": "2025-02-01"
}
Recommended: Use datetime without timezone for intraday queries
{
  "start_date": "2025-01-15T09:00:00",
  "end_date": "2025-01-15T17:00:00"
}
Avoid: Using Z suffix unless you understand UTC offset implications
{
  "start_date": "2025-01-01T00:00:00Z",  // Probably not what you want
  "end_date": "2025-02-01T00:00:00Z"
}

​
Daylight Saving Time

EST observes Daylight Saving Time (DST):
  • Standard Time (EST): UTC-5 (typically November - March)
  • Daylight Time (EDT): UTC-4 (typically March - November)
The API automatically handles DST transitions. When you specify dates without timezone, the conversion to UTC accounts for whether DST was active on that date. Example during DST: 
{
  "start_date": "2025-07-01"  // Interpreted as EDT (UTC-4)
}
→ Converted to 2025-07-01T04:00:00Z UTC (not 05:00 because of DST)

​
Troubleshooting

​
Missing data at day boundaries

Problem: You’re querying January 1st but missing the first or last few hours. Solution: Make sure you’re not using the Z suffix. Use "start_date": "2025-01-01" instead of "start_date": "2025-01-01T00:00:00Z".

​
Data from previous/next day appearing

Problem: Your daily query includes data from adjacent days. Solution: You’re likely using Z suffix with midnight UTC, which doesn’t align with EST days. Remove the timezone suffix.

​
Unexpected DST behavior

Problem: Your queries have a 1-hour difference during DST transitions. Solution: Let the API handle DST automatically by using dates without timezone. If you must use UTC, remember the offset changes between EST (-5) and EDT (-4).

​
Future Changes

In a future version of the API, we plan to support full ISO 8601 timezone offsets (e.g., -05:00, +09:00) to enable multi-timezone queries. Dates without timezone specification will be deprecated at that time.
For now, the recommended approach is to use dates without timezone and let the API handle the EST conversion for you.
⌘I