Ad

This endpoint retrieves information about ads and ad settings.

/api2/ad/external/get

Retrieves information about one or more third-party ads that have been transcoded by our service into a format suitable for cross-platform, cross-device playback. Our 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, our system automatically downloads and converts that ad on the fly. This process is automatic and transparent; this API merely provides a way to query our 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 our 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 Parameter	Type	Description
urls	list	List 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_missing	integer	(Optional) If 0, a missing URL will not result in a cloud slicing job being initiated to process it. Default is 1.

Sample request/response:

The Call() function, which is imported from uplynk_api2_auth module, prepares the message body and digital signature.

from uplynk_api2_auth import Call

print(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
}

Sample request/response:

from uplynk_api2_auth import Call

print(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 Parameter (ads list)	Type	Description
url	string	The same URL passed in the request
state	string	One of: not_found (this ad is unknown to our system), 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_id	string	If state is ok, the asset GUID
external_id	string	If state is ok, the asset's external ID, if any
owner_id	string	If state is ok, the asset's user ID.
creative_id	string	creative id passed to API otherwise null
domain	string	domain passed to API otherwise ''

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