JSON

The JSON datasource allows you to display data from a JSON source in Smartsign.

This makes it possible to integrate data from external systems, APIs, or internally published JSON files into your digital signage content.

JSON (JavaScript Object Notation) is a structured data format commonly used by modern APIs and web services. It represents data using objects and arrays, making it easy to extract individual values and display them on screens.

info

This datasource is intended for users with basic technical knowledge of JSON and JSONPath. While powerful, it may be more complex to configure compared to other datasources.

How it works

When connected, Smartsign retrieves JSON data from the specified source URL and makes it available in the Template Creator using JSONPath expressions.

The JSON data can be fetched either:

• Via the Smartsign server (default, cached for performance and security).
• Or directly from the source by the screen or browser, depending on configuration.

The retrieved data can then be databound to text or image elements in a template. Text elements use JSONPath value, with optional Prefix, Suffix and Parse date (with Date format and Language), or Last update time, which shows when the data was last fetched. Image elements use JSON - Image, or JSON - QR code to show the value as a QR code.

Requirements

To use the JSON datasource, you need:

• An accessible JSON source available over HTTP or HTTPS.
• The JSON source must be encoded in UTF-8
• Basic technical knowledge of JSON and JSONPath.

If you plan to use direct requests, the JSON source must also comply with standard browser security rules (CORS).

Set up the datasource

The first step is to configure your data source with the JSON source you want to use.

In this example we will use a basic URL without any request headers or requirements, but you can read more about them in the configuration details below.

The URL should look like something like this: https://server.example.com/data.json

• Go to Templates -> Datasources, select Add datasource and then Create new.
• Select the JSON datasource.
• Configure the datasource by adding Name, Description and JSON link. If you leave Name empty, it is filled in with the JSON link. Under Users & Groups, choose the users who can add this datasource to a template. Under Custom Icon (optional), you can pick an image from the Media Library as the datasource icon.
• Click Create and verify data connection to see if data can be fetched.
• Once created, you can confirm that data has been fetched.

Datasource is now ready to be used.

Example JSON data

Once the datasource is configured and data can be fetched, it becomes easier to inspect the JSON structure and identify the fields you want to display.

The example below represents a real estate property listing returned from a JSON-based API.

In this case, the following values can be displayed in a template:

• Street address
• Property type
• Price
• Description
• Images

{
  "ads": [
    {
      "estate": {
        "price": "€ 989,000",
        "street": "176 Hillview Sidings St.",
        "town": "Port Vermo, WA3259",
        "description": "Rare opportunity available in the heart of Port Vermo.",
        "property-type": "Single family residence"
      },
      "images": [
        {
          "url": "https://server.example.com/image.jpg"
        }
      ]
    }
  ]
}

Identifying JSONPath expressions

JSONPath is used to tell Smartsign where in a JSON structure a specific value is located. It defines the path from the root of the JSON document to the element you want to display.

JSONPath expressions are case-sensitive and must match property names exactly as they appear in the JSON.

Paths use dot notation, for example: $.ads[0].estate.street

JSONPath notation

Expression	Description
$	The root object or array.
.property	Selects the specified property in a parent object.
[n]	Selects the n:th element from an array. Indexes are 0-based.

Using the example JSON above, the following JSONPath expressions can be used to bind data fields in a template.

JSONPath examples

Field	JSONPath	Result
Street address	$.ads[0].estate.street	176 Hillview Sidings St.
Price	$.ads[0].estate.price	€ 989,000
Property type	$.ads[0].estate.property-type	Single family residence
Description	$.ads[0].estate.description	Property description text
Image	$.ads[0].images[0].url	Image URL

Iterators

When working with lists or arrays in JSON, an index (such as [0]) can be replaced with an iterator expression.

Using an iterator causes the index to start at 0 and automatically increment at a defined interval, allowing multiple items to be shown one at a time.

Example

$.ads[(iterator(20))].estate.price

This means:

• The index starts at 0.
• The displayed item changes every 20 seconds.
• After the last item, the index starts over at 0.
• An offset such as $.ads[(iterator(20)+1)] shows the next item.
• Iterators with a different interval run independently.
• All JSONPath expressions must use the same iterator value to stay synchronized.

To select a specific item instead, use a fixed index:
$.ads[0].estate.price

Create a JSON template

Once the datasource is configured, you can create a JSON template to display the data.

A JSON template can either be created from scratch, or you can download a suitable template from the Marketplace and adapt it to your needs. If you are new to templates, please see the Template Creator guide to learn the basics.

• Create, edit or download templates from the Templates menu.

• Open the template and add text fields and image placeholders for the JSONPath data.

• Bind each element to its corresponding JSONPath expression. Select JSONPath value under Data binding and enter the expression in the JSON Path field. Template Creator loads the connected datasource's data automatically, and the Select JSON Path from test data list helps you identify the correct property when binding fields. It shows No data found when no data was fetched.

  • Street Address $.ads[(iterator(20))].estate.street
  • Property type $.ads[(iterator(20))].estate.property-type
  • Description $.ads[(iterator(20))].estate.description
  • Price $.ads[(iterator(20))].estate.price
  • Image $.ads[(iterator(20))].images[0].url

• Save the template and it can now be used to create a Smart Media to publish on screens.

Technical information

JSON source must be encoded in UTF-8.

Datasource configuration options

JSON link (with GET or POST), Custom request headers and Use direct request are set on the datasource. Data update time, Show progress and Data transformation script are set per template in Template Creator, under Datasource settings for this template, when you connect the datasource or edit its settings.

Setting	Description	Example
JSON link	The complete URL to the JSON file including protocol	https://server.example.com/data.json
HTTP method	Select GET or POST in front of the JSON link field. GET is typically used for static URLs or APIs without a request body. POST can be used for APIs that require parameters or payloads in the request body. It shows a Post body (raw) editor, whose content is sent as JSON.	GET
Data update time	Time in seconds between updates Restrictions (regardless of set value) Server requests: 5 minutes Direct requests: 2 seconds	3600
Show progress	Shows a progress indicator for the rotation of items driven by an iterator.	False
Custom request headers	HTTP header key and value pairs	Key = Authorization Value = Bearer XyzXyzXyzXyz
Use direct request	Enable to request data direct from source instead of proxying through Smartsign Server Server fetched data is cached by the server for 10 minutes for load balancing and security. Direct fetched data is subject to browser security rules https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS	False
Data transformation script	Careful! Programming knowledge required. It's possible to transform/manipulate the data before showing it by providing a script here. The JSON data is available in the variable "input" Moment.js is available to work with date/time. The function must return the data when the transformation is completed.	function(input, moment, smartsign) { // do your transformation here // ex: input['myvar3'] = input['myvar1'] - input['myvar2']; return input; }

Limitations and considerations

• JSON files must be UTF-8 encoded
• JSONPath expressions are case-sensitive
• Direct requests are subject to browser CORS restrictions
• Complex transformations require JavaScript knowledge