Program Data Structure with External ID

The following table describes the Program data structure with external ID, which defines information about a video program.

Field
Type
Mandatory
Description
program_id
String
True
 Unique identifier of the program across your entire video content catalog.
Program IDs must not be duplicated in the feed.
playback_items
List of PlaybackItems
True with Exception
 Video playback items with all available options.
You can provide multiple playback items.
Defined with the PlaybackItem data structure.
external_ids
List of ExternalProgramIds
True
 Unique identifiers of the program from reference metadata providers.
Defined with the ExternalProgramId data structure.
Table 1: Program data structure with external ID

PlaybackItem

The playback_items array defines video playback items and their available options with the PlaybackItem data structures.

Field
Type
Mandatory
Description
deeplink_payload
String
True
 Deeplink payload value to be delivered to your application. Your application must open the content's detail page using this payload value.
country_code
String
True
 Country in which this item is available, in ISO 3166-1 alpha-2 format (2-letter country codes)
license
String
True
 License type:
 • "free": can be watched without any restrictions
 • "rental": can be watched for a limited period after purchase
 • "purchase": can be watched at any time after purchase
 • "subscription": for subscription members only
 • "authentication": for signed-in members only
price
Decimal
True with Exception
 Item price, with up to two decimal places.
※ Exception: The "free", "authentication", and "subscription" license types do not require this field.
currency
String
True with Exception
 Currency of the item price, in ISO 4217 format (3-letter currency codes)
※ Exception: The "free", "authentication", and "subscription" license types do not require this field.
quality
String
True
 Playback video resolution:
 • "SD": 480p
 • "HD": 720p
 • "FHD": 1080p
 • "UHD": 2160p
 • "8K": 4320p
audio_languages
List of Strings
False
 Audio languages available with this playback option, as a list of languages in ISO 639-1 format (2-letter language codes)
subtitle_languages
List of Strings
False
 Subtitle languages available with this playback option, as a list of languages in ISO 639-1 format (2-letter language codes)
available_starting
String
True
 Content availability start time, in UTC, in "YYYY-MM-DD HH:MM:SS" format
Note: This data should be provided at least three days before the availability start time.
available_ending
String
True
 Content availability end time, in UTC, in "YYYY-MM-DD HH:MM:SS" format
Note: This data should be provided at least three days before the availability end time.
attributes
List of Strings
False
 Predefined optional tags. Refer to Attribute Tag.
geo_restrictions
GeoRestrictions
False
 Location-based restrictions of the PlaybackItem. Defined with the GeoRestrictions data structure.
Note:
 • If geo_restrictions is not specified, the playback item defaults to "allow" nationwide.
 • The geo_restrictions field is applicable only if all of the program is "sports event".
 • All PlaybackItems within the same program_id that share the same country_code must have the same geo_restrictions value.
Table 2: PlaybackItem data structure

Example:

{
  "playback_items": [
    {
      "deeplink_payload": "content_id=12335",
      "country_code": "US",
      "license": "purchase",
      "price": 10.99,
      "currency": "USD",
      "quality": "FHD",
      "audio_languages": ["en", "es"],
      "subtitle_languages": ["en", "es"],
      "available_starting": "2019-04-14 00:00:00",
      "available_ending": "2020-04-14 16:00:00",
      "attributes": ["live_ott", "hdr10+"]
    }
  ]
}

Attribute Tag

An attribute tag is a predefined tag that describes an additional content attribute. More tags may be added in the future.

Name
Description
live_ott

 Live OTT viewing option tag
hdr10+

 HDR10+ video tag
Table 3: Attribute tags

GeoRestrictions

The GeoRestrictions data structure defines the location-based restrictions of each playback item.

Field
Type
Mandatory
Description
access_type
String
True
 PlaybackItem access type:
 • "allow": defines a list of the only locations where the content can be shown.
 • "deny": defines a blackout list of locations where the content cannot be shown.
Note:
 • The access_type value must be either "allow" or "deny". They are mutually exclusive.
 • If "allow" is chosen, all locations not listed in "value" are treated as restricted. Conversely, if "deny" is chosen, all locations not listed in "value" are treated as unrestricted.
type
String
True
 GeoRestrictions type. Only one of the geoRestriction types can be used for each playback item.
value
List of Strings / List of GeoRestrictionAreas
True
 Georestrictions value list. Refer to geoRestriction value.
Note: The data type of the "value" field varies according to its geoRestriction type.
Table 4: GeoRestrictions data structure

Example:

{
  "geo_restrictions": {
    "access_type": "allow",
    "type": "timezone",
    "value": ["America/Denver", "America/Los_Angeles"]
  }
}

Example:

{
  "geo_restrictions": {
    "access_type": "deny",
    "type": "area",
    "value": [
      {
        "region": "Texas",
        "city": ["El Paso"]
      },
      {
        "region": "California",
        "city": ["San Diego", "San Francisco"]
      }
    ]
  }
}

geoRestriction type

Each playback item can have only one georestriction type.

Type
Description
dma

 Designated Market Area: geographic areas in the U.S. defined by Nielsen.
area

 Area-based restriction by region or city.
timezone

 Region that observes a uniform standard time.
zipcode

 Postal code that identifies a delivery area.
Table 5: Georestriction types

geoRestriction value

The data type of the georestriction value depends on the georestriction type.

Restriction type
Data type
Description
dma
List of Strings
 Supported DMAs are defined in the DMA list.
area
List of GeoRestrictionAreas
 Defined with the GeoRestrictionArea data structure.
timezone
List of Strings
 Time zone in IANA Time Zone Database format
(for example, America/Los_Angeles, America/New_York)
zipcode
List of Strings
 The length of the zipcode varies by country. We use partial zipcodes because full zipcodes are specific down to the street level, which is more granular than the location data we use. For example, the US uses a standard 5-digit zipcode, and an additional 4 digits can be added for more specific information. However, these additional 4 digits are not included in this specification because they refer to areas too small to be useful for geo-blocking. Canada uses 6-character postal codes, but only the first 3 characters are used for geo-blocking.
 • US: 5 characters (e.g., "10016" for New York)
 • CA: 3 characters (e.g., "L4A" for Stouffville)
 • GB: 2-4 characters (e.g., "CB8" for Newmarket)
Note: The accuracy of zipcode-based restrictions cannot be guaranteed.
Table 6: Georestriction values

GeoRestrictionArea

This data structure defines a restricted area by location. It is used only for the "area" georestriction type.

Field
Type
Mandatory
Description
region
String
True
 Name of the subdivision (for example, "Texas", "California")
Note: When city is provided, region must be the subdivision to which those cities belong.
city
List of Strings
False
 Names of cities within the specified region, at the city level only and not in smaller units, such as towns or villages
(for example, "El Paso, "San Diego", "New York", "Los Angeles")
Note: For a region-only restriction, the city field is not needed.
Table 7: GeoRestrictionArea data structure

ExternalProgramId

The external_ids array defines the IDs of the program with the ExternalProgramId data structure. The IDs originate from a reference metadata provider, enabling the Samsung database to cross-reference and match it with existing database entries.

Field
Type
Mandatory
Description
external_program_id
String
True
 Provider's unique program ID
provider
String
True
 Reference metadata provider name:
 • "tms": Gracenote TMS ID
Note: Currently, only TMS IDs are accepted, and only in the US, CA, and AU.
id_type
String
True with Exception
 If the provider uses multiple IDs for the same content, the ID type must be specified.
For Gracenote TMS ID, the "tmsId" and "rootId" ID types are supported.
※ Exception: Providers other than Gracenote TMS ID do not require this field.
Table 8: ExternalProgramId data structure

Example:

{
  "external_ids": [
    {
      "external_program_id": "EP123",
      "provider": "tms",
      "id_type": "rootId"
    },
    {
      "external_program_id": "EP456",
      "provider": "tms",
      "id_type": "tmsId"
    }
  ]
}

Feed Samples

The following example feeds define program metadata with an external ID:

  • Example JSON feed (with external ID):
{
  "programs": [
    {
      "program_id": "12335",
      "playback_items": [
        {
          "deeplink_payload": "content_id=12335",
          "country_code": "US",
          "license": "purchase",
          "price": 10.99,
          "currency": "USD",
          "quality": "FHD",
          "audio_languages": ["en", "es"],
          "subtitle_languages": ["en", "es"],
          "available_starting": "2019-04-14 00:00:00",
          "available_ending": "2020-04-14 16:00:00",
          "attributes": ["live_ott", "hdr10+"],
          "geo_restrictions": {
            "access_type": "deny",
            "type": "area",
            "value": [
              {
                "region": "Texas",
                "city": ["El Paso"]
              },
              {
                "region": "California",
                "city": ["San Diego", "San Francisco"]
              }
            ]
          }
        },
        {
          "deeplink_payload": "content_id=12559",
          "country_code": "US",
          "license": "subscription",
          "quality": "FHD",
          "audio_languages": ["en"],
          "subtitle_languages": ["en"],
          "available_starting": "2025-03-17 16:00:00",
          "available_ending": "2025-03-17 17:30:00",
          "attributes": ["live_ott", "hdr10+"],
          "geo_restrictions": {
            "access_type": "deny",
            "type": "area",
            "value": [
              {
                "region": "Texas",
                "city": ["El Paso"]
              },
              {
                "region": "California",
                "city": ["San Diego", "San Francisco"]
              }
            ]
          }
        },
        {
          "deeplink_payload": "content_id=67890",
          "country_code": "US",
          "license": "subscription",
          "quality": "HD",
          "audio_languages": ["en", "it"],
          "available_starting": "2022-01-15 19:13:00",
          "available_ending": "2022-05-22 23:59:00",
          "geo_restrictions": {
            "access_type": "deny",
            "type": "area",
            "value": [
              {
                "region": "Texas",
                "city": ["El Paso"]
              },
              {
                "region": "California",
                "city": ["San Diego", "San Francisco"]
              }
            ]
          }
        }
      ],
      "external_ids": [
        {
          "external_program_id": "EP123",
          "provider": "tms",
          "id_type": "rootId"
        },
        {
          "external_program_id": "EP456",
          "provider": "tms",
          "id_type": "tmsId"
        }
      ]
    }
  ]
}
  • Example XML feed (with external ID):
<?xml version="1.0" encoding="UTF-8"?>
<programs>
  <program>
    <program_id>12335</program_id>
    <playback_items>
      <playback_item>
        <deeplink_payload>content_id=12335</deeplink_payload>
        <country_code>US</country_code>
        <license>purchase</license>
        <price>10.99</price>
        <currency>USD</currency>
        <quality>FHD</quality>
        <audio_languages>
          <audio_language>en</audio_language>
          <audio_language>es</audio_language>
        </audio_languages>
        <subtitle_languages>
          <subtitle_language>en</subtitle_language>
          <subtitle_language>es</subtitle_language>
        </subtitle_languages>
        <available_starting>2019-04-14 00:00:00</available_starting>
        <available_ending>2020-04-14 16:00:00</available_ending>
        <attributes>
          <attribute>live_ott</attribute>
          <attribute>hdr10+</attribute>
        </attributes>
        <geo_restrictions>
          <access_type>deny</access_type>
          <type>area</type>
          <value>
            <area_object>
              <region>Texas</region>
              <city>
                <city_object>El Paso</city_object>
              </city>
            </area_object>
            <area_object>
              <region>California</region>
              <city>
                <city_object>San Diego</city_object>
                <city_object>San Francisco</city_object>
              </city>
            </area_object>
          </value>
        </geo_restrictions>
      </playback_item>
      <playback_item>
        <deeplink_payload>content_id=12559</deeplink_payload>
        <country_code>US</country_code>
        <license>subscription</license>
        <quality>FHD</quality>
        <audio_languages>
          <audio_language>en</audio_language>
        </audio_languages>
        <subtitle_languages>
          <subtitle_language>en</subtitle_language>
        </subtitle_languages>
        <available_starting>2025-03-17 16:00:00</available_starting>
        <available_ending>2025-03-17 17:30:00</available_ending>
        <attributes>
          <attribute>live_ott</attribute>
          <attribute>hdr10+</attribute>
        </attributes>
        <geo_restrictions>
          <access_type>deny</access_type>
          <type>area</type>
          <value>
            <area_object>
              <region>Texas</region>
              <city>
                <city_object>El Paso</city_object>
              </city>
            </area_object>
            <area_object>
              <region>California</region>
              <city>
                <city_object>San Diego</city_object>
                <city_object>San Francisco</city_object>
              </city>
            </area_object>
          </value>
        </geo_restrictions>
      </playback_item>
      <playback_item>
        <deeplink_payload>content_id=67890</deeplink_payload>
        <country_code>US</country_code>
        <license>subscription</license>
        <quality>HD</quality>
        <audio_languages>
          <audio_language>en</audio_language>
          <audio_language>it</audio_language>
        </audio_languages>
        <available_starting>2022-01-15 19:13:00</available_starting>
        <available_ending>2022-05-22 23:59:00</available_ending>
        <geo_restrictions>
          <access_type>deny</access_type>
          <type>area</type>
          <value>
            <area_object>
              <region>Texas</region>
              <city>
                <city_object>El Paso</city_object>
              </city>
            </area_object>
            <area_object>
              <region>California</region>
              <city>
                <city_object>San Diego</city_object>
                <city_object>San Francisco</city_object>
              </city>
            </area_object>
          </value>
        </geo_restrictions>
      </playback_item>
    </playback_items>
    <external_ids>
      <external_id>
        <external_program_id>EP123</external_program_id>
        <provider>tms</provider>
        <id_type>rootId</id_type>
      </external_id>
      <external_id>
        <external_program_id>EP456</external_program_id>
        <provider>tms</provider>
        <id_type>tmsId</id_type>
      </external_id>
    </external_ids>
  </program>
</programs>