Media-Press Pivot API

Overview

Here is the link to our Pivot API documentation in Plurimedia.

This REST API provides access to metadata stored in our content-centric database, specifically designed to meet customer requirements. Responses from this API are in JSON format using UTF-8 encoding.

Important: API access is reserved exclusively for our customers.

Getting started

Developer Portal

As a customer, you’ll receive a unique username and password to access the Developer Portal. Within the portal, you can:

  • Retrieve your authentication token
  • Test API endpoints
  • View usage statistics

Authentication Token

Your authentication token can be found under the Profile menu option. You have access to two tokens:

  • Primary token (recommended)
  • Secondary token

If you suspect your token has been compromised, you can request a regeneration of your token through the portal.

Using the API

				
					Standard HTTP request to call a method.
Example implementations are available for different languages on each method page.
GET https://api.plurimedia.fr/v1/api/v1/contents/7488 HTTP/1.1
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: ••••••••••••••••••••••••••••••••
Standard answer
HTTP response
HTTP/1.1 200 OK

cache-control: no-cache
content-encoding: gzip
content-length: 2006
content-type: application/json; charset=utf-8
date: Tue, 05 Nov 2024 11:25:51 GMT
expires: -1
pragma: no-cache
request-context: appId=cid-v1:573995c4-a10b-48e5-b5b5-78ad0699dd05
vary: Accept-Encoding,Origin
x-aspnet-version: 4.0.30319
x-powered-by: ASP.NET

{
    "version": "v1",
    "statusCode": 200,
    "data": {
        "id": 7488,
        "title": "Blade Runner",
        "typographicTitle": "Blade Runner",
…
"lastUpdate": "2024-09-27T07:48:30.677",
        "isFre": true
    }
}


Note: Calls with no result return code 200 with an empty JSON.

Testing Endpoints

To test API endpoints:

  1. Navigate to the APIs section in the menu bar.

  2. Select your desired API version to see available endpoints.

  3. Click the Try it button for the endpoint you wish to test.

  4. Provide required parameters and optional parameters as needed.

  • Mandatory parameters must be filled.
  • Optional parameters can be managed using the

5. Remove parameter option.

Note: The lang parameter is always optional.

 

Data Organization

Our database revolves around the primary entity called Content. Every content entry contains at least:

  • Unique ID
  • Title
  • Format (e.g., Film, Series, Documentary, Sports Show, Magazine, etc.)
  • Genre

You can view the complete list of available formats and genres via the Categories endpoint.

A visual diagram summarizing all potential content attributes is provided below:

Viewing Statistics

To view your usage statistics, select the Reports option from the menu.

API Reference Guide

Import TV Schedule

Channels Data Management

To get started, first import the channel-related data available in your account.

Recommendation: Updating channel data once daily is sufficient.

Endpoints:

  • V1/Channels|Channels
    Retrieves a list of channels associated with your user account.
  • V1/Channels|ChannelCategories/{id}
    Retrieves the category list for a specified channel.
  • V1/Channels|ChannelPacks/{id}
    Provides IDs and channel numbers available from all EPG providers processed by Plurimédia.

Broadcasts

V1/Broadcasts|BroadcastsDaysAvailable

Returns the list of days available on the API for the channels to which you have access.

Tip: Call this endpoint once before each data import.

V1/Broadcasts|BroadcastsLastUpdated

Lists channels/days with modified broadcasts or content since a specified date and time (yyyyMMddHHmmss).
All returned data must be re-imported entirely, as deletions aren’t individually marked.

Tip: If the returned lastUpdate timestamp is earlier than your provided date/time parameter, only content details (guests, text, photos) have changed.

V2/Broadcasts|Broadcasts

Retrieves all broadcast details and associated metadata for a given channel and period.

Tip: Choose the lowest image hierarchy for optimal relevance:

  • hierarchy: 1: Broadcast-specific image
  • hierarchy: 2: Content-specific image
  • hierarchy: 3: Series or Season image
  • hierarchy: 4: Generic content category image

Collections and Master / Season Content

V2/Content|ContentMasterCollections

Retrieves IDs for collections, master content, and seasons attached to content broadcast over a specific period/channel.

Tip:

  • Import from V2/Contents/{id} if the Master/Season IDs aren’t in your system.
  • If IDs already exist, check lastUpdate to determine if re-import is necessary.

Person Metadata

V1/Persons|Persons/{id}

Returns standard data attached to the person whose ID is passed in parameter.

V1/Persons|PersonsBiography/{id}

Returns the Wikipedia biography of the person whose ID is passed in parameter.

V1/Images|PersonImages/{id}

Returns the casting image of the person whose ID is passed in parameter.

V1/Awards|PersonAwards/{personId}

Returns the awards attached to the person whose ID is passed in parameter.

Tags

V2/Tags|ContentTags

Returns the awards attached to the person whose ID is passed in parameter.

V1/Tags|ContentTags/{id}

(For VOD-only content)

Retrieve tags individually for content available exclusively via VOD catalogs.

Tip: The most significant keywords have the lowest numerical weight.

Awards and Sports Teams

V1/Awards|ContentAwards/{contentId}

Awards related to specified content.

V1/SportTeams|ContentSportTeams

Sports team metadata associated with specified content.

Trailers and Related Objects

V1/Videos|Videos

Retrieves available trailers for your authorized scope.

V1/Videos|VideoRelatedObjects/{id}

Provides associated IDs for:

  • “relatedContentIds”
  • “relatedBroadcastIds”
  • “relatedCollectionIds”
  • “relatedChannelIds”

Theatrical Releases

V1/Contents|TheatricalReleases

Retrieves content released in cinemas on a specified date.

Track Changes

V1/TrackChanges|TrackChanges

Identifies content objects updated since a given timestamp. Available objectType values include:

  • {“objectType”: “Award”}
  • {“objectType”: “Broadcast”}
  • {“objectType”: “ContentCatalog”}
  • {“objectType”: “Channel”}
  • {“objectType”: “ChannelInPack”}
  • {“objectType”: “Content”}
  • {“objectType”: “ContentExtradata”}
  • {“objectType”: “BroadcastExtradata”}
  • {“objectType”: “PersonExtradata”}
  • {“objectType”: “ChannelExtradata”}
  • {“objectType”: “SubCatExtradata”}
  • {“objectType”: “Person”}
  • {“objectType”: “SportTeam”)
  • {“objectType”: “SubCategory”}
  • {“objectType”: “PersonImage”}
  • {“objectType”: “PersonBiography”}

 

Episode Retrieval

Contents|SeasonContent/{id}

Retrieves all episodes linked to a Season or Master Content ID.

VOD Catalog Management

Catalog Import and Updates

V1/Catalogs|Catalogs

Lists available catalogs.

V1/Catalogs|Catalogs/{id}

Lists all content in a specified catalog.

Tip:

  • Paginate using:
    https://api.plurimedia.fr/v1/api/v1/catalogs/{id}?page=1
  • Response Headers:
    • X-Available-Pages: total pages available
    • X-Max-Page-Size: max items per page (up to 10,000)

V2/Contents|Contents/{id}

(Content Metadata)

For each content id returned by V1 Catalogs|Catalogs/{id}, 1 additional call must be made on V2/Content/{id} to get content’s metadata.
Returns data attached to the content ID passed in parameter.
This endpoint returns text, cast, images, collection ID + ID and lastupdate for Master and Season Content.

V2/Catalogs|CatalogsLastUpdated/{id}

Returns the list of content added or updated or removed from the catalog ID passed in parameter since the date passed in parameter.

Tip: After initializing a catalog with V1, only use this endpoint for subsequent updates.

VOD Order Submission

V1/Catalogs|VodOrder

Submit JSON-formatted orders to match your content with Plurimédia’s database for metadata linking.

Order API Response Codes:

  • 202: Order accepted and awaiting import.
  • 500: Error during upload; resend order.

Once the order has been matched, the matching result will be sent back to the API.
When the matching result is synchronized on the API, 2 solutions possibles :

  • The result can be sent to the client API. mina This result is materialised in a link between the customer’s assetID and Media Press’s unique ID. Several statuses can be transmitted in this response: INSERT, UPDATE, UNDO
  • The matched content is inserted into a VOD catalogue dedicated to the customer. All you have to do is use the dedicated endpoints to import the results.