Customer Sign In

upLynk

Integration APIs: Ad

Overview

These APIs can be used to get information about ads and ad settings.

/api2/ad/external/get

Retrieves information about one or more third party ads that have been transcoded by upLynk into a format suitable for cross-platform, cross-device playback. The upLynk system contacts ad servers to know what ads to insert into a live or VOD stream. If an ad server replies with an ad that is not in a suitable format, the upLynk system automatically downloads and converts that ad on the fly. This process is automatic and transparent; this API merely provides a way to query the upLynk system about specific third party ads, to see if they are known ads or not, and the use of this API is not required for the above process to function. Additionally, this API can be used to inform the upLynk system about a third party ad URL ahead of time - by default, if it does not have a record for a requested ad, a cloud slicing job will automatically be initiated to process it.

Request parameters
urlslistList of ad media file URLs (e.g. MP4 or FLV HTTP URLs) OR
List of objects with a url, creative_id, and domain e.g. {url:'http://mediafile', domain:'pubads.g.doubleclick.net', creative_id:123456}. Use this option if the ad server will return two differnt URLs for the same media file.
create_missinginteger(Optional) If 0, a missing URL will not result in a cloud slicing job being initiated to process it. Default is 1.
Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
Call('/api2/ad/external/get', urls=['http://uplynk.s3.amazonaws.com/test/Oreo.mp4'])

{
    "ads": [
        {
            "url": "http://uplynk.s3.amazonaws.com/test/Oreo.mp4",
            "asset_id": "b77dded8225a4a08bdccd105b662d4a7",
            "state": "ok",
            "external_id": "oreo_ad",
            "owner_id": "4f59ea65df184a2580ad8fc80d3eaa32"
        }
    ],
    "error": 0
}
Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
Call('/api2/ad/external/get', urls=[{'url':'http://uplynk.s3.amazonaws.com/test/Oreo.mp4', 'domain':'pubads.g.doubleclick.net', 'creative_id':'41138102188'}])
{
    "ads": [
        {
            "asset_id": "bba79da19e9e4a37bd0402643be46a78",
            "creative_id": "41138102188",
            "domain": "doubleclick.net",
            "external_id": "",
            "owner_id": "4f59ea65df184a2580ad8fc80d3eaa32",
            "state": "ok",
            "url": "http://uplynk.s3.amazonaws.com/test/Oreo.mp4"
        }
    ],
    "error": 0
}
Response parameters (inside an 'ads' list in the response)
urlstringThe same URL passed in the request
statestringOne of: not_found (this ad is unknown to upLynk), pending (the system is converting the ad), ok (the system has already successfully converted the ad), error (the system knows about the ad, but cannot convert it)
asset_idstringIf state is ok, the asset GUID
external_idstringIf state is ok, the asset's external ID, if any
owner_idstringIf state is ok, the asset's owning account ID
creative_idstringcreative id passed to API otherwise null
domainstringdomain passed to API otherwise ''

Auto-converted ads belong to an internal upLynk account; playback URLs can be constructed using either the asset ID or the owner and external ID together.