Tandem Data API – Reading Stream Data

In the two previous Tandem articles, you learned how to ingest data into streams in your facility and how to create streams. In this article you will learn how to read data from streams using the API. This may be useful in some scenarios, for example:

• Extract stream data for reporting.
• Use stream data as input for further analytics.

To read stream data, you use this API:

GET timeseries/models/{modelID}/streams/{elementID}

As mentioned in previous articles, Tandem stores stream data in the 'default' model. The URN of the default model is the same as URN of the facility, but with a different prefix (urn:adsk.dtm).

Here's a sample response using the above GET request:

{
    "z:Dg": {
        "1716540287627": 21.15,
        "1716543887627": 20.69,
        "1716547487627": 21.98,
        "1716551087627": 21.18,
        "1716554687627": 22.93,
        "1716558287627": 19.15,
        "1716561887627": 19.4,
        "1716565487627": 20.57,
        "1716569087627": 22.72,
        "1716572687627": 22.04
    }
}

The response contains data points for each parameter – the parameter can be identified using its fully qualified ID. The model schema API provides more details about parameters. In this specific case z:Dg refers to Temperature parameter:

{
    "id": "z:Dg",
    "fam": "z",
    "col": "Dg",
    "name": "Temperature",
    "category": "Higher Education",
    "dataType": 3,
    "flags": 20,
    "forgeUnit": "celsius",
    "forgeSymbol": "degreeC",
    "forgeSpec": "piping.temperature",
    "context": "e"
}

Data points are returned in the following format:

time: value

where time is the time of event in Epoch format.
The API supports additional options using query parameters:

from, to

These parameters can be used to specify an interval of stream data. The value should be in Unix epoch format.
It is possible to specify either one or both, i.e.:

GET https://developer.api.autodesk.com/tandem/v1/timeseries/models/urn:adsk.dtm:WtMe53OeTWuvLaCP4bvZkw/streams/AQAAAHFE8EBchkbYhDzh9roHEXAAAAAA?from=1716540287627

GET https://developer.api.autodesk.com/tandem/v1/timeseries/models/urn:adsk.dtm:WtMe53OeTWuvLaCP4bvZkw/streams/AQAAAHFE8EBchkbYhDzh9roHEXAAAAAA?to=1716662687627

GET https://developer.api.autodesk.com/tandem/v1/timeseries/models/urn:adsk.dtm:WtMe53OeTWuvLaCP4bvZkw/streams/AQAAAHFE8EBchkbYhDzh9roHEXAAAAAA?from=1716540287627&to=1716662687627

limit

This parameter controls the maximum number of data points returned in the response.

sort

This parameter controls the order of returned data. Supported values are asc, desc. It is applied together with the limit parameter only.

substream

This parameter queries data points for a specific parameter rather than all streams. Use a qualified parameter id as input, i.e.:

GET https://developer.api.autodesk.com/tandem/v1/timeseries/models/urn:adsk.dtm:WtMe53OeTWuvLaCP4bvZkw/streams/AQAAAHFE8EBchkbYhDzh9roHEXAAAAAA?substream=z:Dg

Example

Below is a code snippet to list all streams from the facility together with their data points:

const streams = await client.getStreams(defaultModel.modelId);

for (const stream of streams) {
    // STEP 4 - get stream data for last NN days and print their values
    const streamKey = Encoding.toFullKey(stream[QC.Key], true);

    console.log(`${stream[QC.Name]}`);
    const data = await client.getStreamData(defaultModel.modelId, streamKey, from, to);

    for (const item in data) {
        const propDef = schema.attributes.find(p => p.fam === ColumnFamilies.DtProperties && p.id === item);

        if (!propDef) {
            console.warn(`Unable to find property definition: ${item}`);
        }
        console.log(`  ${propDef?.name} (${item})`);
        const values = data[item];

        for (const ts in values) {
            const date = new Date(parseInt(ts));

            console.log(`    [${date.toLocaleString()}]: ${values[ts]}`);
        }
    }
}

Wrap up

In this article you learned how to use the API to get stream data. You can find the complete example here (JavaScript). There is also a Python version available.

Feel free to contact us in case of any questions or if you need any help with the Tandem API: aps.help@autodesk.com. You can also submit your questions via StackOverflow and mark them using autodesk-tandem tag.