Grafana integration example

This example shows how to integrate Exorde API with Grafana. Our goal is to create a dashboard to track the sentiment of Bitcoin and Ethereum.

You can download the dashboard here and import it to quickly get started. Or you can follow the tutorial below to create the dashboard from scratch. All calls made to the Exorde API are explained.

info

As we create the dashboard step by step, we kept is as simple as possible. A more advanced dashboard is available on our GitHub. You can follow the instructions in the README to import it.

The dashboard will look like this:

Access the Exorde API

First, to use the Exorde API, you need to create an account on Exorde developers portal. You'll get 1000 free credits and an API generated on your first login. Keep it safe, you'll need it to authenticate your requests.

Search the IDs of the topics

Before using the Exorde API to query the sentiment of Bitcoin and Ethereum, we need to get the IDs of these topics.

To do so, we can use the List topics endpoint.

First, we need to get the topic id of Bitcoin using the List topics endpoint:

curl \
    --url 'https://api.exorde.io/topics?name=bitcoin' \
    --header "X-Exorde-Api-Version: v1" \
    --header "Accept: application/json" \
    --header "Authorization: Bearer <api-key>"

This will return the list of topics matching the name bitcoin:

{
  "items": [
    {
      "id": 2,
      "name": "0xbitcoin (0xbtc)",
      "categories": [
        { "id": 9, "name": "Cryptocurrency" },
        { "id": 3, "name": "Investing" },
        { "id": 7, "name": "Technology" }
      ]
    },
    // ...
    {
      "id": 366,
      "name": "Bitcoin (BTC)",
      "categories": [
        { "id": 9, "name": "Cryptocurrency" },
        { "id": 6, "name": "Economy" },
        { "id": 3, "name": "Investing" },
        { "id": 7, "name": "Technology" }
      ]
    }
    // ...
  ],
  "pagination": {
    "next": "http://api.exorde.io/topics?name=bitcoin&paginationCursor=eyJhZnRlciI6eyJuYW1lIjoiQml0Y29pbiBIYWx2aW5nIn19",
    "self": "http://api.exorde.io/topics?name=bitcoin"
  },
  "status": { "cost": 1 }
}

There are several topics matching the name bitcoin. We can see that the topic we are looking for is the one with the id 366.

Now, we can get the topic id of Ethereum using the same endpoint, the id is 1143.

info

As you can see, a name is not enough to identify a topic. Several topics can share the same name, for example "apple" can refer to the company or the fruit. That's why we must first search for a topic using its name and then use its id to get the related data.

This is a common pattern in the Exorde API. You can use the List topics endpoint to search for a topic using its name, and then use the topic id to get the related data. The topic selection is not automated because it requires human intelligence, it's a one-time process that you can do manually when integrating the API in your application.

Run Grafana locally

If you don't have a Grafana instance, you can run one locally using a docker container, listening on port 3000:

docker run -d -p 3000:3000 \
  --env GF_INSTALL_PLUGINS=magnesium-wordcloud-panel,marcusolsson-json-datasource \
  grafana/grafana

Grafana is available at http://localhost:3000. The default username and password are both admin.

note

If you already have a Grafana instance, ensure that the Word cloud and JSON API plugins are installed.

Connect Grafana to the Exorde API

Add a JSON API connector, to enable Grafana to query the Exorde API:

Go to Main menu > Connections > Data sources.
Click on Add data source.
Type JSON API in the search bar.
Click on JSON API data source.
Fill the form:
- Name: Exorde API
- URL: https://api.exorde.io
- Authentication: No Authentication
- HTTP Headers: add the following headers:
  - Accept: application/json
  - X-Exorde-Api-Version: v1
  - Authorization: Bearer <YOUR_API_KEY>

Click on Save & Test to validate the connection.

Import the dashboard

note

If you want to create the dashboard from scratch, you can skip this step and go to the next section.

To import the dashboard:

Copy the content of the dashboard from here.
Go to Main menu > Dashboards > New > Import.
Paste the content of the dashboard in the Import via dashboard JSON model field.
Click on Load.
Select the Exorde API data source.
Click on Import.

Create a dashboard

Create a new dashboard to explore the Exorde API:

Go to Main menu > Dashboards > New > New dashboard.
Go to Dashboards settings (gear icon).
Rename the dashboard to Exorde API demo.
Set the Graph tooltip to Shared Tooltip.

Now, from the Variables menu, add a variable to select the topic:

Type: Custom
Name: topic
Label: Topic
Description: Topic to query.
Show on dashboard: Label and value
Custom options: Bitcoin : 366,Ethereum : 1143

note

The topic variable contains a mapping between the topic name and its ID, as returned by the List topics endpoint.

That's it, now save the dashboard to apply the changes.

The dashboard is configured, now we can add some visualizations to track the sentiment of Bitcoin and Ethereum:

total volume of posts
average sentiment
trending keywords related to the topic
sentiment over time
volume of posts over time
proportion of positive, negative and neutral posts

Total volume of posts

The goal of this visualization is to display the total volume of posts collected for the selected topic, in a big number. We'll use the Get volume endpoint to get the total volume of posts between the selected dates.

Click on Add > Visualization.
Select the data source Exorde API.
Select the Stat visualization.
Configure the query on Query tab:
1. On the Path tab, set the path to /volume.
2. On the Params tab, set the following parameters:
  - topicId: $topic
  - startDate: ${__from:date:iso}
  - endDate: ${__to:date:iso}
On the Fields tab, set the following fields:
- $.volume.postsCount (type: Number)
Configure the panel:

Panel options:
- Title: Post volume
- Description: The volume of posts collected.
- Transparent background: true
Standard options:
- Color scheme: Single color (blue)

Click on Apply to apply the changes.

Here is a summary of the configuration:

Average sentiment

The goal of this visualization is to display the average sentiment of posts collected for the selected topic, in a big number. We'll use the Get sentiment endpoint to get the average sentiment of posts between the selected dates.

Click on Add > Visualization.
Select the Stat visualization.
Configure the query on Query tab:
1. On the Path tab, set the path to /sentiment.
2. On the Params tab, set the following parameters:
  - topicId: $topic
  - startDate: ${__from:date:iso}
  - endDate: ${__to:date:iso}
On the Fields tab, set the following fields:
- $.sentiment.sentiment (type: Number)
Configure the panel:

Panel options:
- Title: Social sentiment
- Description: From -1 (negative) to 1 (positive).
- Transparent background: true
Standard options:
- Min: -1
- Max: 1
- Color scheme: Red-Yellow-Green (by value)

Click on Apply to apply the changes.

Here a summary of the configuration:

The goal of this visualization is to display the most frequent keywords related to the selected topic. We'll use the Get trending keywords endpoint to get the most frequent keywords related to the topic between the selected dates. We'll use the Word cloud plugin to display the keywords, and we limit the number of keywords to 10.

Click on Add > Visualization.
Select the Word cloud visualization.
Configure the query on Query tab:
1. On the Path tab, set the path to /keywords/trending.
2. On the Params tab, set the following parameters:
  - topicId: $topic
  - startDate: ${__from:date:iso}
  - endDate: ${__to:date:iso}
  - limit: 10
On the Fields tab, set the following fields:
- $.trendingKeywords.keywords[*].count (type: Number)
- $.trendingKeywords.keywords[*].label (type: Number)
Configure the panel:

Panel options:
- Title: Trending keywords
- Description: Most frequent keywords related to the selected topic.
- Transparent background: true

Click on Apply to apply the changes.

Here is a summary of the configuration:

Sentiment over time

The goal of this visualization is to display the sentiment of posts collected for the selected topic over time. We'll use the Get sentiment history endpoint to get the sentiment of posts collected for the selected topic over time between the selected dates. We'll use the Time series visualization to display the sentiment over time. We limit the number of data points to 1000 (the maximum allowed by the API) and the interval to 15 minutes. So the chart will contain up to 1000 data points, one every 15 minutes.

Click on Add > Visualization.
Select the Time series visualization.
Configure the query on Query tab:
1. On the Path tab, set the path to /sentiment/history.
2. On the Params tab, set the following parameters:
  - topicId: $topic
  - startDate: ${__from:date:iso}
  - endDate: ${__to:date:iso}
  - limit: 1000
  - interval: 15
On the Fields tab, set the following fields:
- $.items[*].startDate (type: Time)
- $.items[*].sentiment (type: Number)
Configure the panel:

Panel options:
- Title: Social sentiment over time
- Description: The sentiment (from -1 most negative to 1 most positive) and the volume of posts collected.
Legend:
- Mode: Table
- Values: Variance, Mean, Min, Max
Graph style:
- Style: Lines
- Line interpolation: Smooth
- Line width: 3
- Gradient mode: Scheme
- Point size: 1
Standard options:
- Min: -1
- Max: 1
- Color scheme: Red-Yellow-Green (by value)

Click on Apply to apply the changes.

Here is a summary of the configuration:

Volume of posts over time

The goal of this visualization is to display the volume of posts collected for the selected topic over time. We'll use the Get volume history endpoint to get the volume of posts collected for the selected topic over time between the selected dates. We'll use the Time series visualization to display the volume over time. We limit the number of data points to 1000 (the maximum allowed by the API) and the interval to 15 minutes. So the chart will contain up to 1000 data points, one every 15 minutes.

Click on Add > Visualization.
Select the Time series visualization.
Configure the query on Query tab:
1. On the Path tab, set the path to /volume/history.
2. On the Params tab, set the following parameters:
  - topicId: $topic
  - startDate: ${__from:date:iso}
  - endDate: ${__to:date:iso}
  - limit: 1000
  - interval: 15
On the Fields tab, set the following fields:
- $.items[*].startDate (type: Time)
- $.items[*].postsCount (type: Number)
Configure the panel:

Panel options:
- Title: Post volume over time
- Description: The volume of posts collected.
Legend:
- Mode: Table
- Values: Variance, Mean, Min, Max
Graph style:
- Style: Lines
- Line interpolation: Smooth
- Line width: 0
- Fill opacity: 100
- Gradient mode: Opacity
- Point size: 1
Standard options:
- Min: 0
- Color scheme: Single color (blue)

Click on Apply to apply the changes.

Here is a summary of the configuration:

Proportion of positive, negative and neutral posts

The goal of this visualization is to display the proportion of positive, negative and neutral posts collected for the selected topic over time. We'll use the Get sentiment history endpoint to get the distribution of posts' sentiment for the selected topic over time between the selected dates. We'll use the Time series visualization to display the sentiment distribution over time, staking 3 series. We limit the number of data points to 1000 (the maximum allowed by the API) and the interval to 15 minutes. So the chart will contain up to 1000 data points, one every 15 minutes.

Click on Add > Visualization.
Select the Time series visualization.
Configure the query on Query tab:
1. On the Path tab, set the path to /sentiment/history.
2. On the Params tab, set the following parameters:
  - topicId: $topic
  - startDate: ${__from:date:iso}
  - endDate: ${__to:date:iso}
  - limit: 1000
  - interval: 15
On the Fields tab, set the following fields:
- $.items[*].startDate (type: Time)
- $.items[*].percentageNegativePosts (type: Number)
- $.items[*].percentageNeutralPosts (type: Number)
- $.items[*].percentagePositivePosts (type: Number)
Configure the panel:

Panel options:
- Title: Sentiment distribution
- Description: The distribution of positive, negative and neutral posts.
Tooltip:
- Tooltip Mode: All
Graph style:
- Style: Lines
- Line interpolation: Smooth
- Line width: 3
- Fill opacity: 25
- Gradient mode: None
- Point size: 1
- Stack series: 100%
Override 1:
- Fields with name: Percentage of negative posts
- Standard options > Color scheme: Single color (red)
Override 2:
- Fields with name: Percentage of neutral posts
- Standard options > Color scheme: Single color (yellow)
Override 3:
- Fields with name: Percentage of positive posts
- Standard options > Color scheme: Single color (green)

Click on Apply to apply the changes.

Here is a summary of the configuration:

Rearrange the panels

Now that we have added all the visualizations, we can rearrange the panels to make the dashboard more readable, like this:

Grafana integration example

Access the Exorde API​

Search the IDs of the topics​

Run Grafana locally​

Connect Grafana to the Exorde API​

Import the dashboard​

Create a dashboard​

Total volume of posts​

Average sentiment​

Trending keywords​

Sentiment over time​

Volume of posts over time​

Proportion of positive, negative and neutral posts​

Rearrange the panels​

Access the Exorde API

Search the IDs of the topics

Run Grafana locally

Connect Grafana to the Exorde API

Import the dashboard

Create a dashboard

Total volume of posts

Average sentiment

Trending keywords

Sentiment over time

Volume of posts over time

Proportion of positive, negative and neutral posts

Rearrange the panels