Fetching Metrics
- Overview
- Available Metrics
- Metrics Restrictions Per Plan
- Metrics Documentation
- Available Assets
- Available Metrics Per Project
- Available Projects Per Metric
- Minimal Interval
- Aggregation
- Queryable Fields
- Examples
Overview
The getMetric
GraphQL query provides a unified method for accessing a variety of metrics across all supported assets. This query enables you to retrieve metadata, datetime availability, and various metric representations, including timeseries data, histogram data, and aggregated timeseries data.
Here is an example of a GraphQL getMetric
query:
1 2 3 4 5 6 7 8 9 10 11 12
{ getMetric(metric: "active_addresses_24h") { timeseriesData( slug: "bitcoin" from: "2023-05-01T08:00:00Z" to: "2023-05-02T08:00:00Z" interval: "30m") { datetime value } } }
This query retrieves the timeseries data for the metric "active_addresses_24h" for Bitcoin, from 8:00 on May 1, 2023, to 8:00 on May 2, 2023, with a 30-minute interval between data points.
Available Metrics
You can fetch the list of all available metrics using the following query:
1 2 3
{ getAvailableMetrics }
To fetch the list of available metrics for a specific plan and product, provide the plan
and product
arguments in the query:
1 2 3
{ getAvailableMetrics(product: SANAPI plan: PRO) }
Metrics restrictions per plan
Access to certain metrics may be limited in various ways based on your subscription plan:
- Some metrics may not be accessible to users on lower-tier subscription plans.
- Lower-tier subscription plans may have limited access to certain metrics, excluding access to historical and real-time data.
You can obtain detailed information about the restrictions on all metrics for a specific subscription plan using this query.
Here is an example of a GraphQL query:
1
2
3
4
5
6
7
8
9
10
11
{
getAccessRestrictions(product: SANAPI plan: PRO){
name
type
minInterval
isAccessible
isRestricted
restrictedFrom
restrictedTo
}
}
Metrics Documentation
You can find the documentation for most of the metrics on this page.
Available Assets
Each metric is retrieved for a specific asset, which is identified by its slug
.
Instructions on how to fetch all available assets can be found in our Glossary. You can obtain a list of all slugs using this query:
1 2 3 4 5
{ allProjects{ slug } }
Available metrics per project
The range of available metrics varies for each asset. The query below demonstrates three distinct lists:
- All accessible metrics
- A subset of all accessible metrics that are timeseries metrics
- A subset of all accessible metrics that are histogram metrics
You can retrieve these lists of metrics using this query:
1 2 3 4 5 6 7
{ projectBySlug(slug: "ethereum") { availableMetrics availableTimeseriesMetrics availableHistogramMetrics } }
Available projects per metric
The getMetric
API supports a comprehensive list of assets, each identified by a unique slug. To fetch the list of available slugs for a specific metric, use the following query:
1 2 3 4 5 6 7
{ getMetric(metric: "mvrv_usd"){ metadata{ availableSlugs } } }
Minimal Interval
Metrics are stored as pairs of datetime and value. The term minInterval
refers to the time interval between two consecutive data points. It signifies the smallest interval that can be utilized when querying the metric.
The most frequently used minInterval
s include:
- 1 day (
1d
): Metrics with this interval are typically referred to as "daily" metrics. - 5 minutes (
5m
): Metrics with this interval are often called "intraday" metrics.
When querying data, the interval
argument is used to determine the resolution of the data. This interval can be significantly larger than the minInterval
. In such instances, all the values within that larger interval must be aggregated into a single value. The aggregation
parameter controls how this data is aggregated.
Aggregation
Fields that return timeseries data accept an aggregation
parameter. When an interval
larger than minInterval
is provided for a specific metric, multiple data point values will be consolidated into a single data point.
Note: Each metric has a manually selected default aggregation that is used if the
aggregation
parameter is not specified. The default aggregation is chosen to be the most logical one.
The types of aggregations are:
SUM
- The total of all values.AVG
- The average of the values.MEDIAN
- The median of all values.FIRST
- The earliest value (with the smallest datetime).LAST
- The most recent value (with the latest datetime).MAX
- The largest value.MIN
- The smallest value.ANY
- Any value within the interval. This is typically used when all values are expected to be the same, and you just want to select one of them. No metrics use this as their default aggregation. This type of aggregation is more commonly used when users write their own SQL queries using the Santiment Queries product.
Note: The aggregation is of the GraphQL enum type and should be provided in uppercase without quotes, like this:
aggregation: MAX
.
The following query retrieves the default aggregation and all available aggregations for each metric:
1 2 3 4 5 6 7 8
{ getMetric(metric: "daily_active_addresses") { metadata { defaultAggregation availableAggregations } } }
Queryable fields
In the getMetric
function, you can query the following fields:
timeseriesData
timeseriesDataPerSlug
aggregatedTimeseriesData
histogramData
metadata
availableSince
lastDatetimeComputedAt
timeseriesData
Timeseries data is a sequence of data points collected at consistent intervals over time. Each data point provided by the API includes a datetime
and a value
field.
To retrieve the values for a specific 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 | The starting date for the values to be returned, in ISO8601 format |
to | The ending date for the values to be returned, in ISO8601 format |
interval | The intervals to be returned. The default is 1d . This is optional |
aggregation | The aggregation to be used when fetching data for longer intervals. This is optional |
includeIncompleteData | Exclude the last incomplete day (today) if it could lead to misleading data. Default is false . This is optional |
transform | Apply a transformation to the result. Default is none . This is optional |
aggregation
: This parameter is optional. If not provided, each metric has a default aggregation that is most suitable. You can view the default aggregation function using the metadata query.includeIncompleteData
: In some cases, if the day is not yet complete, the current value can be misleading. For instance, fetching daily active addresses at 12pm would include only half a day's data, potentially making the data for that day appear too low.transform
: Apply a transformation to the timeseries data result. Available transformations include:{type: "none"}
: Do not apply any transformation{type: "moving_average", moving_average_base: base}
: Apply a simple moving average. Each data point value is calculated as the average of the lastbase
intervals. To compute this, it fetches enough data beforefrom
so it can be computed.{type: "changes"}
: For each 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 useful when you require a single value instead of multiple values separated by an even interval. This can be utilized to fetch the All-Time High (ATH) price or the highest number of daily active addresses, among other examples.
Parameters:
Parameter | Description |
---|---|
slug | The slug of the project |
from | The start date for the returned values in ISO8601 format |
to | The end date for the returned values in ISO8601 format |
aggregation | The aggregation to be used when fetching data for longer intervals (Optional) |
aggregation
: This parameter is optional. If not provided, each metric has a default aggregation function that is most suitable. The default aggregation function can be viewed 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 a graphical representation that organizes a group of data points into a specified range. For instance, if we consider the period from January 2018 to January 2019, we can 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 | The start date for the values in ISO 8601 format |
to | The end date for the values in ISO 8601 format |
interval | The intervals to be returned. Default is 1d |
limit | The number of results to be returned. Optional |
Different histogram metrics may have different response types or formats.
availableMetrics
- The list of all metrics.availableTimeseriesMetrics
- The subset of the available metrics that can be fetched via thetimeseriesData
field.availableHistogramMetrics
- The subset of the available metrics that can be fetched via thehistogramData
field.
metadata
Each metric is accompanied by metadata that describes the following:
- The minimum interval for which it can be fetched. Different metrics are available at varying granularities.
- The default aggregation that will be used when retrieving the metric at a higher resolution.
- The supported aggregations for the metric.
- The existing selectors for the metric.
- The projects for which the metric is available.
- The type of the metric, which can be either a timeseries or a 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
You can fetch the date from which a specific metric is available for an asset using the following query:
1 2 3 4 5
{ getMetric(metric: "transaction_volume") { availableSince(slug: "bitcoin") } }
Typically, a metric is available for a given asset from the moment the contract or blockchain is created. However, there are exceptions. For instance, if the calculation of a metric requires pricing data that is not available, the metric will only be available from the date the pricing data becomes available.
For example, Bitcoin has been operational since early 2009, but there were no exchanges or markets for over a year. Therefore, the pricing data only starts from July 2010. As a result, the MVRV metric, which requires market capitalization, is also only available since July 2010.
lastDatetimeComputedAt
Note: This field may be complex to understand. However, in most scenarios, it's not necessary to comprehend its value.
The lastDatetimeComputedAt
field is utilized to retrieve the datetime for which the last data point for the metric/slug pair was computed:
1 2 3 4 5
{ getMetric(metric: "daily_active_addresses") { lastDatetimeComputedAt(slug: "santiment") } }
Understanding the last datetime computed can be crucial in certain situations. Daily metrics (metrics that have one value per day) are recalculated multiple times throughout the day. Each recalculation includes more data than the previous one.
Note: In many instances, such incomplete days can result in misleading data. For example, the Daily Active Address might appear significantly lower than usual. This discrepancy could be due to the fact that only half a day's data is included. By default, the
includeIncompleteData
flag intimeseriesData
is set to false. Therefore, the current day's data will only be visible once the day has ended.
Examples
Timeseries Data Example
1 2 3 4 5 6 7 8 9 10 11 12
{ getMetric(metric: "active_addresses_24h") { timeseriesData( slug: "bitcoin" from: "2023-05-01T08:00:00Z" to: "2023-05-02T08:00:00Z" interval: "30m") { datetime value } } }
Timeseries Data Example
1 2 3 4 5 6 7 8 9 10 11 12 13
{ getMetric(metric: "twitter_followers") { timeseriesData( slug: "maker" from: "2023-01-01T00:00:00Z" to: "2023-02-01T00:00:00Z" interval: "7d" transform: {type: "consecutive_differences"}) { datetime value } } }
Aggregated Timeseries Data Example
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
{ getMetric(metric: "daily_active_addresses") { highest_daa: aggregatedTimeseriesData( slug: "ethereum" from: "2022-01-01T00:00:00Z" to: "2023-01-01T00:00:00Z" aggregation: MAX ) lowest_daa: aggregatedTimeseriesData( slug: "ethereum" from: "2022-01-01T00:00:00Z" to: "2023-01-01T00:00:00Z" aggregation: MIN ) } }
Histogram Metric Example I
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.
Histogram Metric Example
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.