L'API DVDFr utilise des flux XML encodés en UTF-8. Toutes les requêtes doivent-être encodées dans ce même jeu de caractères.
Les appels à l'API doivent-être fait avec un USER_AGENT propre à votre logiciel. DVDFr se réserve la possibilité de filtrer les USER_AGENT génériques (vides ou correspondant à un navigateur ou une API HTTP générique).
Les erreurs sont renvoyées sous forme de flux XML. La structure de ces messages d'erreur est toujours la suivante :
<errors> <error type="[fatal|warning]"> <code>CODE_ERREUR</code> <message>Message d'erreur</message> </error> </errors>
Cette API permet de trouver la ou les fiches présentes dans notre base de données. Elle renvoit des informations permettant d'identifier la fiche intéressante sans avoir besoin de récupérer la fiche complète. Elle permet par exemple d'implémenter un moteur de recherche et de présenter les résultats à l'utilisateur du logiciel afin qu'il choisisse la fiche correspondant le mieux à sa demande.
http://www.dvdfr.com/api/search.php
Paramètre | Type | Description |
---|---|---|
title | Facultatif | Le nom de l'oeuvre à chercher dans la base DVDFr. Contrairement à la recherche intégrale sur le site la recherche s'effectue uniquement dans les champs "titre" de la base (titre / titre VO / titre alternatif / titre alternatif VO). Attention : l'article est stocké "à part" dans la base de données il faut donc le filtrer avant de lancer la recherche. Il est possible de grouper des mots en utilisant les guillemets doubles ("1001 pattes") |
gencode | Facultatif | Code barre (EAN-13) de la fiche à chercher. |
withActors | Facultatif | Si ce paramètre est positionné le flux XML de résultat de recherche inclura non seulement les réalisateurs mais aussi les acteurs. |
produit | Facultatif |
Si ce paramètre est positionné la recherche est filtrée par support. Les valeurs possibles sont :
|
Vous devez fournir au moins un paramètre de recherche (title ou gencode). Si vous ne spécifiez aucun paramètre de recherche vous générez l'erreur SEARCH_NOT_DEFINED.
Vous obtenez une liste de fiches. Pour des raisons de compatibilité ascendante, une fiche est identifiée par le tag XML <dvd> mais cela peut bien entendu être aussi un UMD, un Blu-ray ou un HD DVD.
<dvds generator="$Id: dvd.tpl 855 2008-08-04 15:53:24Z $"> <dvd> <id>6242</id> <media>DVD</media> <cover>https://www.dvdfr.com/images/dvd/covers/200x280/e60b4aa32dbdc98bd48c4081089f10b6/6242/old-1001_pattes_collector.0.jpg</cover> <titres> <fr>1001 pattes</fr> <vo>A Bug's Life</vo> <alternatif/> <alternatif_vo/> </titres> <annee>1998</annee> <edition>Édition Collector</edition> <editeur>Walt Disney France</editeur> <stars> <star type="Réalisateur" id="1840">John Lasseter</star> <star type="Réalisateur" id="1841">Andrew Stanton</star> </stars> </dvd> </dvds>
Vous obtenez donc l'identifiant DVDFr de la fiche, le média sur lequel il est disponible (DVD, UMD, Blu-ray, etc.), la liste des titres disponibles pour cette oeuvre, l'année du programme, l'édition, l'éditeur et la liste des réalisateurs. En option vous pouvez ajouter la liste des acteurs avec le paramètre optionnel withActors.
Cette API vous permet de récupérer les spécifications techniques d'un DVD (ou UMD / Blu-ray, etc.).
L'utilisation de cette API est limitée par un système de quotas (cf. utilisation des quotas). Le quota actuel est de 200 fiches par semaines. Il est possible de réinitialiser ce quota 5 fois. Tout appel à l'API fiche compte pour une utilisation de ce quota. Nous vous déconseillons donc d'appeler l'API fiche pour chaque résultat de recherche.
http://www.dvdfr.com/api/dvd.php
Paramètre | Type | Description |
---|---|---|
id | Obligatoire | Identifiant DVDFr de la fiche à récupérer. |
bandeAnnonce | Facultatif | Si ce paramètre est positionné renvoit les informations sur les bandes-annonces (URL, identifiant, etc.). Ne fonctionne que pour les appels signés à l'API. |
json | Facultatif / expérimental | Si ce paramètre est positionné, le résultat de l'appel à l'API sera renvoyé sous la forme d'un objet JSON au lieu d'un flux XML |
ts | Facultatif |
Utilisé pour les appels signés à l'API. Timestamp unix au moment où vous faites l'appel à l'API. |
key | Facultatif | Utilisé pour les appels signés à l'API. Nous contacter pour plus d'information à ce sujet. |
Vous obtenez un flux XML avec l'ensemble des caractéristiques techniques de la fiche. Ce flux n'est pas (encore) documenté ici-même mais devrait se suffire à lui-même. Sinon n'hésitez pas à contacter le responsable technique du site pour plus de renseignements.
Cette API permet de connaitre l'utilisation qui est faite de son quota d'appels à l'API fiche.
http://www.dvdfr.com/api/quota.php
Paramètre | Type | Description |
---|---|---|
xml | Facultatif | Récupération du résultat sous forme API au format XML |
json | Facultatif | Récupération du résultat sous forme API au format JSON |
ts | Facultatif |
Utilisé pour les appels signés à l'API. Timestamp unix au moment où vous faites l'appel à l'API |
key | Facultatif | Utilisé pour les appels signés à l'API. Nous contacter pour plus d'information à ce sujet. Utiliser 0 comme valeur d'ID pour signer vos appels. |
Pour récupérer les quotas dans un format exploitable par vos programmes, vous devez spécifier soit xml soit json dans votre appel à cette API
Vous obtenez sous forme XML les informations d'utilisation de votre quota. Vous ne pouvez pas utiliser l'API pour demander la remise à zéro de votre quota, il faut passer par le formulaire sur le site. L'adresse du formulaire est présente dans le flux de résultat :
<quotas generator="$Revision: 1360 $"> <fetchs> <used>2</used> <maximum>200</maximum> </fetchs> <resets> <used>0</used> <maximum>3</maximum> <url>http://www.dvdfr.com/api/quota.php</url> </resets> </quotas>
Ce flux est composé de deux informations : la première est liée au nombre d'appels effectués à l'API fiche (<fetchs>) et aux remises à zéro possible (<resets>). Chaque information est décomposée en nombre d'appels effectués (<used>) et en nombre d'appels maximum effectuables (<maximum>). L'URL permettant d'accéder au formulaire de réinitialisation des quotas est aussi donnée dans le flux.
API PRO uniquement. Cette API n'est utilisable que pour les abonnés pro aux API DVDFR. Pour vous abonner voir la page contact du site.
Cette API permet via un seul appel de recevoir les résultats pour plusieurs EAN en une seule fois. Vous consommez une unité de quota pour chaque EAN fourni en paramètre existant dans notre base. Si un EAN est invalide, une erreur est renvoyée par l'API.
http://www.dvdfr.com/api/productlist.php
Paramètre | Type | Description |
---|---|---|
ean[] | Obligatoire | Liste des EAN à interroger |
bandeAnnonce | Facultatif | Si ce paramètre est positionné renvoit les informations sur les bandes-annonces (URL, identifiant, etc.). |
json | Facultatif / expérimental | Si ce paramètre est positionné, le résultat de l'appel à l'API sera renvoyé sous la forme d'un objet JSON au lieu d'un flux XML |
ts | Obligatoire | Timestamp unix au moment où vous faites l'appel à l'API |
key | Obligatoire | Pour calculer votre clé, remplacer l'ID par la concaténation des EAN séparés par des , |
Vous obtenez une liste de produits. Chaque produit est conforme à la spécification individuelle de l'API dvd décrite précédemment.
Cette API permet de connaitre l'utilisation qui est faite de son quota d'appels à l'API fiche.
http://www.dvdfr.com/api/quota.php
Paramètre | Type | Description |
---|---|---|
xml | Facultatif | Récupération du résultat sous forme API au format XML |
json | Facultatif | Récupération du résultat sous forme API au format JSON |
ts | Facultatif | Utilisé pour les appels signés à l'API. Nous contacter pour plus d'information à ce sujet. |
key | Facultatif | Utilisé pour les appels signés à l'API. Nous contacter pour plus d'information à ce sujet. Utiliser 0 comme valeur d'ID pour signer vos appels. |
Pour récupérer les quotas dans un format exploitable par vos programmes, vous devez spécifier soit xml soit json dans votre appel à cette API