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).
Click here to view the Ad Serving API documentation in Chinese
The following diagram shows a simplified version of what a native integration could look like.
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
POST https://sandbox-api.vistarmedia.com/api/v1/get_ad/jsonPOST https://api.vistarmedia.com/api/v1/get_ad/jsonRequest 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 | An ad request without a venue_id is not a valid request as of May 2023 |
| 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 toTrue. |
| supported_ media |
The valid mime types and encodings supported by the device. Example Values:
Note: |
String | Required | If you have audio-only inventory (no physical screens), set this parameter to one or both of the following mime types:
|
| min_duration | Minimum acceptable video 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 video 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: |
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: |
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: |
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: |
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: |
String | Required | This field is not recommended for use and should always be set to "false". |
| excluded_creative_id |
The Example value: |
String Array | Optional | This field is recommended in cases where ads should not be played consecutively or there are competitive separation concerns |
| blocked_category |
The creative category ID of any and all categories that should not be returned in the ad response. The ID maps to the Example value: |
String Array | Optional | This field is recommended to supplement venue and network restrictions as well as to handle any competitive separation concerns |
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.
{
"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",
"excluded_creative_id": [
"766094572e5c18406a2a646a696f0e055d5b5546XXXX",
"766094572e5c18406a2a646a696f0e055d5b5546YYYY"
],
"blocked_category": [
"1008X",
"1008Y"
]
}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 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 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: |
Int64 | Required |
When Vistar leases an ad, the ad is only eligible to be played up until the time specified in the This value is 24 hours from the requested display time for ads from direct campaigns and 15 minutes for exchange campaigns. |
| display_area_id | String | Required | ||
| asset_url |
A unique URL that will always represent the same content.
|
String | Required |
We recommend caching based on asset_url. The asset_url will update for every unique version of the creative that is generated. |
| 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: |
Int32 | Required | |
| height |
The height, in pixels, of an advertisement. Example value: |
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: |
Int32 | Optional | |
| length_in_milliseconds |
Describes how long the assets should play in milliseconds. If omitted or Example value: |
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 Example value: |
Int64 | Required | |
| deal_id | The unique identifier associated with the deal(PMP) to which the returned creative belongs. If the returned creative is not part of a deal (PMP), deal_id is not found in the response. |
String | Optional | |
| order_id |
The contract number associated with the direct-flexible order. If there is not contract number associated with the order, the field is empty. Note that there is a limit of 22 characters. |
String | Optional | |
| creative_category |
View the creative category codes. Example value: |
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. | Object Array | Optional | This is only relevant for certain media owners. Assume that you can ignore this. |
| name |
The name of the creative companion. Example value: |
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: |
String | Required* | *This is required only if the creative_companion field is in the response. |
| bid_type |
This is the bid type of the demand. The value will be one of the following:
|
String | Required |
{
"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",
"bid_type": "DEAL"
}
]
}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: |
Int32 | Required | We suggest that the display time fall within the hour of the requested time. |
https://api.vistarmedia.com/api/v1/proof_of_play/json?l=
CJH9k4YD2NDgtNDK4AcLjLc&display_time=1364832421
How display times drive reporting
Vistar reporting relies on the reported display time to determine when ad delivery occurred. So, for example, if a proof of play is sent with a display time appended, reporting will reflect the appended time. It's important that the appended display time is an accurate reflection of when the ad ran. If there is no display time appended, the display time will be set to the time the proof of play url was hit.
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: |
Float | |
media_cost |
The gross amount spent for the spot in nano-dollars. Nano-dollars is used to ensure precision is not lost in the rounding. Example value: |
Int32 | |
expires |
Count of expirations. Example values: |
Int32 | |
errors |
Number of errors encountered processing the proof of play. Example value: |
Int32 | |
message |
Debugging messages in the case of errors. | String |
{"impressions":2.236739417989418,"media_cost":11183697,"spots":1,
"expires":0,"errors":0}