Sync video content metadata (API)
Overview
With Equativ’s video content metadata API, video publishers can synchronize the metadata of their video content catalog with Equativ. Video content metadata describe the content that is being monetized, i. e. the content where an impression appears. The metadata includes attributes such as episode number, title, season, genre, album, producer etc. The API is mainly for publishers of Connected TV applications using Equativ to monetize their inventory.
Supported industry standards
The API supports the following industry standards for video content metadata:
Authentication
For information about how to authenticate, refer to the API authentication article.
Errors
For all errors, the HTTP error code 403 Forbidden is being returned.
| Error name | Description |
|---|---|
AccessDenied |
returned in case of unauthorized requests (see section “Authentication” above) |
RowsNumberExceeded |
returned if the global limit of 10000 open RTB or MRSS configuration objects/items is exceeded |
UnableSaveContentMetadataToDb |
returned if the API is unable to process the objects/items, i. e. the object/item cannot be saved in the database |
Limits
The global number of open RTB or MRSS objects/items is limited to 10000 objects/items.
API methods
POST /UploadVideoContentMetadata
At this time, the video content metadata API supports the POST method only. More methods (GET etc.) will follow soon.
When posting an object/item which already exists, all of the previously stored video content metadata of this object/item is wiped and the object/item is replaced by the new video content metadata payload. Partial updating of an existing object/item is not yet supported!
Both standards (Media RSS and IAB Open RTB) are supported when synchronizing video content metadata with the POST method:
POST https://content.smartadserverapis.com/UploadVideoContentMetadata
Request sample – IAB open RTB
This request sample creates two Content objects with the Ids fake-id-1 and fake-id-2. If the objects were created successfully, the status code 201 Created is returned.
[
{
"id": "fake-id-1",
"episode": 1,
"title": "fake-title-1",
"series": "fake-series-1",
"season": "fake-season-1",
"artist": "fake-artist-1",
"genre": "fake-genre-1",
"album": "fake-album-1",
...
},
{
"id": "fake-id-2",
"episode": 2,
"title": "fake-title-2",
"series": "fake-series-2",
"season": "fake-season-2",
"artist": "fake-artist-2",
"genre": "fake-genre-2",
"album": "fake-album-2",
...
}
]Request sample – MRSS
This request sample creates two items with the Ids fake-id-1 and fake-id-2. If the items were created successfully, the status code 201 Created is returned.
<?xml version="1.0" encoding="UTF-8" ?>
<rss xmlns:atom="http://www.w3.org/2005/Atom"
xmlns:media="http://search.yahoo.com/mrss/"
xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/"
xmlns:dfpvideo="http://api.google.com/dfpvideo"
xmlns:tms="http://data.tmsapi.com/v1.1"
version="2.0">
<channel>
<atom:link rel="next" href="https://www.fake.com/?page2" />
<item>
<dfpvideo:contentId>fake-id-1</dfpvideo:contentId>
<dfpvideo:lastModifiedDate>2022-09-21T08:00:00+01:00</dfpvideo:lastModifiedDate>
<title>Fake 1</title>
<dfpvideo:cuepoints>12.345,67</dfpvideo:cuepoints>
<dfpvideo:keyvalues key="episode" value="1" type="string" />
<dfpvideo:keyvalues key="season" value="1" type="string" />
<dfpvideo:thirdPartyContentId cms="youtube" id="fake-3rd-party-content-id-1" />
<media:content url="https://www.fake.com/video?qwerty" duration="1234" />
<media:status state="active" />
<media:thumbnail url="https://www.fake.com/thumbnail-1.jpg" width="100" height="50" />
<pubDate>2020-01-01T00:00:00+01:00</pubDate>
<tms:tmsId>EP123400000000</tms:tmsId>
<tms:tmsSeriesId>SH123400000000</tms:tmsSeriesId>
<dfpvideo:ingestUrl type="application/x-mpegURL" preconditioned="false">https://fake.com/?v=123.m3u8</dfpvideo:ingestUrl>
<dfpvideo:lastMediaModifiedDate>2021-01-01T00:00:00+01:00</dfpvideo:lastMediaModifiedDate>
<dfpvideo:closedCaptionUrl language="en" name="English (CC)" characteristics="public.accessibility.describes-music-and-sound" type="text/vtt">https://fake.com/subtitle.vtt</dfpvideo:closedCaptionUrl>
<dfpvideo:fw_caid>123456789000</dfpvideo:fw_caid>
</item>
<item>
<dfpvideo:contentId>fake-id-2</dfpvideo:contentId>
<dfpvideo:lastModifiedDate>2022-09-21T08:00:00+01:00</dfpvideo:lastModifiedDate>
<title>Fake 2</title>
<dfpvideo:cuepoints>12.345,67</dfpvideo:cuepoints>
<dfpvideo:keyvalues key="episode" value="2" type="string" />
<dfpvideo:keyvalues key="season" value="1" type="string" />
<dfpvideo:thirdPartyContentId cms="youtube" id="fake-3rd-party-content-id-2" />
<media:content url="https://www.fake.com/video?qwerty" duration="1234">
<media:status state="deleted" />
<media:thumbnail url="https://www.fake.com/thumbnail-2.jpg" width="100" height="50" />
</media:content>
<pubDate>2020-01-01T00:00:00+01:00</pubDate>
<tms:tmsId>EP123400000000</tms:tmsId>
<tms:tmsSeriesId>SH123400000000</tms:tmsSeriesId>
<dfpvideo:ingestUrl type="application/dash+xml" preconditioned="true">https://fake.com//playlist.mpd</dfpvideo:ingestUrl>
<dfpvideo:lastMediaModifiedDate>2021-01-01T00:00:00+01:00</dfpvideo:lastMediaModifiedDate>
<dfpvideo:closedCaptionUrl language="en" name="English (CC)" characteristics="public.accessibility.describes-music-and-sound" type="text/vtt">https://fake.com/subtitle.vtt</dfpvideo:closedCaptionUrl>
<dfpvideo:fw_caid>123456789000</dfpvideo:fw_caid>
</item>
<dfpvideo:version>2</dfpvideo:version>
</channel>
</rss>