Digital Measurement SEI Content Asset Metadata
From Engineering Client Portal
The Nielsen "Server-To-Server" method of collecting DCR data requires the distributor to make available each Asset (Episode) referenced in the DCR Viewing file in a separate metadata file (a.k.a metadata catalog).
Naming Convention and Delivery Specification
Consolidated list of asset metadata catalog that is up to date for a particular hour needs to be provided in a single file following the naming convention specified below. The metadata needs to be in a json lines format, including a header line. A reasonable effort needs to be made to remove expired/inactive asset ids, to avoid size creep.
Nielsen will move files to indicate they are being processed.
S3 bucket naming convention:
useast1-nlsn-w-dig-sei-<partner_id>-feeds-<env>/<s3_prefix>/<s3_object>
S3 prefix naming convention:
<file_type>/yyyy/mm/dd/hh
S3 object naming convention:
<partner_id>_<file_type>_<int_id>[.gz|.bz2]
partner_id | Partner id provided by Nielsen (4 letter code or TICK symbol, a.k.a. publisher id) in human readable format. |
env | [ test | prod ] |
int_id | Integration id provided by Nielsen. Used to link different integration inputs, ex. associate single audit ping integration with different viewsership pipelines (dar, dtvr, dcr, etc.) |
file_type | [ dcrassetmetadata ] |
/yyyy/mm/dd/hh/ | year/month/day/hour (including leading zeros, starting from 00 hour )
ex.: 2023/02/12/05 |
[.gz|.bz2] | Uncompressed json lines (no extension) - splittable, ideal for medium size files, less than 5 GB, preferred for metadata. Optional compression formats supported:
|
Example of a file for 10:00 EST to 11:00 AM EST:
useast1-nlsn-w-dig-sei-acme-feeds-prod/dcrassetmetadata/2022/06/12/10/
acme_dcrassetmetadata_a9ddf15ea054ea415718767ea6
SLA
The files must be delivered into the proper S3 bucket within 2 hours of the broadcast. For example, files from 1:00 AM to 1:15 AM must be delivered before 3:00 AM. The metadata file should be delivered to an S3 bucket before any Viewing file has been delivered. Please refer to the associated specifications for the SLAs of these other files.
JSON Param Definition
Header Record:
Parameter | Description | Mandatory | Specified by | Format or Example |
schemaversion | Json Schema Version | Yes | Nielsen | Example: S2SAssetMetaDataDCRV2.0 |
mvpdid | Server App ID | Yes | Nielsen | Example: NLSN |
creationtime | File creation time | Yes | Client | Format: utc (time in 32-bit unsigned int UTC in seconds) |
recordcount | # of records in body of file | Yes | Client | Format: numeric
In this schema implementation this value is set to "1", as each file will only contain the metadata associated to a single asset |
Header JSON Schema:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"schemaversion": { "type": "string" },
"mvpdid": { "type": "string" },
"creationtime": { "type": "string" },
"recordcount": { "type": "string" }
},
"required": [ "schemaversion", "appid", "creationtime", "recordcount" ]
}
Header Record - Example:
{"schemaversion":"S2SAssetMetaDataDCRV2.0","mvpdid":"NLSN","creationtime":"1473781507","recordcount":"1"}
Body Record:
Parameter | Description | Mandatory | Specified by | Format or Example |
assetid | In-house asset id | Yes | Client | Format: alphanumeric,
Example: VID123456789 AssetId needs to be unique at episode level |
assetname | In-house video asset name,
for troubleshooting |
Yes | Client | Format: alphanumeric
Examples: TMS ID, EIDR ID or Episode title |
programname | Name of the program | Yes | Client | Format: alphanumeric, Max 25 char’s; no special characters
Example: Nightly News See below for more specific guidance on Program Name |
episodetitle | Title of the episode | Yes | Client | Format: alphanumeric,
Examples: News: “Prime Time News YYYY-MM-DD” TV Show: “The Greatest American Hero S2E23” Movie: “Movie Title” See below for more specific guidance on Episode Title |
episodelen | Total episode length | Yes | Client | Format: Integer (seconds)
Example: 3600 For continuous live stream or unknown duration use 24*60*60 (86400) Can be updated with a replacement asset file when the live playout ends, and the exact duration becomes known |
isfullepisode | Full episode Flag
(indicates full episode or a clip) |
Yes | Client | Format: integer – 0 (not full episode), 1 (full episode) |
genre | Nielsen genre code | No | Client | Format: alphanumeric
Example: CV (comedy variety), N (news) Contact Nielsen Technical support for a list of current Genre codes |
airdate | The date the episode was first made available on Traditional TV | No | Client | Format: US ET: YYYYMMDDHHMMSS
Example: 19970716231256 For the US, the time should be specified as Eastern Timezone. Other countries will use a local timezone. Used as default episode name if metadata not available This value can be updated with a replacement asset file if the original air date changes |
webpageurl | Website Identifier, for diagnostics, can be turned off/on as needed | No | Client | Format: alphanumeric (max 2k)
Example:https://www.myapp.com/video.html |
crossrefId1 | Content owner’s episode asset id. Used for secondary crediting | No | Client | Format: alphanumeric
Example: TMS ID, EIDR ID or Episode title Note: this field only needs to be populated by Distributors |
crossrefId2 | Content owner. Used for secondary crediting | Yes | Client | Format: alphabetical - Gracenote, channel mnemonic or Nielsen channel mnemonic
Example: AMC Contact Nielsen for a list of current Nielsen channel codes Note: this field only needs to be populated by Distributors |
Note: All parameters are case sensitive. Body - Example:
{"assetid":"VID123456789", "assetname":"myassetname", "programname":"Nightly News","episodetitle":"Prime Time News S2E23", "episodelen":"2000", "isfullepisode":"true", "genre":"N", "airdate":"19970716231256", "webpageurl":"http://www.myapp.com/video.html", "crossrefId1":"myepisodeid", "crossrefId2":"networkxyz"}
Additional Guidance on Program & Episode Metadata
If the intention is that the DCR metadata also be used for TCR (Total Content Ratings). Then the DCR Program & Episode name should be identical to the Program & Episode name that is used in Traditional TV Ratings. It is recommended to use the metadata registered in Nielsen TV Names systems (myEVNTS/myVOD). If a Nielsen TV Names systems is not used, then you may use the Program & Episode name registered with a 3rd party television listing service such as GraceNote.
Nielsen recommends the following format for Episode name:
Format: Episode Title + Season # + Episode # (e.g. Title S3E1).
Values: A minimum of one of the values below should be provided:
- Episode Title: must be first value if provided
- Season #: must follow Episode Title if provided
- Episode #: must follow Season # if provided
NOTE: It is recommended to pass all three values if available.
Identifiers:
- Season: 'Season', 'S'
- Episode: 'Episode', 'E', 'Ep'
- Not case sensitive
Delimiters:
- Supported delimiters: ' ' (space), ':', '.'
- Delimiters are optional
Characters:
- 40 character limit
- No special characters
You may reference the examples below to determine if you are passing a valid episode name:
- Valid: 'Title S2E9', 'Title S.2 EP.9', 'Title Episode:9'
- Invalid (with reason):
- 'Title S-2 E-9' '-' is not a supported delimiter
- 'Title Episode9 Season2' Season # must precede Episode #
- 'Title SE2 EP9' 'SE' is not a valid identifier