Metrics
- Overview
- All available metrics
- Metrics Documentation
- All available assets
- Available metrics per project
- Available projects per metric
- Queryable fields
- aggregatedTimeseriesData
- histogramData
- metadata
- availableSince
- lastDatetimeComputedAt
Overview
The getMetric
API gives a unified API for many different metrics across the
whole universe of supported assets. The query allows to get metadata, first/last
datetime available and different metric representations - timeseries data,
histogram data, aggregated timeseries data.
Supported blockchains:
Bitcoin | Ethereum | Ripple |
---|---|---|
BNB Chain | Bitcoin Cash | Litecoin |
---|---|---|
Cardano | Dogecoin | Polygon |
---|---|---|
Avalanche (ERC20) | Optimism | Arbitrum |
---|---|---|
All available metrics
The list of all available metrics can be fetched with this query:
1 2 3
{ getAvailableMetrics }
The list of available metrics for given plan can be fetched by supplying the plan
argument with query like this:
1 2 3
{ getAvailableMetrics(plan: PRO) }
Documentation for those metrics can be found on the metrics page
Metrics Documentation
Documentation for most of the metrics can be found on this page.
All available assets
Every metric is fetched for a given asset, identified by its slug
.
Documentation about biw to fetch all available assets can be found here
Available metrics per project
The set of available metrics is not the same for each asset. The following query shows three lists:
- All available metrics
- The subset of all available metrics that are timeseries metrics
- The subset of all available metrics that are histogram metrics
1 2 3 4 5 6 7
{ projectBySlug(slug: "ethereum") { availableMetrics availableTimeseriesMetrics availableHistogramMetrics } }
Available projects per metric
The getMetric
API supports a large list of assets identified by their slug.
For a given metricthe list of available slugs can be fetched with this query:
1 2 3 4 5 6 7
{ getMetric(metric: "mvrv_usd"){ metadata{ availableSlugs } } }
Queryable fields
The fields that can be queried on getMetric
:
timeseriesData
aggregatedTimeseriesData
histogramData
metadata
availableSince
lastDatetimeComputedAt
Aggregation
Some of the queryable fields accept an aggregation parameter.
When an interval
bigger than minInterval
is provided for a given metric,
more than 1 data point values will be aggregated into a single data point.
The aggregations types are:
SUM
- The sum of all the valuesAVG
- The average of the valuesMEDIAN
- The median of all the valuesFIRST
- The first valueLAST
- The last valueMAX
- The max valueMIN
- The min valueANY
- Any value falling in the larger interval. This is usually used when all values are expected to have the same result and you just want to take one of them.
Note: The aggregation should be provided capitalized without quotes like this:
aggregation: MAX
The following query fetches the default aggregation and all available aggregations per metric:
1 2 3 4 5 6 7 8
{ getMetric(metric: "daily_active_addresses") { metadata { defaultAggregation availableAggregations } } }
timeseriesData
Timeseries data is a sequence taken at successive equally spaced points in time.
For every point the API provides a datetime
and a value
field.
To fetch the values for a given metric, slug and time range you can use the
timeseriesData
subquery of the getMetric
API.
Parameters:
Parameter | Description |
---|---|
slug | The slug of the project |
from | From which date to return the values in ISO8601 format |
to | Until which date to return the values in ISO8601 format |
interval | The intervals that should be returned. Default is 1d . Optional |
aggregation | The aggregation to be used when fetching data for longer intervals. Optional |
includeIncompleteData | Exclude the last incomplete day (today) if it lead to misleading data. Default is false . Optional |
transform | Apply a transformation on the the result. Default is none . Optional |
- aggregation - This parameter is optional and if it is not provided - every metric has a default one that fits best. You can see the default aggregation function using the metadata query.
- includeIncompleteData - In some cases if the day is not finished the current value can be misleading. For example fetching daily active addresses at 12pm would include only half a day of data and because of the that the data for that day could seem too low.
- transform - Apply a transformation to the timeseries data result. Available
transformations:
{type: "none"}
- Do not apply any transformation{type: "moving_average", moving_average_base: base}
- Apply a simple moving average. For every data point the value is calculated as the average of the lastbase
intervals. In order to compute this internally it fetches enough data beforefrom
so it can be computed.{type: "changes"}
- For every data point change the value to the difference between the value and the previous value.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
{ getMetric(metric: "dev_activity") { timeseriesData( slug: "santiment" from: "2019-01-01T00:00:00Z" to: "2019-09-01T00:00:00Z" includeIncompleteData: true interval: "7d" aggregation: SUM transform: { type: "moving_average", moving_average_base: 3 } ) { datetime value } } }
aggregatedTimeseriesData
Aggregated timeseries data is used when you don't need many values separated apart by an even interval but just a single value. This can be used to fetch the ATH price or the highest daily active addresses ever as one of the many examples.
Parameters:
Parameter | Description |
---|---|
slug | The slug of the project |
from | From which date to return the values in ISO8601 format |
to | Until which date to return the values in ISO8601 format |
aggregation | The aggregation to be used when fetching data for longer intervals. Optional |
- aggregation - This parameter is optional and if it is not provided - every metric has a default one that fits best. You can see the default aggregation function using the metadata query.
The following query fetches the all time highest price for santiment:
1 2 3 4 5 6 7 8 9 10
{ getMetric(metric: "price_usd") { highest_price: aggregatedTimeseriesData( slug: "santiment" from: "2017-07-01T00:00:00Z" to: "2020-04-01T00:00:00Z" aggregation: MAX ) } }
histogramData
A histogram is an approximate representation of the distribution of numerical or categorical data.
This is better understood with an example: For the period of January 2018 - January 2019, fetch the amount of Ether that was bought in every 100-dollar price range: $0-$100, $100-$200, ... , $1300-$1400.
To fetch the values for a given histogram metric, slug and time interval you can
use the histogramData
subquery of the getMetric
API.
Parameters:
Parameter | Description |
---|---|
slug | The slug of the project |
from | From which date to return the values in ISO 8601 format |
to | Till which date to return the values in ISO 8601 format |
interval | The intervals that should be returned. Default is 1d |
limit | The number of results returned. Optional |
Different histogram metrics could have different response types/formats.
Example 1
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
{ getMetric(metric: "age_distribution") { histogramData( slug: "santiment" from: "2020-02-10T07:00:00Z" to: "2020-03-30T07:00:00Z" interval: "1d" ) { values { ... on DatetimeRangeFloatValueList { data { range value } } } } } }
The response result is a list that contains a 2-element range of datetimes and a float value.
Explanation:
For all Santiment tokens moved between January 6th, 2020 and January 7th, 2020,
fetch when these tokens last moved. The result is two lists - of labels and of
values. For every label there is a corresponding value. The following label The amount of tokens last moved between 2018-11-30 00:00 Etc/UTC and 2018-12-01 00:00 Etc/UTC
has a corresponding value of 18645
, meaning that 18.6k of the
tokens moved in the specified 1 day interval moved for the last time between
November 30th, 2018 and December 1st, 2018.
Example 2
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
{ getMetric(metric: "price_histogram") { histogramData( slug: "santiment" from: "2020-02-10T07:00:00Z" to: "2020-03-30T07:00:00Z" interval: "1d" ) { values { ... on FloatRangeFloatValueList { data { range value } } } } } }
The response result is a list that contains a 2-element range of float (prices) and a float value.
availableMetrics
- The list of all metrics.availableTimeseriesMetrics
- The subset of the available metrics that are fetchable via thetimeseriesData
field.availableHisogramMetrics
- The subset of the available metrics that are fetchable via thehistogramData
field.
metadata
Each metric has metadata describing:
- What is the minimal interval it can be fetched for. Different metrics are available with different granularities.
- What is the default aggregation which will be used when getting the metric for higher resolution.
- What are the supported aggregations for the metric.
- What are the existed selectors for the metric.
- Which are the projects the metric is available for.
- What is the type of the metrics - timeseries or histogram
1 2 3 4 5 6 7 8 9 10 11 12
{ getMetric(metric: "daily_active_addresses") { metadata { availableAggregations availableSelectors availableSlugs dataType defaultAggregation minInterval } } }
availableSince
To fetch the datetime from which a given metric is available for an asset:
1 2 3 4 5
{ getMetric(metric: "transaction_volume") { availableSince(slug: "santiment") } }
A metric is usually available for a given asset since the creation of the contract/blockchain.
Exception to this statement is when pricing data is needed in order to calculate the metric and the price data is missing. For example, Bitcoin is working since the beginning of 2009, but because there were no exchanges and markets for over an year, the pricing data starts from July 2010. This means that MVRV, which requires market capitalization, is also available since July 2010.
lastDatetimeComputedAt
To fetch the datetime for which the last data point for the metric/slug pair is computed:
1 2 3 4 5
{ getMetric(metric: "daily_active_addresses") { lastDatetimeComputedAt(slug: "santiment") } }
Knowledge of the last datetime computed is essential in some cases. The daily metrics (metrics which have one value per day) are recomputed several times a day.
Note: In many cases such incomplete days can lead to misleading data. For example the Daily Active Address can appear to be much lower than the usual, but this can be caused by the fact that they contain only half a day of data. By default the
includeIncompleteData
flag intimeseriesData
is set to false. In this case the current day data will be seen only when the day finishes.