Glossary of API Terms

    This glossary provides definitions for terms frequently used throughout our documentation.

    GraphQL-related

    More about all the GraphQL-related terms can be found on the GraphQL documentation website.

    query

    A "query" in the context of GraphQL refers to a read operation. For instance, in the example below, getAccessRestrictions is the query. Essentially, in a GraphQL request, the query is the function that is invoked.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    {
      getAccessRestrictions {
        name
        type
        isRestricted
        restrictedFrom
        restrictedTo
      }
    }

    Run in explorer

    A single GraphQL request can accommodate multiple queries. In the following example, there are two getMetric queries. To avoid name collision in the returned result, each query is given an alias.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    {
      price_usd_min_interval: getMetric(metric: "price_usd") {
        metadata {
          minInterval
        }
      }
      nvt_min_interval: getMetric(metric: "nvt") {
        metadata {
          minInterval
        }
      }
    }

    Run in explorer

    If different queries are used, aliases can be omitted. In the next example, the queries are getMetric and currentUser.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    {
      getMetric(metric: "price_usd") {
        metadata {
          minInterval
        }
      }
      currentUser {
        id
        username
        email
      }
    }

    Run in explorer

    A query can either return the specified result directly or provide a set of fields that the user can choose from.

    Field

    The term refers to a GraphQL field. Fields are used to specify which parts of a complex object should be returned in a query. The following examples demonstrate the use of different fields in the same getMetric query.

    In the first example, the timeseriesData field is used. The datetime and value are also fields. This illustrates that fields can either have arguments or not.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    {
      getMetric(metric: "active_addresses_24h") {
        timeseriesData(
          slug: "ethereum"
          from: "2019-01-01T00:00:00Z"
          to: "2019-01-01T03:00:00Z"
          interval: "30m"
        ) {
          datetime
          value
        }
      }
    }

    Run in explorer

    In the second example, the aggregatedTimeseriesData field is used.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    {
      getMetric(metric: "active_addresses_24h") {
        aggregatedTimeseriesData(
          slug: "ethereum"
          from: "2019-01-01T00:00:00Z"
          to: "2019-01-01T03:00:00Z"
          aggregation: AVG
        )
      }
    }

    Run in explorer

    Santiment-related

    Metric

    In the context of Santiment's API, a metric is a term with a specific meaning. It refers to a set of data points that carry a particular significance. There are two types of metrics: timeseries metrics and histogram metrics.

    Consider the following example where nvt is the metric and getMetric is the query.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    {
      getMetric(metric: "nvt") {
        timeseriesData(
          slug: "santiment"
          from: "2019-01-01T00:00:00Z"
          to: "2019-09-01T00:00:00Z"
          includeIncompleteData: true
          interval: "7d"
        ) {
          datetime
          value
        }
      }
    }

    Run in explorer

    In some instances, the query and the metric are identical. In the next example, historicalBalance is both the query and the metric. This scenario occurs when a query fetches exactly one metric (the metric argument is implicit), unlike getMetric where the metric argument is explicitly passed with the metric argument.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    {
      historicalBalance(
        selector: { slug: "santiment", infrastructure: "ETH" }
        address: "0xA0D8F33Ef9B44DaAE522531DD5E7252962b09207"
        from: "2019-01-01T00:00:00Z"
        to: "2019-09-01T00:00:00Z"
        interval: "30d"
      ) {
        datetime
        balance
      }
    }

    Run in explorer

    Asset

    An asset refers to any cryptocurrency or crypto token that can be associated with a specific price. Examples of assets include Bitcoin, Ethereum, and Santiment tokens. For more detailed information, please visit our glossary on assets.

    Slug

    A slug is a unique string that identifies an asset. You can find the slug of various projects, along with their names, tickers, and other data, by using the allProjects API.

    Interval

    An interval is a representation of time intervals such as 5 minutes, 12 hours, 10 days, or 4 weeks. There are two types of interval representations: fixed time intervals and functions.

    A fixed time interval is a string that begins with a number and is followed by one of these suffixes:

    • s - second
    • m - minute
    • h - hour
    • d - day
    • w - week

    Here are examples of intervals:

    • 5 minutes - 5m
    • 12 hours - 12h
    • 10 days - 10d
    • 4 weeks - 4w

    Note: There is no suffix for specifying months because a month does not contain a fixed number of days.

    The second type of interval representation is through function names. Functions can achieve two main objectives that fixed intervals cannot:

    • Functions can create non-fixed interval ranges, such as months, which can have between 28 and 31 days.
    • Functions can change the alignment. For example, if the requirement is not just 7 days, but also for the time intervals to start on Monday or Sunday.

    The following functions are supported:

    • toStartOfHour
    • toStartOfDay
    • toMonday
    • toStartOfWeek (aligns dates on Sundays)
    • toStartOfMonth
    • toStartOfQuarter
    • toStartOfYear

    Intervals are used when fetching timeseries data. If the raw data is available at 5-minute intervals but you want to fetch it daily, you should provide interval: "1d" as a parameter. In this case, the default aggregation will be applied to all 288 5-minute data points in a day to compute the value for the entire day. The type of aggregation varies based on the metric. In some cases, taking the average or the last value is required (price), while in other cases, taking the sum of all values is necessary (transaction volume), and so on.

    ISO8601

    The API uses the ISO8601 format for date and time. The format is structured as follows: <year>-<month>-<day>T<hour>:<minute>:<second>Z.

    For instance, January 10th, 2019 at 12:34:56 would be represented as 2019-01-10T12:34:56Z.

    API Key

    Your API key is essential for accessing the premium features provided by our API. For more detailed information, please refer to the API Authentication section.