There is nothing to convert on the way in, which is the point of the format: Massive returns Unix epoch integers, and an epoch integer counts from one fixed instant and carries no zone at all. Conversion is only ever something you do on the way out, to display a local time. The difference that does bite is precision, and it changes between feeds.
Applies to
- Plans: all plans.
- Endpoints: every REST endpoint, every WebSocket channel and every flat-file dataset.
- Asset classes: all.
Precision by feed
Precision differs by feed, and getting the unit wrong is the mistake that actually happens, because it is silent:
| Feed | Field | Unit |
|---|---|---|
| REST trades and quotes | sip_timestamp, participant_timestamp, trf_timestamp | Nanoseconds |
| REST aggregates | t | Milliseconds |
| Flat files | the timestamp columns | Nanoseconds |
| WebSocket trades and quotes | t, pt | Milliseconds |
| WebSocket aggregates | s, e | Milliseconds |
| Futures | window_start, timestamp | Nanoseconds |
How to convert one
Use your language's own library rather than a website:
from datetime import datetime, timezone
ns = 1788566398110367271 # a REST trade
ms = 1788566398110 # the same event on the WebSocket
print(datetime.fromtimestamp(ns / 1_000_000_000, timezone.utc))
print(datetime.fromtimestamp(ms / 1_000, timezone.utc))
Keep the integer for storage, comparison and sorting, and convert only when you display it. Storing a formatted local string is how a trade ends up attributed to the wrong session.
Why UTC rather than Eastern time
UTC is used rather than market time because the markets Massive covers are not all in one time zone and not all of them close: crypto runs continuously, forex runs around the clock on weekdays, and futures sessions cross midnight. One fixed reference means a timestamp means the same thing on every feed and never repeats or skips an hour, which local time does twice a year.
If you need the trading session, derive it. The US equities regular session is 09:30 to 16:00 Eastern, which is 14:30 to 21:00 UTC in winter, when Eastern is UTC-5, and 13:30 to 20:00 UTC in summer, when it is UTC-4. Convert with a real time-zone database rather than a fixed offset, or the two weeks around each daylight saving change will be wrong.
If you see an error
A timestamp that decodes to 1970 means the value was divided as if it were seconds. One far in the future means milliseconds were treated as nanoseconds.
Events that look an hour out for part of the year are a fixed UTC offset applied to Eastern time. Use a time-zone database.
A trade that appears outside market hours may be genuine. Pre-market and after-hours trades are published like any other.
