Skip to main content

Time Series

Our signals are all stored as a complete time series.

To retrieve a full time series data set for a particular signal you just need to use the Get Signal Data endpoint:

https://api.clearmacro.com/api/v3/signal/{signal_code}/{signal_version}/data/

Along with the relevant tags for the variant you want data for. By default the data will be returned in Parquet format which can be easily read and manipulated using the Pandas framework in Python.

import io

import pandas as pd
import requests

url = "https://api.clearmacro.com/api/v3/signal/ECNBALM/2/data/?country_iso=USA"
headers = {"X-API-KEY": "YOUR_API_KEY"}
response = requests.get(url=url, headers=headers)

if 200 <= response.status_code < 299:
    # On successful request load data into to pandas dataframe
    dataframe = pd.read_parquet(io.BytesIO(response.content))
else:
    # If the request failed, print the error code and message
    print("Error occurred")
    print("{response.status_code}: {response.content}")

You can find a much more detailed explaination of how to pull signal data from our API here

Data Structure

For each Signal, three columns are included.

  1. Level - the signal score computed over the underyling raw signal.
  2. Momentum - the signal score computed over the first derivative of the underlying raw signal.
  3. Aggregate - aggregation of the Level and Momentum values.
| Date       | Level              | Momentum           | Aggregate          |
|------------|--------------------|--------------------|--------------------|
| 2022-02-03 |  2.963997324233545 | 3.8151095045771424 | 3.3895534144053436 |
| 2022-02-04 |  2.949988399322118 | 3.8152687949783597 |  3.382628597150239 |
| 2022-02-05 |  2.938107972657662 |  3.819478652190406 |  3.378793312424034 |
| 2022-02-06 |  2.923679012072327 |  3.815374116317438 | 3.3695265641948824 |
| 2022-02-07 | 2.9088276885088384 |  3.808925720059262 |   3.35887670428405 |
| 2022-02-08 | 2.8939791712395957 | 3.7992816145554875 | 3.3466303928975414 |

Point In Time Data

By default all data you request will be the latest available that we have in our databases. However, we support requesting data that we produced from any other point in time.

For instance, to request the data from 2023-08-24T12:00:00 you just have to specify the as_of_utc parameter.

curl -X "GET" \
https://api.clearmacro.com/api/v3/signal/ECNBALM/2/data/?fmt=parquet&kind=SNAP&country_iso=USA&as_of_utc=2023-08-24T12%3A00%3A00
-H "X-API-KEY:$API_KEY" > ECNBALM_USA.parquet
note

as_of_utc needs to be a ISO 8601 formatted string

Alternative data formats

If you wish to load the data into Excel or work on it in another programming language that does not have a dataframe analogue; you can also request the data in CSV or JSON formats by using the fmt parameter.

curl -X "GET" \
https://api.clearmacro.com/api/v3/signal/ECNBALM/2/data/?fmt=csv&kind=SNAP&country_iso=USA&as_of_utc=2023-08-24T12%3A00%3A00
-H "X-API-KEY:$API_KEY" > ECNBALM_USA.parquet
note

More information about each data format can be found using the following links:

Fixed In Time Data

By default all data returned will be in Point In Time (SNAP) format where the entire time series is re-calculated each time it is produced and is subject to vendor revisions etc. We also support a Fixed In Time (FIT) format where the time series is composed completely of values as they were reported at the time.

To demonstrate this point, consider a time series which evolves over time like so:

        SNAP                                              FIT


| Date       | Value |                            | Date       | Value |
|------------|-------|                            |------------|-------|
| 2022-02-03 |  1    |                            | 2022-02-03 |  1    |


| Date       | Value |                            | Date       | Value |
|------------|-------|                            |------------|-------|
| 2022-02-03 |  0.5  |                            | 2022-02-03 |  1    |
| 2022-02-04 |  2    |                            | 2022-02-04 |  2    |


| Date       | Value |                            | Date       | Value |
|------------|-------|                            |------------|-------|
| 2022-02-03 |  0.5  |                            | 2022-02-03 |  1    |
| 2022-02-04 |  2.2  |                            | 2022-02-04 |  2    |
| 2022-02-05 |  3    |                            | 2022-02-05 |  3    |

This example is purposefully fairly extreme but you can see how SNAP is subject to historical vendor revisions, where as FIT stays consistent with which ever values were reported at the time.

To query for FIT data, just set the kind parameter accordingly:

curl -X "GET" \
https://api.clearmacro.com/api/v3/signal/ECNBALM/2/data/?fmt=csv&kind=FIT&country_iso=USA&as_of_utc=2023-08-24T12%3A00%3A00
-H "X-API-KEY:$API_KEY" > ECNBALM_USA.parquet