Catalog and availability feeds overview
Apple’s video content platform supports content programming using the Universal Media Catalog (UMC). To include your content in the UMC, you’ll need to supply at least one catalog XML feed with information about what content you have and availability XML feeds with information about where and when your content is available.
Service providers host the URL endpoints for their XML feeds and are responsible for ensuring the data is updated at a reasonable cadence alongside content availability.
For each content item, there should be a record in both the catalog feed and the availability feed that corresponds to the service where the content will be live. If items in the availability feed are not in the catalog feed at the time of ingest, those items may not be made available to viewers within the Apple TV app.
When managing a large number of feeds (as is the case with regional live services), explore the option of using a partner manifest.
Learn more about partner manifest feeds
Catalog feed
The feed must contain data for only one catalog identified by its unique identifier, a catalog ID. A catalog can include one or more content items. All movie and TV content items should be provided in a single catalog feed, and the order of items in the catalog feed is not important. Live sports content items should be provided in a separate catalog feed. One catalog should be used for multiple territories or multiple brands, when possible. Exclude adult-only content from the feed.
The catalog feed endpoint returns the catalog feed data as a formatted XML document. While the ordering of items within the catalog feed is not important, the order of feed elements within the items is important and should appear in the order specified in XML Feed Elements.
Learn more about metadata requirements
Availability feed
As a video service provider, you can implement the UMC Availability Data Interface to enable discovery and consumption of your content through various Apple experiences such the Apple TV app, Universal Search, and Apple Subscription Video. This allows Apple to know when, how, and where your content can be played.
Availability of your service and its content is described using:
- Offers: Describe when and how content is available.
- Restrictions: Define any limitations for a given offer.
- Locators: Specify where content can be opened or played. Locators should be excluded on any availability feeds for Apple Subscription Video services. This content plays back directly in the Apple TV app.
- Playable properties: Specify the accessibility and quality settings for content.
The feed must be published at the predefined HTTPS endpoint. This endpoint will be periodically accessed by the UMC Data Ingest Service.
To ensure security, the endpoint must support the HTTPS protocol using a certificate issued by a well-known certificate authority. For further security, limit endpoint access by IP range, use HTTP authentication, or force client-based certificate authentication. Work with your Apple Technical Partner Representative to ensure the IP addresses used to access your endpoints are on an approved list.
The feed must always reflect the current availability data for content offered as part of this service. A content item, identified by a content ID and a catalog ID, must be unique and appear only once in the feed. All availability data for a given content item must be consolidated and provided under a single element. This data will replace any previously provided availability data for this content item in this service.
Primary tasks to prepare availability data for ingestion
- Ensure your Team ID is registered.
- For Video App Integrations, the Team ID is the ID for the developer account your app is associated with.
- For Apple Subscription Video (Apple TV Channels) services, the Team ID will be identical to the provider short-name.
- If the Team ID is not known or not yet registered, contact your Apple Technical Partner Representative.
- Ensure your Service ID is registered.
- Service ID is a unique service identifier, as established during Apple service registration.
- If your Service ID is not known or not yet registered, contact your Apple Technical Partner Representative.
- Ensure the content items referenced in the availability data are provided through the catalog feed.
- Implement the availability feed with the data requirements as described in the UMC Availability Data Interface Specifications.
- Provide the HTTPS endpoint information for your availability data feed.
Two types of services are currently supported: video on demand (VOD) and linear. Feed data constraints differ depending on whether it’s a VOD or linear service.
VOD service
VOD service is used to provide availability for content in which the offer windows are not necessarily programmed in a back-to-back schedule. This service typically allows viewers to select and watch video content on demand, rather than having to watch at a specific broadcast time. VOD service supports TV shows, movies, and event-based sporting events.
VOD service can further be classified as an Apple Subscription Video service, where the video content is delivered using the Subscription Video Asset Specification.
Provide only one availability feed per market per VOD service type. For example:
- If your VOD service is live in the United States and Canada, you should provide one feed for each country.
- If you have VOD service through your app and an Apple Subscription Video service in the same market, you should provide one availability feed for the app service and another availability feed for your Apple Subscription Video service.
For VOD services, every published update must include the following:
- All items currently available in the service.
- All items that will become available within 48 hours following the feed’s publish time. For Apple Subscription Video service, the feed must include all items that will become available within seven days following the feed’s publish time.
- All items that expired 48 hours before the feed’s publish time.
Linear service
A linear service is used to provide availability for content in which the offer windows are typically programmed back-to-back on a continuous schedule. Play (tune-in) locators are typically provided on the service level and shared by all content items and offers under the service. Linear service supports live sporting events on a 24/7 linear channel.
Each availability service must be pre-registered with Apple and include the Service ID and Team ID. Each content item in a service is identified by its content ID and catalog ID.
For linear services, every published update must include availability data for the following:
- All items scheduled for the next 14 days following the feed’s publish time.
- All items scheduled 24 hours prior to the feed’s publish time.
Expiration of an availability window for an offer requires special care. It must be communicated in the XML feed by explicitly publishing the expiration in the feed at least 48 hours before the scheduled expiration. Removal of an availability item from the availability feed does not guarantee that the item’s offer will be expired.
Restricting content on Apple Subscription Video services
If you need to restrict playback for content in your service based on the viewer’s device location, manage restrictions in the service offers block in the header of the availability feed for Apple Subscription Video services. Video app integration content should not be restricted in the availability feed; instead, restrict it on the app client side, otherwise it may not properly display on the Apple TV app.
Additionally, if you supply multiple video quality options, accessibility features, advanced media components, or audio or subtitle files in multiple locales for a single asset, use playable properties to control visibility of these features in each market. Video app integration content can also use playable properties to inform viewers what playback options are available on your service. Note: Playable properties are not applicable to TV shows or TV seasons.
EU portability
If your Apple TV Channel is available in the European Union, you can support cross-border portability laws by adding device_location restrictions for each country.
Video app integrations are expected to comply with these regulations on the app client side and should not use this block in the availability feeds.
Ensure you apply the service offers restrictions block as outlined in EU Portability for Video Subscription Partners.
Create and maintain feeds with Sequence
Sequence is an Apple-built web tool that helps you create and maintain catalog and availability XML feeds that comply with UMC specifications. Reach out to your Apple Technical Partner Representative to get access and training for Sequence.