Broadsign Control Real-Time Audience API

The Broadsign Control real-time audience API allows developers to integrate audience data.

There are two main types of requests:

Each request type has a different action macro. Other macros are the same across all request types.

The Real-Time Audience API has two measurement components:

  • The "prediction" component – Broadsign Control Administrator requests the API to provide, in advance of the slot, estimated or expected audience numbers for when this slot will come up. This can be requested up to 35 seconds in advance and it is included in Broadsign Reach ad requests.
  • The "measurement" component – Broadsign Control Administrator requests the API to measure, during playback of a slot, the actual audience numbers. The measurement starts at the beginning of the slot and stops when playback completes. This information is reported with POPs.

The real-time audience bidding protocol is based on HTTP(S) GET requests, issued from Broadsign Control Player with a series of supported macros. The requests are sent typically about 35 seconds before the expected programmatic slot to get the expected audience for bidding purposes.

Sample Request for Real-Time Audience Bidding in Broadsign Reach

Copy 
GET $URL/{{action_name}}?expected_play_time={{expected_play_time}}&frame_id={{frame_id}}&campaign_id={{campaign_id}}&content_id={{content_id}}

The following table lists the supported macros and values for Real-time audience bidding:

Macro Name Substituted Value
{{action_name}} Mandatory field. It will be replaced with the proper internal command.
Common macros for all actions. Substituted values are url-encoded.
{{expected_play_time}} The expected UTC display_time in milliseconds since epoch.
{{frame_id}} The Broadsign Frame ID from which the request originates.
{{campaign_id}} The Broadsign Campaign ID from which the request originates.
{{content_id}} The Broadsign Content ID from which the request originates.
{{content_name}} The name of the Broadsign Content from which the request originates.
{{expected_duration}} The expected duration of the Content in milliseconds.
{{app_name}} "Broadsign Control Player"
{{player_id}} The Broadsign Control Player ID.
{{display_unit_id}} The Broadsign Display Unit ID.
{{external_id}} The Broadsign Display Unit External ID (for external systems).
{{location_code}} The Broadsign Display Unit's location code.
{{latitude}} The Broadsign Display Unit's Latitude.
{{longitude}} The Broadsign Display Unit's Longitude.

URL macros can be used to dynamically transform the URL that is requested by the Broadsign Control Player.

Refer to the third-party HTTP API specification for all mandatory fields.

For example, if the remote url is:

Copy 
"http://localhost:10000/audience/{{action_name}}?frame_id={{frame_id}}&content_name={{content_name}}&player_id={{player_id}}"

and the current internal action is \"start\", fame_id is 33333, player_id is 555 and content_name is \"video\", then the URL requested by the player will be:

Copy 
"http://localhost:10000/audience/start?frame_id=33333&content_name=video&player_id=555\n");

Response Format

Copy 
{
  "audience_pre": {
    "timestamp": 1429789106,
    "utc_offset": 7200,
    "total": 5,
    "metric": "3AI-F0",
    "gender": {male: 2, female: 3, unknown: 0},
    "age": [
      {
        "min": 0,
        "max": 17,
        "count": {male: 1, female: 1, unknown: 0}
      },
      {
        "min": 18,
        "max": 35,
        "count": {male: 1, female: 1, unknown: 0}
      },
      {
        "min": 36,
        "max": 99,
        "count": {male: 0, female: 1, unknown: 0}
      }
    ],
    "states": ["female"]
  }
}

The response is expected to be provided in json encoding with utf-8 charset.

  • timestamp: In milliseconds since epoch and must be in UTC.
  • utc_offset: The offset, in seconds, from UTC to the provided time zone.
  • HTTP responses in the 3XX, 4XX, and 5XX series are logged as an error. Redirects are not followed.
  • On a 200 OK response, the body is expected to be formed as follows:
    • audience_pre: Mandatory response root element
      • total: Mandatory
      • gender array: Optional. If specified, is used for bidding
      • Age ranges: Optional. If provided, used in conjunction with genders for bidding
    • Any other fields in the response are ignored.
    • Any parsing errors, missing mandatory, or malformed attributes will be logged and no real-time audience info will be recorded.

The proof-of-play audience protocol is also based on HTTP(S) GET request, with a series of supported macros. For proof of play, two requests are issued:

  • A “start” request when the ad copy starts playing.
  • A “stop” request when it is done.

Other macros are the same across all request types.

Note: The total number of impressions is cumulative when the players are configured with the statistical audience files per time range. This also applies for the gender and age ranges. See Broadsign POP Log.

Sample Request for Proof-of-Play Audience START

Copy 
GET $URL/{{action_name}}?expected_play_time={{expected_play_time}}&frame_id={{frame_id}}&campaign_id={{campaign_id}}&content_id={{content_id}}

The following are the supported macros and values for proof-of-play audience START.

Macro Name Substituted Value
{{action_name}} "start"
All Common Macros (see Sample Request for Real-Time Audience Bidding in Broadsign Reach).

Response Format to “START”

Copy 
{
  “status” : “ok”
}

The response is expected to be provided in json encoding with utf-8 charset.

  • HTTP responses in the 3XX, 4XX, and 5XX series are logged as an error. Redirects are not followed.
  • On a 200 OK response, the body is expected to be formed as follows:
    • status: Mandatory. If any response other than “ok”, it is logged and ignored.
    • Any other fields in the response are ignored.
    • Any parsing errors, missing mandatory, or malformed attributes will be logged.

Sample Request for Proof-of-Play Audience STOP

Copy 
GET $URL/{{action_name}}?frame_id={{frame_id}}&campaign_id={{campaign_id}}&content_id={{content_id}}

The following are the supported macros and values for proof-of-play audience STOP.

Macro Name Substituted Value
{{action_name}} "stop"
All Common Macros (see Sample Request for Real-Time Audience Bidding in Broadsign Reach).

Response Format to “STOP”

Copy 
{
  "audience_clip": {
    "timestamp": 9,
    "utc_offset": 7200,
    "duration": 3000,
    "total": 5,
    "metric": "3AI-F0"
    "gender": {male: 2, female: 3, unknown: 0},
    "age": [
      {
        "min": 0,
        "max": 17,
        "count": {male: 1, female: 1, unknown: 0}
      },
      {
        "min": 18,
        "max": 35,
        "count": {male: 1, female: 1, unknown: 0}
      },
      {
        "min": 36,
        "max": 99,
        "count": {male: 0, female: 1, unknown: 0}
      }
    ],
    "states": ["female"],
  }
}

The response is expected to be provided in json encoding with utf-8 charset.

  • timestamp: In milliseconds since epoch and ,must be in UTC.
  • utc_offset: The offset from UTC to the provided time zone in seconds.
  • HTTP responses in the 3XX, 4XX, and 5XX series are logged as an error. Redirects are not followed.
  • audience_clip: mandatory response root element.
    • “total: Mandatory. This value is recorded as impressions in the proof-of-play.
    • gender array: Optional. If specified, is used for gender breakdown in the proof-of-play.
    • Age ranges : Optional. if provided, is used for age breakdowns in the proof-of-play.
  • Any other fields in the response are ignored.
  • Any parsing errors, missing mandatory or malformed attributes will be logged and ignored.