Creative Caching endpoint

Your CMS can make calls to Vistar’s ad server to request and cache creatives (also known as assets) in advance. All creatives that qualify to run on your network over the next 30 hours are returned from this endpoint. This is beneficial in the case of poor internet connectivity and can also help save on bandwidth usage.

Creatives are returned if all of the following are true:

  1. Creative is active.
  2. Creative is associated with an active campaign or line item.
  3. Creative is approved.
  4. Venue falls within creative or campaign targeting parameters. 

Note - device attributes, time of day and day of week targeting filters are not applied when determining the creatives to return from the caching endpoint. This is because as previously mentioned, the endpoint returns all creatives that qualify to run on your network over the next 30 hours. 

To view best practices for caching creatives, see the FAQs section in this article.

To request for creative assets

Use the following endpoint URL to make your request. You must specify a display_time to match up with relevant assets.

URL

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

Body parameters

See Ad Serving API for definitions of the body parameters.

Sample JSON request

{
  "device_id": "VistarDisplay0",
  "device_attribute": [],
  "display_area": [
    {
      "id": "display-0",
      "supported_media": [
        "application/x-shockwave-dynamic-flash",
        "application/x-shockwave-flash",
        "image/gif",
        "image/jpeg",
        "image/png",
        "video/mp4",
        "video/mpeg",
        "video/mpg",
        "video/quicktime",
        "video/webm",
        "video/x-flv",
        "video/x-ms-wmv",
        "video/x-msvideo"
      ],
      "allow_audio": false,
      "width": 1920,
      "height": 1280
    }
  ],
  "display_time": 1461181625,
"direct_connection": false
  "venue_id": "PHX003384",
  "network_id": "5U71FqbWTgSMAuO0XS-HHQ",
  "api_key": "0f877d21-33fe-40a0-a149-af3527a57130"
}

Sample JSON response

{
  "asset": [
    {
      "asset_id": "asset-1",
      "creative_id": "creative-1",
      "order_id": "Q1_2016_001",
      "campaign_id": "campaign-1",
      "asset_url": "http://url/to/asset.jpg",
      "width": 1280,
      "height": 720,
      "mime_type": "image/jpeg",
      "length_in_seconds": 15,
      "length_in_milliseconds": 15000,
      "creative_category": "Entertainment"
"advertiser": "Test Advertiser 1",
"creative_name": "Test Creative 1"

    },
    {
      "asset_id": "asset-2",
      "creative_id": "creative-2",
      "order_id": "Q1_2016_001",
      "campaign_id": "campaign-2",
      "asset_url": "http://url/to/asset2.mp4",
      "width": 1280,
      "height": 720,
      "mime_type": "image/mp4",
      "length_in_seconds": 30,
      "length_in_milliseconds": 30000,
      "creative_category": "Wildlife",
"advertiser": "Test Advertiser 2",
"creative_name": "Test Creative 2"
    }
  ]
}

 

FAQs

How often should I make a call to the Creative Caching endpoint?

As a best practice, we recommend sending a call for assets once a day. You should compare the assets in the get_assets response to the pool of already cached creatives using the creative ID. You should only download new creatives identified in the get_asset response.

What should I do when I see a new creative in the ad response?
If you receive an ad response with a creative that was not cached when the daily get_asset call was made, you should download the creative in real time and add it to the pool of cached creatives.
How much storage should I allocate for creative caching?

Storage needs vary from one media owner to another. There are a number of variables that dictate the volume of caching memory that you (the media owner) should allocate, such as:

  • The mime types you can support —See "What are the supported mime-types" in the Frequently asked questions article.
  • The demand for your inventory—This can vary from market to market and based on price.
  • Your caching criteria.

With this in mind, here are some recommended storage sizes to start out, depending on the types of creatives you support:

Creative type supported Recommendation
Images only At least 140 MB of storage
Video only At least 250 MB of storage
Images and video At least 400 MB of storage
Dynamic creatives At least 400 MB of storage

The following table also shows you asset sizes in the 90th percentile (based on our historical records) for your reference:

media_type asset size (bytes)
application/cortex-bundle 6530417
image / gif 252631
image / jpeg 1415926
image / png 2306046
video / mp4 5989494
video / mp4 -tt 11384636
video / ogg 5938633
video / quicktime 379911794
video / webm 4703875
video / x-ms-wmv 6308185
video / x-flv 4179606


For efficient management of your cache, we recommend the following best practices:

  1. Clearing the creative from your cache after 30 days.
    • It is recommended that you keep track of when a creative is first returned by Vistar’s ad server. For example, you can set a cache_date for the creative that you update each time you see the creative returned. You do not need to re-download the creative, but you should update the date to indicate the last time the creative was active.
  2. Monitoring the memory of your local cache using tools available to you based on your device or server operating system. Depending on the average volume of files cached in a 30 day window, you can adjust your storage size accordingly.
Was this article helpful?
4 out of 5 found this helpful