Accessing the API

• Overview
• Access the API
  • Live API Explorer
  • curl
  • Santiment-provided Python library
  • Programming language of your choice
• Authentication
• Errors

Overview

Santiment API utilizes GraphQL. The reasons for choosing GraphQL over REST include:

• It allows for precise data requests and easy batching of requests. This effectively addresses the problems of underfetching and overfetching data. For instance, why fetch all 20+ fields of a project when only its name is required?

• The request outlines the format of the response. This eliminates the need to guess what data the result contains and how to parse it.

• It provides an easy, ready-to-use method to explore our API via our Live Explorer.

Access the API

Please note that some metrics may not be freely available or may have restrictions, such as limited historical and real-time data. To explore these metrics without restrictions, use the slug santiment.

There are several methods to retrieve data from Santiment's API:

Live API Explorer

The Live API Explorer allows you to run queries directly from your browser. You can access the explorer at the following link: https://api.santiment.net/graphiql.

Here's an example of how to run a query and view the results directly in your browser:

GraphQL Request fetching transaction volume

We also offer an advanced version of the GraphiQL that is particularly useful for API users: https://api.santiment.net/graphiql_advanced. This version allows you to add HTTP headers, which can be used to include an API key and authenticate your requests. To do this, simply add the following header: Authorization: Apikey <YOUR_OWN_API_KEY>.

curl

The following GraphQL request will be passed as the body of the request:

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  getMetric(metric: "dev_activity") {
    timeseriesData(
      slug: "ethereum"
      from: "2020-02-10T07:00:00Z"
      to: "2020-03-10T07:00:00Z"
      interval: "1w"
    ) {
      datetime
      value
    }
  }
}

You can use the curl tool to retrieve the development activity of Ethereum. Copy and paste the following curl request into your console:

1
2
3
4
5
curl \
-X POST \
-H "Content-Type: application/graphql" \
--data '
{ getMetric(metric: "dev_activity"){ timeseriesData( slug: "ethereum" from: "2020-02-10T07:00:00Z" to: "2020-03-10T07:00:00Z" interval: "1w"){ datetime value } } }' https://api.santiment.net/graphql

The response should look similar to this:

1
{"data":{"getMetric":{"timeseriesData":[{"datetime":"2020-02-13T00:00:00Z","value":1281.0},{"datetime":"2020-02-20T00:00:00Z","value":1115.0},{"datetime":"2020-02-27T00:00:00Z","value":952.0},{"datetime":"2020-03-05T00:00:00Z","value":605.0}]}}}

If you have the jq tool installed, you can use it to visualize the response more effectively:

1
2
3
4
5
6
curl \
-X POST \
-H "Content-Type: application/graphql" \
--data '
{ getMetric(metric: "dev_activity"){ timeseriesData( slug: "ethereum" from: "2020-02-10T07:00:00Z" to: "2020-03-10T07:00:00Z" interval: "1w"){ datetime value } } }' https://api.santiment.net/graphql \
| jq .data.getMetric.timeseriesData

The output should look like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
[
  {
    "datetime": "2020-02-13T00:00:00Z",
    "value": 1281
  },
  {
    "datetime": "2020-02-20T00:00:00Z",
    "value": 1115
  },
  {
    "datetime": "2020-02-27T00:00:00Z",
    "value": 952
  },
  {
    "datetime": "2020-03-05T00:00:00Z",
    "value": 605
  }
]

Santiment-provided Python library

Santiment offers a Python wrapper for the GraphQL API, known as sanpy. You can find the documentation and installation instructions for this library here.

You can install sanpy using pip with the following command:

1
pip install sanpy

To fetch Ethereum development activity data using this library, use the following code:

1
2
3
4
5
6
san.get(
  "dev_activity/ethereum",
  from_date="2019-01-01T00:00:00Z",
  to_date="2019-01-07T00:00:00Z",
  interval="1d"
)

The result will be a pandas dataframe, as shown below:

1
2
3
4
5
6
7
datetime                    activity
2019-01-01 00:00:00+00:00       44.0
2019-01-02 00:00:00+00:00       89.0
2019-01-03 00:00:00+00:00      140.0
2019-01-04 00:00:00+00:00      177.0
2019-01-05 00:00:00+00:00       46.0
2019-01-06 00:00:00+00:00       22.0

Programming language of your choice

In the san-sdk repository, you can find examples of how to query the API using various programming languages. Here are some examples:

• R
• Ruby
• Elixir
• Javascript Example #1: This example shows how to plot Daily Active Addresses with Highchart.
• Javascript Example #2: This example demonstrates how to compute the combined ETH balance of all projects.

Authentication

Certain APIs necessitate a valid API key, which must be linked to an account with a paid subscription to access additional data. You can generate your API key on your Account Settings page.

After generating your API key, you need to include it as an additional HTTP header in the format Authorization: Apikey <YOUR_OWN_API_KEY>.

Here is an example of how to do this using curl:

1
2
3
4
5
6
curl \
  -X POST \
  -H "Content-Type: application/graphql" \
  -H "Authorization: Apikey <YOUR_OWN_API_KEY>"\
  --data '<YOUR_OWN_QUERY>' \
  https://api.santiment.net/graphql

Errors

If there's an issue with your request, the API will return an error. Regardless of the error, the API should always return a status code of 200. The error response will include a description of the problem that occurred.

For instance, if an invalid query is passed to the API, the following will occur:

1
2
3
4
5
6
7
8
9
10
11
12
13
$ curl \
  -X POST \
  -H "Content-Type: application/graphql" \
  --data '{transactionVolume' \
  https://api.santiment.net/graphql | jq .

{
  "errors": [
    {
      "message": "An unknown error occurred during parsing: no function clause matching in Absinthe.Phase.Parse.format_raw_parse_error/1"
    }
  ]
}

If your query is missing an argument, the error response will describe this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
$ curl \
  -X POST \
  -H "Content-Type: application/graphql" \
  --data '{ transactionVolume(slug:"santiment", from:"2019-01-01T00:00:00Z") { datetime transactionVolume }}' \
  https://api.santiment.net/graphql | jq .

{
  "errors": [
    {
      "locations": [
        {
          "column": 3,
          "line": 1
        }
      ],
      "message": "In argument \"to\": Expected type \"DateTime!\", found null."
    }
  ]
}

If the query does not return a status code of 200, it indicates a different issue. Here are some possibilities:

• 429 - You're being rate-limited. Reduce the number of requests you're making.
• 5xx - An internal server error has occurred. Please let us know in the support channel on our Discord server.