Ad Serving API

The Ad Serving API provides media owners with a RESTful interface over HTTP. Using this API, you can request ads, receive ad responses, and report back proof of plays (PoPs). You can also use the Creative Caching endpoint to request and cache creatives in advance in case of poor internet connectivity (see Creative Caching endpoint for more information).

The following diagram shows a simplified version of what a native integration could look like.

Integrations_-_Native_integration.png

View the endpoint, parameters, and JSON examples of each request and response:

To understand the HTTP status codes for each request, see Status codes and errors.

To request an ad

Make a call to the API to request for an ad. An ad request lets Vistar know that there is an opening where an ad can be served.

URL

Staging Production
POST https://sandbox-api.vistarmedia.com/api/v1/get_ad/json

Request body parameters

Name Description Type Required Notes
network_id The ID of the network you are making a request for. This is one of two fields used to authenticate someone using the Ad Serving API. String Required See API credentials to learn how to retrieve these credentials.
api_key The unique key for the network. This is one of two fields used to authenticate a user using the Ad Serving API. String  Required See API credentials to learn how to retrieve these credentials.
device_id Any string, including an empty string, as long as it is unique for each network_id. Max length 64 characters. String Required If you have multiple devices shared by your venue, this field can be used as an identifier for each device. It is not applied in any way for the basis of ad serving.
venue_id

This is the user-defined ID of the venue that is making the request. This will be used to look up the venue’s location, CPM, and impression data.

The following list outlines the only supported characters for the venue ID: a-z, A-Z, 0-9, -, _

String Required* *While an ad request can still be valid without a venue ID as long as you pass a valid lat/long, we highly recommend that you pass the venue_id because this allows you to track venue-level reporting.
display_time

Time in the future at which you expect to show the ad in UTC epoch seconds.

Example value: 1354576345

Int64 Required Due to the nature of programmatic ads, the display time should be as close as possible in real time to the ad request.
device_attribute

A single attribute bound to a display. Known attributes of a device should be sent as a repeated field in the ad request.

There is no type information associated with the values, so richer data types should either sent with their obvious string representation or omitted.

Device
Attribute
Optional Device attributes can be used as a form of targeting where direct campaigns only deliver to venues whose attributes match the specified values. See custom targeting for more detail.
name The name of the device attribute. String Required* *This is required only if the device_attribute field is added to the request.
value The value of the device attribute. String Required* *This is required only if the device_attribute field is added to the request.
display_area A display area describes a section of a screen that may show an ad. This may be the absolute resolution of the display or the resolution of some subsection of the screen. Display
Area
Required Each request needs to have at least one display area. If you have multiple sections of your screen that need ads at the same time, you can pass a request for each one.
id The id field is important in the context of a request with multiple display areas, as each returned advertisement will have a display_area_id corresponding to the display area ID you requested. String Required  
width

The width, in pixels, of the section of a screen.

Example value: 640

Int32 Required If you have audio-only inventory (no physical screens), this parameter must be 0 or omitted.
height

The height, in pixels, of the section of a screen.

Example value: 480

Int32 Required If you have audio-only inventory (no physical screens), this parameter must be 0 or omitted.
allow_audio

Indicates whether the audio is allowed.

Example value: False

Boolean Optional* *If you have audio-only inventory (no physical screens), this parameter must be set to True.
supported_
media

The valid mime types and encodings supported by the device.

Example Values:

  • "application/x-shockwave-dynamic-flash"
  • "application/x-shockwave-flash"
  • "audio/aac"
  • "audio/mpeg"
  • "image/jpeg"
  • "image/png"
  • "video/mp4"
  • "video/mpeg"
  • "video/mpg"
  • "video/quicktime"
  • “video/webm"
  • "video/x-flv"
  • "video/x-ms-wmv"
  • "video/x-msvideo"

Note: "image/jpg" is not an acceptable MIME type.

String Required If you have audio-only inventory (no physical screens), set this parameter to one or both of the following mime types:
  • "audio/aac"
  • "audio/mpeg"
 
min_duration Minimum acceptable asset duration, in seconds. Int32 Required* *While this is an optional field, we strongly recommend that you pass it in your ad request to ensure that each creative returned to your screens runs for the desired amount of time.
max_duration Maximum acceptable asset duration, in seconds. Int32 Required* *While this is an optional field, we strongly recommend that you pass it in your ad request to ensure that each creative returned to your screens runs for the desired amount of time.
order_id

Specifying the contract number of an order in this field will only return advertisements for that order.

Note that there is a limit of 22 characters.

String Optional  
max_file_
size_bytes

Maximum file size (in bytes) that is supported by the device.

Example value: 3500000

Int32 Optional  
static_duration

Supported duration (in seconds) for static creatives. All static assets will be returned with the duration set to this value.

Example values: 10

Int32 Required* *While this is an optional field, we strongly recommend that you pass it in your ad request to ensure that each static creative returned to your screens runs for the desired amount of time.
latitude

Degrees north.

Example value: 29.7628844

Float Optional For most cases, Vistar recommends passing the venue_id only and leaving the latitude and longitude blank. Since each venue has a latitude and longitude, the ad server can look up the location at the time of the request. The only time we recommend passing the latitude and longitude in your ad requests is when you have venues that move (for example, taxi cabs).
longitude

Degrees east.

Example value: -95.3830615

Float Optional For most cases, Vistar recommends passing the venue_id only and leaving the latitude and longitude blank. Since each venue has a latitude and longitude, the ad server can look up the location at the time of the request. The only time we recommend passing the latitude and longitude in your ad requests is when you have venues that move (for example, taxi cabs).
direct_connection

Expected value:
false

String Required This field is not recommended for use and should always be set to "false".

 

Note

Geographic targeting is used very frequently in ad campaigns. Sending an invalid or inaccurate set of geographic information will impact how many ads may be shown for your device, which will then reduce the maximum CPMs available. For example, if an agency targets some number of zip codes and your device does not provide relevant geo data, it will not show that ad, even if the ad is targeted to the zip where the screen happens to be.

Sample JSON request
{
"device_id": "VistarDisplay0",
"device_attribute": [],
"display_area": [
  {
    "height": 1920,
    "supported_media": [
      "application/x-shockwave-dynamic-flash",
      "application/x-shockwave-flash",
      "image/jpeg",
      "image/png",
      "video/mp4",
      "video/mpeg",
      "video/mpg",
      "video/quicktime",
      "video/webm",
      "video/x-flv",
      "video/x-ms-wmv",
      "video/x-msvideo"
    ],
    "width": 1080,
    "id": "display-0",
    "allow_audio": false,
    "static_duration": 8
  }
],
"display_time": 1562706713,
"venue_id": "DEFAULT_VENUE_ID",
"network_id": "HtEQ8rPVTeiXXXXXXXXXXX",
"direct_connection":false

"longitude": -73.9925458,
"latitude": 40.7450898,
"api_key": "8876e3dd-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
}

Back to top

Ad response

Each ad request can result in one or more ad responses. At most, there is one ad response per display area specified. If requesting ads for multiple display areas, you can correlate the advertisement object by referencing the display_area_id.

Note that a valid ad request can return an empty response. This can occur when there is no qualifying ad to be returned based on your campaign targeting parameters.

Response body parameters

Name Description Type Required Notes
advertisement An advertisement is a single asset destined for a single display area with the given attributes.   Required 

If your inventory supports resizing, we may return an ad that is not the exact size of the reference asset.

In order to reach as much inventory as possible, we may find an ad that roughly fits into this display area. The aspect ratio, however, should be nearly identical.

id The unique identifier of the advertisement. String Required  
proof_of_play_url

This URL must be fetched once the advertisement has been displayed. If successful, the API will respond with a 204 (No Content) status code. After the URL is fetched, it cannot be fetched again.

Max characters : Can vary but generally around 2048 chars. See notes.

String Required Vistar makes the best effort to keep proof of play urls as short as possible, but sometimes having their length grow is unavoidable. Note, this url may be a few KB and if using a Relational database management system (RDMS) the url should be stored as TEXT. 
lease_expiry

Epoch Seconds UTC at which the Advertisement will expire.

Example value: 1338260504

Int64 Required

When Vistar leases an ad, the ad is only eligible to be played up until the time specified in thelease_expiry value.

This value is 24 hours from the requested display time for ads from direct campaigns and ranging from 1-4 hours for exchange campaigns.

display_area_id   String Required  
asset_url A unique URL that will always represent the same content. String Required  
asset_id A unique ID that represents the asset returned to serve on your screen. This asset could be the originally uploaded creative or a transcoding. String  Required  
width

The width, in pixels, of an Advertisement.

Example value: 1280

Int32 Required  
height

The height, in pixels, of an advertisement.

Example value: 720

Int32 Required  
mime_type   String Required  
creative_id The unique identifier associated with the original creative that was uploaded.

For creatives submitted through the exchange or from a PMP transaction, this ID is displayed in the creative approval view of the ad platform when you click on an individual creative.
String Required  
expiration_url This should be fetched in the case that you do not plan on showing the advertisement. This allows us to reallocate the budget that was leased out for this advertisement. String Required  
length_in_seconds

Describes how long the assets should play in seconds.

Example value: 15

Int32 Optional  
length_in_milliseconds

Describes how long the assets should play in milliseconds. If omitted or 0, there are no restrictions on how long the advertisement shows.

Example value: 15000

Int32 Optional  
advertiser The advertiser is typically a brand (for example, Nike, Ford, Dell) and they provide the creatives for their campaigns. String Required  
display_time

The requested display time in UTC epoch seconds. An ad must be shown within the same hour of this display_time in order to respect campaign day part targeting.

Example value: 1354576345

Int64 Required  
deal_id The unique identifier associated with the deal to which the returned creative belongs. If the returned creative is not part of a deal, deal_id is null. String Optional  
order_id

The contract number associated with the advertisement's order.

Note that there is a limit of 22 characters.

String Optional  
creative_category

View the creative category codes.

Example value: 13610

String Optional  
creative_companion Creative companions are key value pairs that can be associated with a creative. Each companion is either a file (for example, an image) or an attribute (free form string value). They will be included on the ad response when they are associated with a creative. String Optional This is only relevant for certain media owners. Assume that you can ignore this.
name

The name of the creative companion.

Example value: logo

String Required* *This is required only
if the creative_companion field is in the response.
value

The value of the companion. This will either be a URL (for a file) or a string (for an attribute).

Example value:
https://s3.amazonaws.com
/dev.assets.
vistarmedia.com/

String Required* *This is required only
if the creative_companion field is in the response.
Sample JSON response
{
"advertisement": [
{
"id": "2031187955",
"proof_of_play_url": "https://api.vistarmedia.com/api/v2/proof_of_play/
json?s=PP0Yap3JG99FVxKBw5-dMus9_Y9l5tIamM8tXwO9LDIph2zStCusX_
6GrXe1Bld42tx8ii9o9xN20cyDomnvlAk5Oq4YFcy5sGuLG32eLFUfp9Kqm_
VytwZ4jPA2c_63Wg18LM0rfolZE1EaolKuvJpkp011k_LZc5N24xo69fm_
CFPwFDe9Nnv9Mx7JXFRpPO0WKKxSUGy36QjKsHJEGRfYxXtE5CXWzNbxBFenbUOX_
qgjmGvXxkGHjREZwMiEnrmMUmZ-r3uWVo540uKxah2tm33bu_3Bg6KT-
JpSqav3q4f1h0I3rIdIEfvnSHbpgvZhWMaIO2LBrwa97zQRqjFKCea56WELR8g6MPS0SME_
9n-Kwrok8ouRdT9OZAPtSZxSzVmyCj90KykMUGfMwj-poODmNR0XvrZ8rhIo1oB12N54fV1O-
A5W9Qk6VU67QBYm-Awf2Vsdar3lMsW4aG4QqsR7EXu_vVBRIbGe8Kid57K7aOUx1-FcVyLd",
"expiration_url": "https://api.vistarmedia.com/api/v2/cancel/json?s=
PP0Yap3JG99FVxKBw5-dMus9_Y9l5tIamM8tXwO9LDIph2zStCusX_6GrXe1Bld42tx8ii9o9
xN20cyDomnvlAk5Oq4YFcy5sGuLG32eLFUfp9Kqm_VytwZ4jPA2c_63Wg18LM0rfolZE1Eao
lKuvJpkp011k_LZc5N24xo69fm_CFPwFDe9Nnv9Mx7JXFRpPO0WKKxSUGy36QjKsHJEGRfYx
XtE5CXWzNbxBFenbUOX_qgjmGvXxkGHjREZwMiEnrmMUmZ-r3uWVo540uKxah2tm33bu_
3Bg6KT-JpSqav3q4f1h0I3rIdIEfvnSHbpgvZhWMaIO2LBrwa97zQRqjFKCea56WELR8g6
MPS0SME_9n-Kwrok8ouRdT9OZAPtSZxSzVmyCj90KykMUGfMwj-poODmNR0XvrZ8rhIo1oB1
2N54fV1O-A5W9Qk6VU67QBYm-Awf2Vsdar3lMsW4aG4QqsR7EXu_vVBRIbGe8Kid57K7aOUx1
-FcVyLd",
"order_id": "c10D2L00004vnqSDUA2",
"display_time": 1567093166,
"lease_expiry": 1567100573,
"display_area_id": "004.079012",
"creative_id": "766094572e5c18406a2a646a696f0e055d5b55464142",
"asset_id": "39552c386c091c126b3070315315101a4c4451486464",
"asset_url": "https://assets-cdn.vistarmedia.com/creative/P_
FgGlcfrSYixpR-Uzpek-w/f1/bcd/ff1b0201-3eae-4a15-8334-288b6
b6274dc.jpg",
"width": 1200,
"height": 400,
"mime_type": "image/jpeg",
"length_in_seconds": 8,
"length_in_milliseconds": 8000,
"campaign_id": 1846159892,
"creative_category": "10082",
"advertiser": "Campbells",
"deal_id": "987uXnf7ZRyq88ESkIVlS_g"
}
]
}

Back to top

Proof of play

You must notify Vistar after an ad is played by hitting the proof_of_play_url located in the ad response. When the URL is hit, the time is recorded in Vistar’s system as the reported display time. If you hit the URL at a different time than the ad was played, you can append that display time to the query string, as shown in the Sample proof of play URL.

Body parameters

Name Description Type Required Notes
display_time

The actual time an ad was shown in UTC epoch seconds.

Example value: 1338260504

Int32 Required We suggest that the display time fall within the hour of the requested time.
Sample proof of play URL
https://api.vistarmedia.com/api/v1/proof_of_play/json?l=
CJH9k4YD2NDgtNDK4AcLjLc&display_time=1364832421

Back to top

Proof of play response

After you submit a proof of play, you receive a response message that includes the cost information about the advertisement.

Response body parameters

Name Description Type Notes
impressions

The number of impressions spent for the spot.

Example value: 4

Float  
media_cost

The amount spent for the spot in nano-dollars. Nano-dollars is used to ensure precision is not lost in the rounding.

Example value: 1380087500

Int32  
expires

Count of expirations.

Example values: 0 when a proof of play is submitted; 1 when an advertisement expiry is sent.

Int32  
errors

Number of errors encountered processing the proof of play.

Example value: 0 on a success proof of play.

Int32  
message Debugging messages in the case of errors. String  
Sample JSON response
{"impressions":2.236739417989418,"media_cost":11183697,"spots":1,
"expires":0,"errors":0}

 

Back to top

Was this article helpful?
3 out of 6 found this helpful