Guides‎ > ‎

HTTP API Documentation

Version 2.0.6, updated 2015-12-01

The wywy HTTP-API is an "all purpose" custom application interface between the wywy automated content recognition system and any third party service.



Introduction

Uses

The wywy HTTP-API is intended for use when integrating with third parties requiring flexibility of integration with wywy commercial airing data.


Examples of uses are:

  • websites and web services with specific custom needs

  • real-time collection of data for in-house business intelligence software

  • DSP, DMP and SSP integrations for real-time advertising solutions

Airing Data

The wywy HTTP-API will always provide the most basic information about a commercial that has been detected:

  • name and ID of the commercial (provided on delivery of TV creatives)

  • name and ID of the channel

  • timestamp of the recognition in coordinated universal time (UTC)

Customization

The wywy HTTP-API can be customized to pass other parameters and values depending on case by case requirements. Examples could include:

  • the duration of the commercial

  • the campaign or creative ID for ad delivery

  • the commercial end time for business intelligence tools

Integration Steps and Time to Implement

The wywy HTTP-API requires that the receiving third party develop and provide an HTTP endpoint. Once this step is completed, and the TV creatives are supplied to wywy, integration and testing can be completed within a few business days.


Documentation

Whenever the target commercial is aired on a monitored broadcaster wywy will send an HTTP-request with information about the airing to a predefined URL. This information can be used for data analysis or making changes to websites in real time.


The endpoint at the specified customer URL must be able to accept and handle data provided via the HTTP request.

Required Information

In order to set up the handler, the following information must be provided by customers:


Required Information

Description

Endpoint URL

URL of customer endpoint to be called by wywy upon commercial recognition

HTTP Method

HTTP method of the request

HTTP Headers

Headers required to call the endpoint

Payload format

Format of the payload: JSON, form, ...


Supported HTTP Methods

The following HTTP methods are supported to communicate with the customer endpoint:


HTTP Method

Description

GET

name/value pairs are sent in the URL of a GET request

POST

name/value pairs are sent in the HTTP message body of a POST request

Data Format

With GET, parameters are sent url encoded as a query string (name=value pairs) in the URL of the HTTP request.


With POST, the parameters will be sent using application/json as Content-Type in the payload of the HTTP request.


Default Parameters

Default parameters that are always* sent upon commercial recognition:


Parameter Name

Value Description

commercialID

wywy-internal ID of detected commercial

customerID

wywy-internal ID of customer

timestamp

unix timestamp (UTC) of commercial detection

channelName

name of channel, where commercial was detected

channelID

wywy-internal ID of channel, where commercial was detected

commercialName

name of detected commercial, provided with creative at start of flight


Broadcast Area Parameters

If required, wywy can provide the broadcast area for the detected channel.


Parameter Name

Value Description

broadcast_area_type

designates the information level for the area; country, state, dma

broadcast_area

JSON array of area values

Additional Custom Parameters

If required, additional parameters can be specified to provide custom information, such as a security token.


Parameter Name (Examples)

Description

securityToken

pre-shared secret

Expected Return Values

The handler decides based on the HTTP status code if the request was successful or not.

Success

Every HTTP status code within 2xx (200 OK, 201 Created, ...) will be treated as a successful delivery.


Any other response will alert wywy to verify the request.

Security

In order to secure the endpoint, it is recommended to add an additional parameter, such as a security token in the form of a pre-shared secret.


Example call with one additional parameter in JSON format


POST / HTTP/1.1
Host: example.org
Accept: */*
Content-Type: application/json

{

 "timestamp": 1234567890,

 "channelID": 12,

 "customerID": 123456,

 "commercialID": 1234567,

 "channelName": "Channel",

 "commercialName": "Commercial"

 "additionalParameter1": "additional value"

}


HTTP/1.0 200 OK                                                                                                                                                  
Content-Type: application/json; charset=utf-8
Content-Length: 0
Date: Fri, 04 Jul 2014 12:49:10 GMT


Example call with broadcast area in JSON format


POST / HTTP/1.1
Host: example.org
Accept: */*
Content-Type: application/json

{

"broadcast_area_type": "state",

"broadcast_area": [

"US-AZ",

"US-CA",

"US-CO",

"US-NV",

"US-NM"

]

 "timestamp": 1234567890,

 "channelID": 12,

 "customerID": 123456,

 "commercialID": 1234567,

 "channelName": "Channel",

 "commercialName": "Commercial"

 "additionalParameter1": "additional value"

}


HTTP/1.0 200 OK                                                                                                                                                  
Content-Type: application/json; charset=utf-8
Content-Length: 0
Date: Fri, 04 Jul 2014 12:49:10 GMT

Example call with pre-shared token in header


POST / HTTP/1.1
Host: example.org
Accept: */*
Content-Type: application/json

Authorization: secureToken

{

 "timestamp": 1234567890,

 "channelID": 12,

 "customerID": 123456,

 "commercialID": 1234567,

 "channelName": "Channel",

 "commercialName": "Commercial"

}


HTTP/1.0 200 OK                                                                                                                                                  
Content-Type: application/json; charset=utf-8
Content-Length: 0
Date: Fri, 04 Jul 2014 12:49:10 GMT


Comments