Skip to main content

Variants

Each signal is comprised of numerous variants, each describing a specific market, asset or territory. Each variant has one or more tags attached to them and are used to query for its data.

To get information on what variants a specific signal has, you can use the Get Signal By Code endpoint:

https://api.clearmacro.com/api/v3/signal/{signal_code}/{signal_version}/
import requests
from pprint import pprint

url = "https://api.clearmacro.com/api/v3/signal/ECNBALM/2/"
headers = {"accept": "application/json", "X-API-KEY": "YOUR_API_KEY"}
response = requests.get(url=url, headers=headers)
pprint(response.json())

The API will respond with JSON output similar to the below.

{
  "name": "Basic Balance Master",
  "code": "ECNBALM",
  "tags": [
    {
      "kind": "country_iso",
      "values": [
        "ARG",
        "AUS",
        ...
        "USA",
        "VNM",
        "ZAF"
      ],
      "sub_tags": null
    },
    {
      "kind": "region",
      "values": [
        "Asia",
        "Developed Markets",
        "Developed Markets Asia-Pacific",
        ...
        "Nordic",
        "North America",
        "World"
      ],
      "sub_tags": null
    }
  ],
  "version": 2
}
View Full Response
{ "name": "Basic Balance Master", "code": "ECNBALM", "tags": [ { "kind": "country_iso", "values": [ "ARG", "AUS", "AUT", "BEL", "BGD", "BRA", "CAN", "CHL", "CHN", "COL", "CZE", "DEU", "DNK", "EGY", "ESP", "EST", "FIN", "FRA", "GBR", "GRC", "HKG", "HRV", "HUN", "IDN", "IND", "ISR", "ITA", "JOR", "JPN", "KAZ", "KOR", "LKA", "LTU", "MAR", "MEX", "MUS", "NLD", "NOR", "NZL", "PAK", "PHL", "POL", "PRT", "QAT", "ROU", "RUS", "SAU", "SGP", "SRB", "SVN", "SWE", "THA", "TUR", "USA", "VNM", "ZAF" ], "sub_tags": null }, { "kind": "region", "values": [ "Asia", "Developed Markets", "Developed Markets Asia-Pacific", "Emerging Markets", "Emerging Markets Asia", "European Union", "Eurozone", "Frontier Markets", "Latin America", "Nordic", "North America", "World" ], "sub_tags": null } ], "version": 2 }

Here we can see that the signal ECNBALM version 2 has 55 country and 12 regional variants that can be queried independently.

Multi Dimensional Variants

Some signals have variants that are described by multiple tags. These are shown in the API response through use of the sub_tags field.

An example of this type of signal is Equity Flows Sector, which has the signal code EQFLOS.

The Equity Flows Sector signal processes data on sectors within a specific country. You need to use both country_iso and sector to get specific signal variants.

import requests
from pprint import pprint
url = f"https://api.clearmacro.com/api/v3/signal/EQFLOS/1/"
headers = {"X-API-KEY": api_key}
response = requests.get(url=url, headers=headers)
pprint(response.json())

The response this time looks slightly different. We now have sub_tags included with each entry in the list of tags.

{
  "name": "Equity Flows Sector",
  "code": "EQFLOS",
  "tags": [
    {
      "kind": "country_iso",
      "values": [
        "USA"
      ],
      "sub_tags": [
        {
          "kind": "sector",
          "values": [
            "Basic Materials",
            ...
            "Utilities"
          ]
        }
      ]
    },
    ...
    {
      "kind": "sector",
      "values": [
        "Utilities"
      ],
      "sub_tags": [
        {
          "kind": "country_iso",
          "values": [
            "USA"
          ]
        }
      ]
    }
  ],
  "version": 1
}
View Full Response
{ "name": "Equity Flows Sector", "code": "EQFLOS", "tags": [ { "kind": "country_iso", "values": [ "USA" ], "sub_tags": [ { "kind": "sector", "values": [ "Basic Materials", "Consumer Discretionary", "Consumer Staples", "Energy", "Financials", "Health Care", "Industrials", "Technology", "Telecommunications", "Utilities" ] } ] }, { "kind": "sector", "values": [ "Technology" ], "sub_tags": [ { "kind": "country_iso", "values": [ "USA" ] } ] }, { "kind": "sector", "values": [ "Telecommunications" ], "sub_tags": [ { "kind": "country_iso", "values": [ "USA" ] } ] }, { "kind": "sector", "values": [ "Health Care" ], "sub_tags": [ { "kind": "country_iso", "values": [ "USA" ] } ] }, { "kind": "sector", "values": [ "Financials" ], "sub_tags": [ { "kind": "country_iso", "values": [ "USA" ] } ] }, { "kind": "sector", "values": [ "Consumer Discretionary" ], "sub_tags": [ { "kind": "country_iso", "values": [ "USA" ] } ] }, { "kind": "sector", "values": [ "Consumer Staples" ], "sub_tags": [ { "kind": "country_iso", "values": [ "USA" ] } ] }, { "kind": "sector", "values": [ "Industrials" ], "sub_tags": [ { "kind": "country_iso", "values": [ "USA" ] } ] }, { "kind": "sector", "values": [ "Basic Materials" ], "sub_tags": [ { "kind": "country_iso", "values": [ "USA" ] } ] }, { "kind": "sector", "values": [ "Energy" ], "sub_tags": [ { "kind": "country_iso", "values": [ "USA" ] } ] }, { "kind": "sector", "values": [ "Utilities" ], "sub_tags": [ { "kind": "country_iso", "values": [ "USA" ] } ] } ], "version": 1 }

Here you can see how each tag contains a populated sub_tags field, showing that they are related and need to be queried together for this signal.