Skip to main content

JSON datasource

JSON datasources allow you to fetch and display data from JSON APIs, REST endpoints, or any URL that returns JSON formatted data. The system automatically parses JSON structures and makes the data available to your widgets and templates.

Prerequisites​

Before creating a JSON datasource, ensure you have:

  • A valid JSON API endpoint or URL that returns JSON data
  • Proper network access to the JSON source
  • Understanding of the JSON structure you want to consume
  • Authentication credentials if required by the API

Supported JSON Structures​

The JSON datasource supports various data structures:

Simple Object:

{
  "title": "Weather Update",
  "temperature": "25°C",
  "condition": "Sunny"
}

Array of Objects:

[
  {
    "name": "Product 1",
    "price": "$19.99",
    "stock": 15
  },
  {
    "name": "Product 2",
    "price": "$29.99",
    "stock": 8
  }
]

Nested Structure:

{
  "data": {
    "items": [
      {
        "id": 1,
        "details": {
          "name": "Item 1",
          "category": "Electronics"
        }
      }
    ],
    "metadata": {
      "total": 1,
      "updated": "2024-01-15T10:30:00Z"
    }
  }
}

Create datasource​

Go to Settings > Datasources and open the External Datasources tab. Click Add external datasource, then on the Choose a datasource type screen select JSON.

Basic Configuration​

1. Update Schedule Set how often the datasource updates under Refresh settings: a Simple interval or an Advanced schedule (cron). Learn more: Refresh and caching

2. JSON Endpoint URL In the URL field, enter the JSON API endpoint or URL. The URL must:

  • Return valid JSON content
  • Be accessible from your server
  • Use HTTP or HTTPS protocol
Valid JSON URL Examples
  • https://api.example.com/data.json
  • https://jsonplaceholder.typicode.com/posts
  • https://api.openweathermap.org/data/2.5/weather?q=London&appid=YOUR_API_KEY

Advanced Configuration Options​

3. Advanced settings The caching options are explained in Refresh and caching. Active, Continue refreshing despite errors, Connection settings and shuffling lists (Process and filter data) are explained in Advanced datasource settings.

Authentication​

If the JSON API needs authentication, click Connection settings:

  • For a username and password, turn on Authentication (Basic auth).
  • For an API key or a token, add it under Custom headers (advanced), for example X-API-Key with your key, or Authorization with Bearer <token>.

Learn more: Connection settings

4. Save Configuration Once all settings are configured according to your JSON source requirements, click Save to create the datasource.

Using JSON Data in Widgets​

After creating the JSON datasource, you can bind the data to widgets using dot notation:

  • Simple values: data.title, data.temperature
  • Array elements: data.items[0].name, data.items[1].price
  • Nested objects: data.metadata.total, data.details.category

Common JSON API Types​

REST APIs: Standard HTTP APIs returning JSON responses
Weather APIs: Current conditions, forecasts, alerts
News APIs: Headlines, articles, RSS-to-JSON services
Social Media APIs: Posts, feeds, statistics
E-commerce APIs: Product catalogs, inventory, pricing
Custom Applications: Internal systems, databases via API