AllTick
-
Market Datareal-time market dataFinancial DataTrading Technology

Why Does the Timestamp Received from a Real-Time Market Data API Not Match Local Time?

Real-time market timestamps may differ from local time due to timezone conversion, timestamp units, server clocks, or market hours. Learn how to correctly handle seconds, milliseconds, UTC, and receive times.

AllTick5 min read

After integrating a real-time market data API, developers may encounter a seemingly strange problem: prices update normally, but the market timestamps displayed on the screen differ from the computer's local time by several hours. Sometimes the difference is eight hours, sometimes four, and in other cases, the converted date even jumps back to 1970.

When this happens, the first assumption is often that the API has returned an incorrect time or that the market data is delayed. In reality, the problem may be related to timestamp units, time zone conversion, the server's system clock, or even a misunderstanding of what the market update time represents.

To determine accurately whether real-time market data is delayed, it is first necessary to understand what time the API timestamp actually represents.

First, Distinguish Market Time from Local Receive Time

The timestamp returned by a market data API does not necessarily represent the time when the data arrives at the developer's server.

In a real-time market data system, at least three different types of time need to be distinguished:

  • Market time: The time associated with a market data record, such as a particular Tick or order book update.
  • Receive time: The time when the application actually receives the data, recorded by its own server or client.
  • Display time: The time displayed by the frontend after conversion to the user's local time zone.

These three timestamps do not necessarily match.

For example, a market data record may correspond to 10:00:00, while the server receives it at 10:00:00.150. The difference between the two timestamps is 150 milliseconds. However, this does not necessarily mean that the timestamp conversion is incorrect.

Unix timestamps also represent absolute points in time. They do not directly contain local time zone information such as Beijing Time or New York Time. If a program converts a timestamp into a local date and time without explicitly specifying a time zone, the displayed result may differ across servers and execution environments.

Therefore, it is recommended to store the original market timestamps in UTC on the backend and convert them according to the user's time zone on the frontend. This helps prevent inconsistencies across different time zones and makes it easier to calculate market data update intervals.

Mixing Milliseconds and Seconds Is Another Common Cause

If the time difference is not a fixed number of hours, but instead produces an unexpected date such as 1970 or a date far in the future, the timestamp unit should be checked first.

There are two common types of Unix timestamps:

  • Seconds-based timestamps: Usually 10 digits long.
  • Milliseconds-based timestamps: Usually 13 digits long.

For example, suppose an API returns the timestamp 1793260800000. If the program interprets it as seconds instead of milliseconds, the resulting date will be completely incorrect.

Another detail that is easy to overlook is that time fields in different APIs may use the same name, such as timestamp or tick_time, without necessarily sharing the same unit.

Take AllTick as an example. The tick_time field in its HTTP order book data uses a millisecond timestamp, while the timestamp field in its K-line data uses a second-based timestamp. If both types of data are passed through the same conversion function without distinguishing their units, timestamp errors may occur.

Timestamp parsing logic can be centralized, but the conversion unit must be selected according to the definition of each specific field.

The following example demonstrates how to handle these timestamps in Python:

text
from datetime import datetime, timezone
from zoneinfo import ZoneInfo

# Use Beijing Time as the display example
DISPLAY_TZ = ZoneInfo("Asia/Shanghai")

def tick_time_to_utc(value):
    # Millisecond timestamp
    return datetime.fromtimestamp(
        int(value) / 1000,
        tz=timezone.utc
    )

def kline_timestamp_to_utc(value):
    # Second-based timestamp
    return datetime.fromtimestamp(
        int(value),
        tz=timezone.utc
    )

# quote is a parsed HTTP order book data record
quote_time_utc = tick_time_to_utc(quote["tick_time"])

# Convert to the specified time zone for display
quote_time_local = quote_time_utc.astimezone(DISPLAY_TZ)

# Record the local receive time when the market data message arrives
received_at_utc = datetime.now(timezone.utc)

# Calculate the observed time difference in milliseconds
observed_gap_ms = (
    received_at_utc - quote_time_utc
).total_seconds() * 1000

Note that Asia/Shanghai is only used as an example for display. For an application targeting the US stock market, America/New_York can be used instead. If the system needs to display time according to each user's local time zone, it should use the corresponding time zone identifier.

For K-line data, call kline_timestamp_to_utc() instead. The millisecond conversion logic should not be applied directly.

Trading Hours and Market Data Update Times Are Not the Same

Another situation that is easily mistaken for a timestamp problem is when market timestamps remain unchanged for an extended period.

For example, an application is subscribed to real-time market data for a stock. The WebSocket connection remains active, but both the price and timestamp stay at their previous values.

This does not necessarily mean that the API has failed. The stock market may have entered its lunch break or closed for the day. It is also possible that no new quotes or trades have occurred temporarily.

It is important to understand that trading hours are not the same as continuous market data update times. Exchange trading calendars, opening hours, and holiday schedules all affect market data updates. Trading hours also vary across different markets.

When troubleshooting, check three things at the same time: whether the current time falls within the trading session for the relevant instrument, whether the WebSocket connection and heartbeat are functioning normally, and whether the API has received any new market data messages.

If market timestamps continue to update but the difference between them and the local receive time gradually increases, the server's system clock should also be checked. In production environments, it is recommended to synchronize the system clock using NTP or Chrony. Otherwise, clock drift on the server itself may affect latency measurements.

Establish a Consistent Time-Handling Process When Integrating a Real-Time Market Data API

For applications that display multiple types of market data, such as stocks, forex, and cryptocurrencies, it is better not to implement separate timestamp conversion logic in every business module.

A more reliable approach is to parse timestamps in the data ingestion layer according to each API's field definitions and convert them into datetime objects with UTC time zone information. The market time and receive time should then be stored separately, while the presentation layer converts them according to the user's time zone or the relevant market's time zone.

AllTick provides REST API and WebSocket API interfaces. Developers can use them to retrieve real-time quotes, order book data, and historical K-line data according to their application requirements. The fields and time definitions of different interfaces should be checked separately. In particular, the same timestamp parsing rules should not be applied indiscriminately to Tick, order book, and K-line data.

For developers building real-time market monitoring dashboards or quantitative trading systems, the AllTick official product and developer portal provides information about supported market data types and related APIs.

The troubleshooting process for timestamp issues is relatively straightforward: first, identify what time each field represents; then check whether seconds and milliseconds are being converted correctly; next, verify the time zone; and finally, compare the market timestamp with the actual receive time. By examining these elements separately, developers can determine whether the problem lies in data parsing, the server's system clock, or the market data update process itself.

Start streaming market data today

Generate a free API key in seconds and connect to every market from one endpoint.