Introduction
Jeu de caractères
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.
Requêtes HTTP / User Agent
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).
Erreurs
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>
Recherche
Présentation
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.
Adresse
http://www.dvdfr.com/api/search.php
Paramètres
| 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.
Résultats obtenus
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.
Fiche
Présentation
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.
Adresse
http://www.dvdfr.com/api/dvd.php
Paramètres
| 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. 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. |
Résultats obtenus
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.
Quotas
Présentation
Cette API permet de connaitre l'utilisation qui est faite de son quota d'appels à l'API fiche.
Adresse
http://www.dvdfr.com/api/quota.php?xml
Paramètres
Aucun si ce n'est le paramètre xml permettant de récupérer l'information sous forme d'API.
Résultats obtenus
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.