Home › APIs › Display Segment

Display Segment

What is a Display Segment?

A Display Segment supports the rendering of digital items onto output hardware. Most typically this takes the form of making an image, Web page or other media visible on a screen.

Overview

The Display Segment API provides 4 resources with a total of 7 methods:

Info
GET / List all information about this display.

 

Scheduling
POST /schedule Request that the specified content is scheduled onto the display.

 

Sensing
GET /sensing List context sources available at a display.
POST /sensing Provide context information to a display.

 

Playback Analytics
GET /playback/ List what is playing at the display now.
POST /playback/subscribe/ Request that subscription record is created in order to provide playback updates to the caller.
POST /playback/unsubscribe/ Request that subscription record is removed.

Each endpoint supports JSON as both the request and response format.

XML formatted requests are only supported by the scheduling resource. XML responses are not supported.

Info

This resource provides one method:

 

Get info

GET / List all information about this display.

Request headers

None specified.

Response

Possible response status codes:

  • 200 — OK.
Response fields:
location object An JSON object describing the location of the display.
sensors string A URL at which information on registered sensors may be acquired.

Examples

request

Accept: application/json

response

200 (OK)
    Content-Type: application/json
{
    "location": {
        "latitude" : "N 50° 43.449",
        "longitude" : "W 002° 03.115",
    },
    "sensors": {
        "url" : "/sensing",
    }
}

Scheduling

This resource provides one method:

 

Request content scheduling

POST /schedule Request that the specified content is scheduled onto the display.

POST parameters

Over JSON
content-item required A URL for a display-ready content-item. The item will be rendered in Web browser.
preferred-duration optional An string value describing the amount of time that the caller considers the optimum duration for the content.
 Over XML

The XML must be a valid Content Descriptor Set (CDS).

Request Headers

None specified.

Response

Possible response status codes:

  • 400 – Bad request. The display could not understand the request.
  • 415 – Unsupported media type. The display does not accept content described in this format (may be the result of scheduling a CDS onto a display that supports only a single item described by a URL).
  • 202 – Accepted. The display has accepted the request.
Response fields:
request-status string A string message that describes the state of the request. Possible values:

  • “rejected” — the request was not accepted
  • “scheduling” — the request is being scheduled

 

Examples

Two examples:

 

Sending a URL to a display for scheduling:

request


Date: Tue, 15 Jun 2013 08:12:31 GMT
Content-Type: application/json
Accept: application/json
{
"content-item" : "http://www.pd-net.org",
"preferred-duration" : "10 seconds",
}

response

202 (Accepted)
Content-Type: application/json
{
"request-status": "scheduling",
}

 

Sending a Content Descriptor Set (CDS) to a display for scheduling:

request

Date: Tue, 15 Jun 2013 08:12:31 GMT
Content-Type: text/xml
Accept: application/json
<?xml version+"1.0" encoding="UTF-8"?>
<content-set name="sample content" type="inline">
    <constraints>
        <scheduling-constraints>
            <playback order="random" avoid-context-switch="false"/>
            <time>
                <between start="00:00:00" end="23:59:00"/>
            </time>
            <day-of-week>
                <between start="monday" end="sunday"/>
            </day-of-week>
            <priority level="medium"/>
        </scheduling-constraints>
    </constraints>
    <content-item content-type="image/jpeg; charset=binary"
                  size="56033 bytes">
        <requires-file>
            <hashes>
                <hash type="md5">
                    894038023f8df9eaa24d2fb635476e4f
                </hash>
            </hashes>
            <sources>
                <uri>http://sample.com/mycontent/image1.jpg</uri>
            </sources>
        </requires-file>
    </content-item>
    <content-item content-type="image/jpeg; charset=binary"
                  size="110181 bytes">
        <requires-file>
            <hashes>
                <hash type="sha1">
                      ecc8e014715b7279baca070d86fd9b5681be9510
                </hash>
            </hashes>
            <sources>
                <uri>http://www.example.com/mypic.jpg</uri>
            </sources>
        </requires-file>
    </content-item>
</content-set>

response

202 (Accepted)
    Content-Type: application/json
{
    "request-status": "scheduling",
}

 

Sensing

This resource provides two methods:

 

List context sources

GET /sensing List context sources available at a display.

Request headers

None specified.

Response

Possible response status codes:

  • 200 — OK.
Response fields

A list of JSON sensor objects each comprised as follows:

sensor-id string A unique string identifier for this sensor.
sensor-type string A string description of the functional class of sensor (e.g. “air temperature”).

 Examples

request

Accept: application/json

response

200 (OK)
    Content-Type: application/json
[
    {
        "sensor-id": "ac:bc:e8:42:f9",
        "sensor-type": "air temperature",
    },
    {
        "sensor-id": "e8:42:f9:ac:bc",
        "sensor-type": "video stream",
    },  
]

 

Provide context data

POST /sensing Provide context information to a display.

Post parameters

sensor-id required The unique string identifier for this sensor.
sensor-type optional A string description of the functional class of sensor (e.g. “air temperature”). MUST be sent with the first message sent by a sensor, optional thereafter.
data optional* The sensor reading.
data-source optional* A URI from which the data can be read.

* Note that EITHER “data” OR “data-source” is required.

Request headers

None specified.

Response

Possible response status codes:

  • 200 — OK.

Examples

Two examples:

 

Send a simple data value to a display

request

Date: Tue, 15 Jun 2013 08:12:31 GMT
Content-Type: application/json
Accept: application/json
{
    "data": 23.2,
    "sensor-id": "ac:bc:e8:42:f9",
    "sensor-type": "air temperature",
}

response

200 (OK)
    Content-Type: application/json
{}

 

Send the source of a video feed or similar to a display

request

Date: Tue, 15 Jun 2013 08:12:31 GMT
Content-Type: application/json
Accept: application/json
{
    "data-source": "rtsp://example.com:1234",
    "sensor-id": "e8:42:f9:ac:bc",
    "sensor-type": "video stream",
}

response

200 (OK)
    Content-Type: application/json
{}

 

Playback Analytics

This resource provides three methods:

List currently playing content item

GET /playback/ List what is playing at the display now.

Documentation coming soon…

Subscribe to playback notifications

POST /playback/subscribe/ Request that subscription record is created in order to provide playback updates to the caller.
POST /playback/unsubscribe/ Request that subscription record is removed.

POST parameters

subscriber-uri string The URI to which playback updates should be posted.

Request headers

None specified.

Response

Possible response status codes:

  • 201 — Created.

Examples

request

Content-Type: application/json
Accept: application/json
{
    "subscriber-uri": "http://pd-logger.pd-net.org/api/logs/pd-display-1/",
}

response

201 (Created)
{
}

Unsubscribe from playback notifications

POST /playback/unsubscribe/ Request that subscription record is removed.

POST parameters

subscriber-uri string The subscriber-uri sent in the original subscribe call.

Request headers

None specified.

Response

Possible response status codes:

  • 200 — OK.

Examples

request

Content-Type: application/json
Accept: application/json
{
    "subscriber-uri": "http://pd-logger.pd-net.org/api/logs/pd-display-1/",
}

response

200 (OK)
{
}