L'endpoint videolists permet de récupérer une ou plusieurs playlists et leurs vidéos avec leurs métadonnées. Il constitue le point d'entrée principal pour tout affichage de contenu structuré par playlist : carrousel, portail vidéo, page thématique.
Base URL
https://www.ultimedia.com/api/search/getvideolistsMéthode : GET Format de réponse : JSON Authentification : clé mdtk passée en paramètre de chemin
GET /api/search/getvideolists/datatype/json/mdtk/{mdtk}/zone/{zone}/videolistid/{videolistid}Les paramètres sont passés dans le chemin de l'URL (path parameters), pas en query string.
| Paramètre | Type | Description |
|---|---|---|
datatype |
string | Format de réponse. Valeur fixe : json |
mdtk |
string | Identifiant de votre site Digiteka qui servira à l'intégration des vidéos |
zone |
integer | Zone de diffusion. Valeur standard : 1 |
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
videolistid |
string | Identifiant de la playlist cible | |
filter_mdtk |
string | Filtre sur les MDTK. Retourne uniquement les playlists rattachées aux MDTK fournis. | |
perpage |
integer | 20 |
Nombre de vidéos retournées par page. Maximum recommandé : 50 |
page |
integer | 1 |
Numéro de page pour la pagination |
{
"date": "2026-05-20 16:38:22",
"nb_result": 201,
"nb_page": 21,
"results": [
{
"videolist_id": "xxxxx",
"videolist_name": "Nom de playlist",
"site": {
"mdtk": "0123456",
"name": "Nom du site"
},
"videolist_metadata": {
"description": "",
"thumbnail": "https://vod.digiteka.com/playlists/xxxxxx/ffd790...png",
"extradata": []
},
"nb_videos": 201,
"videos": [ ... ]
}
]
}
| Champ | Type | Description |
|---|---|---|
date |
string | Horodatage de la réponse serveur (YYYY-MM-DD HH:MM:SS) |
nb_result |
integer | Nombre total de vidéos dans la playlist, toutes pages confondues |
nb_page |
integer | Nombre total de pages disponibles selon la valeur de perpage |
results |
array | Tableau des playlists retournées |
results[] — Playlist| Champ | Type | Description |
|---|---|---|
videolist_id |
string | Identifiant unique de la playlist |
videolist_name |
string | Nom de la playlist tel que défini dans l'interface Digiteka |
site.mdtk |
string | Identifiant du site auquel appartient la playlist |
site.name |
string | Nom du site |
videolist_metadata.description |
string | Description de la playlist (peut être vide) |
videolist_metadata.thumbnail |
string (URL) | Vignette associée à la playlist, pleine résolution |
videolist_metadata.extradata |
array | Tableau de métadonnées custom configurables depuis l'interface (ex. position d'affichage, label visuel) |
nb_videos |
integer | Nombre total de vidéos dans la playlist |
videos |
array | Vidéos de la page courante (paginées selon perpage) |
videos[] — Vidéo| Champ | Type | Description |
|---|---|---|
video_id |
string | Identifiant unique de la vidéo |
label |
string | Nom du catalogue |
orientation |
string | Format de la vidéo : horizontal ou vertical |
| Champ | Type | Description |
|---|---|---|
creation_date |
string | Date de création, format lisible (YYYY-MM-DD HH:MM:SS) |
creation_time |
string | Date de création, timestamp Unix |
begin_time |
string | Timestamp de début de disponibilité |
edition_time |
string | Timestamp de dernière modification |
| Champ | Type | Description |
|---|---|---|
title |
string | Titre de la vidéo |
description |
string | Description courte (peut être vide) |
enriched_description |
string | Description enrichie, peut contenir du HTML |
authors |
string | Auteur(s) de la vidéo (peut être vide) |
views |
string | Nombre de vues |
lengthvideo |
string | Durée de la vidéo en secondes |
Quatre résolutions sont disponibles pour chaque vidéo.
| Champ | Dimensions | Usage recommandé |
|---|---|---|
image |
134×100 px | Miniature en liste compacte |
image_high |
480×360 px | Grille de vignettes standard |
image_large |
858×480 px | Carrousel, affichage élargi |
image_original |
Variable | Résolution native, soumise par le journaliste |
| Champ | Type | Description |
|---|---|---|
embed |
string (HTML) | Balise <script> prête à l'emploi pour intégration JavaScript |
iframe |
string (HTML) | Balise <iframe> prête à l'emploi, recommandée en contexte webview |
url_preview |
string (URL) | Extrait MP4 court pour prévisualisation sans instancier le player |
Les champs iframe et embed sont retournés pré-formatés par l'API. Ils peuvent être injectés directement dans le DOM.
Intégration iFrame — recommandée en contexte webview mobile :
<iframe
width="100%"
height="100%"
src="https://www.ultimedia.com/deliver/generic/iframe/mdtk/{mdtk}/zone/1/src/{video_id}"
frameborder="0"
scrolling="no"
allowfullscreen
allow="autoplay"
referrerpolicy="no-referrer-when-downgrade">
</iframe>Intégration JavaScript — si l'environnement exécute du JS :
<script
type="text/javascript"
src="https://www.ultimedia.com/deliver/generic/js/mdtk/{mdtk}/src/{video_id}/zone/1/">
</script>
| Cas | Comportement observé |
|---|---|
mdtk invalide |
Réponse vide (nb_result: 0, results: []) |
videolistid inexistant |
Réponse vide (nb_result: 0, results: []) |
page hors limite |
videos: [], les champs racine restent valides |
Paramètre perpage absent |
Valeur par défaut appliquée (20) |
L'API retourne toujours un HTTP
200. La détection d'erreur doit se faire en vérifiantnb_resultet la taille du tableauresults.
Cache — les playlists étant mises à jour manuellement depuis l'interface Digiteka, un TTL de cache de 5 à 10 minutes est adapté pour les appels d'accueil. Ne pas descendre en dessous de 1 minute pour éviter une charge inutile.
Choix de la vignette — privilégier
image_largepour les affichages principaux (carrousel, hero),image_highpour les grilles,imagepour les listes compactes.
Champ
orientation— permet d'adapter le ratio du conteneur player (16:9pourhorizontal,9:16pourvertical) avant même l'initialisation du player, évitant tout layout shift.
Champ
url_preview— fichier MP4 léger exploitable pour un autoplay muet au survol ou au scroll, sans charger le player complet. Attention à la gestion de la bande passante sur mobile.
Champ
extradata— tableau libre configurable depuis Vidéos > Mes playlists dans l'interface Digiteka. Peut accueillir n'importe quelle paire clé/valeur : position d'affichage, couleur de thème, slug, etc. La structure du contenu est définie par votre équipe.
Champ
lengthvideo— retourné en secondes sous forme de string. Penser à le caster en entier (parseInt) avant tout calcul ou formatage d'affichage.