Ad Timings with the API

After you've added your ad tag to your account (see Ad Tags Overview for more details), you will want to set up your desired ad timings. Ads are displayed based on the ad timings that are set on a per video basis in Zype.

This guide will cover how to view and create Ad Timings using the API, Ad Timings can also be added and viewed using the admin, you can review the Ad Timings article for more information.  

List Ad Timings

Each video has a pre-roll ad timing configured by default, meaning that ads are set to appear before the video plays. This pre-roll Ad timing is created inside a Data source, both are created upon import/upload of the video. 

To list all the Ad timing for a video can use the List Ad Timings endpoint 

curl --request GET \  
 --url https://api.zype.com/videos/id/ad_timings \ 
 --header 'Accept: application/json'

The response will include an array holding a data source object, which will include an array with all the ad timings for the video.  

Here is a sample response with 2 ad timings, one at the start and a second one at 5 seconds mark: 

{
"response": [
   {
    "data_source_id": "5ec5aac7aa2f87000168511b",
    "ad_timings": [
        {
         "_id": "5d2dd1e1a1464859231d1352",
         "mode": "off",
         "time": 0,
         "type": "in"
         },
        {
          "_id": "5f529df4700bd70001d60794",
          "mode": "off",
          "time": 5,
          "type": "in"
         }]
     }]}

Add a New Ad Timing

To add new ad Timing the endpoint requires the video_id, the data_source_id, and the time in seconds for the ad timing. 

The data_source_id can be obtained using the List Ad Timings endpoint. 

curl --request POST \ 
  --url https://api.zype.com/videos/video_id/data_sources/data_source_id/ad_timings \
  --header 'Accept: application/json' \  
  --header 'Content-Type: application/json' \  
  --data '{"ad_timing":{"time":time}}'

For example, for video_id:5ec5aac7aa2f87000168511a, data_source_id: 5ec5aac7aa2f87000168511b and a time of 10 seconds for the ad, the request looks like this:

curl --request POST \ 
  --url https://api.zype.com/videos/5ec5aac7aa2f87000168511a/data_sources/5ec5aac7aa2f87000168511b/ad_timings \
  --header 'Accept: application/json' \  
  --header 'Content-Type: application/json' \  
  --data '{"ad_timing":{"time":10}}'

Creating ad timings in bulk

Now that we know how to list and create individual ad timings, we can write a simple bare-bones python script that takes a CSV file as input with video_ids and time for each ad timings we are going to add in seconds.

As seen above, creating new ad timings for a video is a 2 step process, first, we need to fetch the data_source_id, and once we have it, we can create each ad timing. 

Sample CVS File with spaces to improve readability: 

video_id,ad_timings
5f6025c71a23423423423423,"300,600,900"
234234234234234234234234,"600,1200,1500"

We are going to update 2 videos with 3 ad timing each, which are already in total second. 

Our Script will go over the CVS file line by line, use each video_id to fetch the corresponding data_source_id, and then create a request to create each individual ad timing.

import requests
import pandas as pd

api_key = 'YOUR_API_KEY'
df = pd.read_csv('sample.csv') #Name of the CSV file

# iterate on each row of the CVS File
for index, row in df.iterrows(): 
  # grab the video_id from the CVS File
  video_id = row['video_id']
  # and save all the ad timings for the video 
  # creating an array by separating each time using "," 
  ad_timings = row['ad_timings'].split(",")
 
  # We then create the URL for the request
  url = f"https://api.zype.com/videos/{video_id}/ad_timings?api_key={api_key}"    
  # And send the request for each video 
  response = requests.request("GET", url) 
  print(response.text)
  #From the response we grab the first (and only) data_source_id in the array
  dataSource = response.json()['response'][0]['data_source_id']
  # With the data_source_id we create the new url
  post_url = f"https://api.zype.com/videos/{video_id}/data_sources/{dataSource}/ad_timings?api_key={api_key}"

  # Finally create a post Request for each time value in the ad_timings array
  for time in ad_timings:
    payload = {"ad_timing": {"time": time}}
    post_response = requests.request("POST", post_url, json=payload)
    print(post_response.text)

As mentioned before, this is only a simple example and is not recommended for large data set as it does the process in sequence one by one, we are also not capturing or managing possible errors on the requests.