Skip to main content

JSON Data Source in Grafana

Introduction​

The JSON data source is a powerful feature in Grafana that allows you to connect to and visualize data from external REST APIs that return JSON. This data source is particularly useful when you need to integrate data that isn't available through traditional database systems or when you want to visualize data from third-party services without setting up complex data pipelines.

In this guide, you'll learn how to configure and use the JSON data source in Grafana to create dynamic dashboards from external API endpoints.

Understanding JSON Data Sources​

JSON (JavaScript Object Notation) is a lightweight data interchange format that's easy for humans to read and write and easy for machines to parse and generate. Many web services and APIs use JSON as their standard response format.

Grafana's JSON data source works by:

  1. Making HTTP requests to API endpoints
  2. Parsing the returned JSON data
  3. Transforming this data into a format suitable for visualization
  4. Refreshing this data periodically or on-demand

Prerequisites​

Before diving into JSON data sources, make sure you have:

  • A running Grafana instance (version 7.0 or later recommended)
  • Access to a JSON API endpoint for testing
  • Basic understanding of HTTP requests and JSON format

Installing the JSON API Plugin​

The JSON data source is available as a plugin in Grafana. To install it:

  1. Navigate to Configuration → Plugins in your Grafana instance
  2. Search for "JSON API"
  3. Click on the plugin and select "Install"

Alternatively, you can install it via the CLI:

bash
grafana-cli plugins install simpod-json-datasource

After installation, restart your Grafana server if required.

Configuring a JSON Data Source​

Let's set up a JSON data source step by step:

Step 1: Add the data source​

  1. Go to Configuration → Data Sources
  2. Click "Add data source"
  3. Search for "JSON API" and select it

Step 2: Configure basic settings​

Fill in the following fields:

Name: My JSON API
URL: https://api.example.com/data
Access: Server (default)

Step 3: Configure authentication (if required)​

If your API requires authentication, you can set:

  • HTTP headers (for API keys or tokens)
  • Basic authentication
  • Custom authentication methods

For example, to add an API key:

Header: Authorization
Value: Bearer your-api-token-here

Step 4: Configure query parameters​

You can set default query parameters that will be sent with every request:

Parameter: limit
Value: 100

Step 5: Test and save​

Click "Save & Test" to verify that Grafana can connect to your API endpoint.

Creating Queries with JSON Data Source​

Once your data source is configured, you can create queries to fetch and visualize data.

Basic query structure​

In a dashboard panel, select your JSON data source and configure a query:

json
{
  "endpoint": "/users",
  "method": "GET",
  "parameters": {
    "status": "active"
  }
}

Handling nested JSON​

If your API returns nested JSON, you can specify a path to the data you want to visualize:

json
{
  "endpoint": "/statistics",
  "method": "GET",
  "jsonPath": "$.data.metrics[*]"
}

The jsonPath field uses JSONPath syntax to extract specific data from complex JSON structures.

Practical Example: Weather Dashboard​

Let's create a practical example using a public weather API.

Step 1: Configure the data source​

Name: Weather API
URL: https://api.weatherapi.com/v1
Access: Server

Add your API key in the headers:

Header: key
Value: your-api-key-here

Step 2: Create a temperature panel​

  1. Create a new dashboard and add a Graph panel
  2. Select the Weather API data source
  3. Configure the query:
json
{
  "endpoint": "/forecast.json",
  "method": "GET",
  "parameters": {
    "q": "London",
    "days": "7"
  },
  "jsonPath": "$.forecast.forecastday[*]"
}
  1. In the "Fields" section, map the data:
    • Time field: date
    • Metric field: day.avgtemp_c

Step 3: Add variables for dynamic locations​

  1. Go to Dashboard settings → Variables

  2. Add a new variable:

    • Name: location
    • Type: Text box
    • Default value: London

  3. Update your query to use this variable:

json
{
  "endpoint": "/forecast.json",
  "method": "GET",
  "parameters": {
    "q": "$location",
    "days": "7"
  },
  "jsonPath": "$.forecast.forecastday[*]"
}

Now your dashboard will show weather data for any location entered in the variable.

Transforming JSON Data​

Sometimes the JSON data doesn't come in a format that's immediately usable by Grafana. Here's how to transform it:

Using JSONPath​

JSONPath is a query language for JSON, similar to XPath for XML:

$.store.book[*].author    // All authors of all books in the store
$.store.book[0].title     // Title of the first book
$.store.book[?(@.price < 10)].title  // Titles of books less than $10

Using Transformations​

Grafana also offers transformations to reshape your data:

  1. In your panel, go to the "Transform" tab
  2. Add transformations like:
    • Filter by name
    • Organize fields
    • Reduce
    • Join by field

For example, to calculate the average temperature:

  1. Add a "Reduce" transformation
  2. Select "Mean" as the calculation
  3. Choose your temperature field

Advanced Techniques​

Handling Pagination​

Many APIs use pagination to limit response size. You can handle this with:

json
{
  "endpoint": "/users",
  "method": "GET",
  "parameters": {
    "page": "1",
    "per_page": "100"
  }
}

For more advanced pagination, you might need to use a proxy or middleware.

Caching Responses​

To reduce API calls and improve dashboard performance:

  1. Go to the data source configuration
  2. Set "Cache Time To Live" (TTL) to an appropriate value, e.g., 300 seconds

Using Templates​

You can create template queries that return values for dashboard variables:

json
{
  "endpoint": "/regions",
  "method": "GET",
  "jsonPath": "$[*].name"
}

This returns a list of region names that can be used in a dashboard variable.

Troubleshooting​

Common Issues​

  1. CORS errors: If you see CORS errors, you'll need to either:

    • Configure your API to allow Grafana's domain
    • Use the "Server" access mode instead of "Browser"

  2. Authentication failures: Verify your authentication settings and make sure tokens haven't expired.

  3. Data format issues: Use the "Inspector" tab in panel editing to view the raw data returned by your API.

Debugging Tips​

When your panel doesn't display data correctly:

  1. Check the browser console for errors
  2. Use the Panel Inspector to view the raw query response
  3. Verify your JSONPath expression using an online JSONPath tester
  4. Test your API endpoint directly with tools like Postman or curl

Data Refresh and Real-time Updates​

Configuring Refresh Rates​

You can control how often Grafana fetches new data:

  1. Dashboard-level refresh: Set at the top-right of the dashboard
  2. Panel-level refresh: Configure in panel options
  3. Data source-level refresh: Set in the data source configuration

Streaming Data​

For real-time data:

  1. Set a short refresh interval (e.g., 5s)
  2. Consider using Grafana's WebSocket data source plugin for true streaming

graph TD A[API Endpoint] -->|HTTP Request| B[JSON API Data Source] B -->|Parse JSON| C[Data Processing] C -->|JSONPath| D[Data Extraction] D -->|Transformation| E[Visualization] F[Refresh Interval] -->|Trigger| A

Performance Considerations​

When working with JSON APIs, keep in mind:

  1. API rate limits: Most APIs have rate limits. Set appropriate refresh rates to avoid hitting these limits.

  2. Response size: Large JSON responses can slow down dashboard rendering. Use filtering and JSONPath to extract only the data you need.

  3. Caching: Enable caching in your data source settings to reduce API calls.

Summary​

The JSON data source in Grafana is a versatile tool that lets you connect to virtually any REST API and visualize the returned data. By following the steps and examples in this guide, you can:

  • Configure JSON data sources to connect to external APIs
  • Create queries that extract and transform data for visualization
  • Build dynamic dashboards using variables and templates
  • Troubleshoot common issues with JSON data integration

With these skills, you can extend Grafana beyond traditional data sources and integrate data from modern web services and APIs.

Additional Resources​

Exercises​

  1. Connect Grafana to a public API like GitHub, Weather, or Stock data
  2. Create a dashboard that visualizes multiple metrics from the API
  3. Add dashboard variables to make your visualization dynamic
  4. Apply transformations to calculate derived metrics
  5. Configure different refresh rates and observe the impact on performance

If you spot any mistakes on this website, please let me know at [email protected]. I’d greatly appreciate your feedback! :)