• Documentation
  • Common Data Service API Specifications

Common Data Service API Specifications


Common Data Service offers data providers a series of unified API specifications. Only APIs that have completed standardization according to the specifications can be registered as data sources for Common Data Service. For more information about how to register data sources, see Registering a Data Source.


Common Data Service supports registering APIs of the Metrics, Accumulative Points, Attributes, and Records types as data sources. The following describes the general specifications to be followed by all API types, and the special specifications to be followed by each API type.

General Specifications


All APIs of the Metrics, Accumulative Points, Attributes, and Records types need to follow the specifications below:

  • The response code for successful API calls is 0.

  • Common Data Service does not require authentication to call the data source APIs for data.

  • If historical, current, and future data are to be provided at the same time, use one of the following two options:

    • Use the Metrics APIs, which provide historical data, in conjunction with the Accumulative Points APIs, which provide current and future data. Do not return current and future data through the Metrics APIs unless they are used in a special future-data scenario such as planned production.
    • Current and future data are provided through the Metrics APIs and there is no separate Accumulative Points API.

  • In the Metrics and Accumulative Points APIs, the time format specification for the timeGroup (aggregation time granularity) parameter is as follows.


    Time Granularity Description Time Format Example
    RAW Raw Data YYYY-MM-DD hh:mm:ss 2021-03-25 00:00:01
    1m 1 Minute YYYY-MM-DD hh:mm:ss 2021-03-25 00:01:00
    5m 5 Minutes YYYY-MM-DD hh:mm:ss 2021-03-25 00:05:00
    10m 10 Minutes YYYY-MM-DD hh:mm:ss 2021-03-25 00:10:00
    15m 15 Minutes YYYY-MM-DD hh:mm:ss 2021-03-25 00:15:00
    30m 30 Minutes YYYY-MM-DD hh:mm:ss 2021-03-25 00:30:00
    H Hour YYYY-MM-DD hh:mm:ss 2021-03-25 01:00:00
    D Day YYYY-MM-DD 2021-03-25
    W Week YYYY-Wxx 2021-W12
    M Month YYYY-MM 2021-03
    Q Quarter YYYY-Qx 2021-Q1
    Y Year YYYY 2021
    T Total 1970 1970
    L Latest YYYY-MM-DD hh:mm:ss 2021-03-25 00:00:01

  • In the Metrics APIs, the specifications for the returned results vary according to the timeGroup (aggregation time granularity) parameter:

    • If timeGroup is L, users do not need to pass in the startTime and endTime request parameters, and the data source API needs to return the latest time if the time of multiple requested metrics is inconsistent.
    • If timeGroup is a time granularity other than L, users need to specify a time range in the request, and the data source API needs to return data in a left-closed and right-closed interval according to the granularity. For example, the Production metric supports the D, M, and Y aggregation granularity and the data to be returned in different scenarios are as follows:
      • If the specified time range is 2021-01-01 00:00:00 to 2021-01-05 00:00:00 and timeGroup is D, the daily production from 2021-01-01 to 2021-01-05 is returned.
      • If the specified time range is 2021-01-05 00:00:00 to 2021-02-05 00:00:00 and timeGroup is M, the monthly aggregated production from 2021-01-05 to 2021-01-31 and from 2021-02-01 to 2021-02-05 is returned respectively.
      • If the specified time range is 2020-01-05 00:00:00 to 2021-02-05 00:00:00 and timeGroup is Y, the yearly aggregated production from 2020-01-05 to 2020-12-31 and from 2021-01-01 to 2021-02-05 is returned respectively.