• 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.

Type-Specific Specifications