The Secret Circle S01E15 — Return
Si vous êtes un amateur de séries, vous savez à quel point il est difficile de rester à jour simplement dans ses épisodes. Entre les semaines de vacances et les séries qui reprennent sans prévenir, c'est parfois un enfer.
Grâce à BetaSeries, vous pouvez enfin gérer vos séries de A à Z : De la gestion de votre planning au téléchargement des derniers sous-titres, en passant par la découverte de nouvelles séries... Tout cela entouré de la communauté BetaSeries ainsi que de vos amis, directement sur le site !
Tout le site est gratuit, et sans aucune publicité.
Vous trouverez ci-dessous la documentation de l'API BetaSeries :
Méthodes :
Les appels à l'API doivent être faits sous la forme de requêtes HTTP en GET ou POST sur le domaine api.betaseries.com, par exemple :
GET/POST http://api.betaseries.com/shows/display/dexter.(xml|json)
Le format de retour est au choix XML, JSON ou JSONP, ce qui ressemble en général à ceci :
<root>
( ... réponse ... )
<code>1</code>
<errors />
</root>
{"root":{( ... réponse ... ),"code":1,"errors":[]}}
Si vous ajoutez un paramètre callback à votre requête HTTP, le JSON se transforme en JSONP :
callback({"root":{( ... réponse ... ),"code":1,"errors":[]}})
code est égal à 1 si l'appel s'est déroulé avec succès, sinon 0.
errors contient plus d'informations sur les erreurs rencontrées en cas de code 0.
Les retours XML ou JSON ne seront pas ou peu documentés, ils sont assez explicites. :)
Pour savoir les dernières modifications des fonctions et le statut global de BetaSeries, utilisez /status :
GET http://api.betaseries.com/status.xml
Vous pouvez voir un changelog plus détaillé sur le [Changelog|Changelog].
Pour toutes vos requêtes, vous devez mentionner votre clé API dans la requête, avec le paramètre key :
?key=<key>
Ce paramètre est obligatoire pour permettre d'éviter les éventuels abus sur l'utilisation de l'API.
Lorsque vous avez besoin d'interagir avec un compte membre, vous devez d'abord identifier ce membre avec la fonction /members/auth. Une fois l'identification effectuée, vous récupérez un token qui vous servira dans toutes les requêtes suivantes, à placer en paramètre.
?token=<token>
Vous pouvez à tout moment détruire le token grâce à /member/destroy.
Il est recommandé de spécifier un User-Agent spécifique à votre application dans vos requêtes. De ce fait, si vous utilisez votre clé pour plusieurs applications, il nous sera plus facile de différencer votre trafic.
Pour tester vos applications des comptes de test ont été créés. Leurs données sont réinitialisées toutes les nuits à 4 heures du matin. Ces comptes sont les suivants :
Nous vous conseillons de modifier le mot de passe du compte de test que vous souhaitez utiliser pour ne pas vous écraser entre développeurs !
Les utilisateurs ont entre 1 et 10 amis développeurs ajoutés automatiquement, ainsi que les options suivantes :
Note : Rien ne vous empêche de créer vos propres comptes de test :) mais pensez à supprimer au maximum leurs actions pour ne pas polluer le site de fausses données.
Pour pouvoir tester la plupart des actions sur les séries proposées par l'API sans polluer le site, vous pouvez maintenant utiliser la série créée spécialement pour l'occasion :
Si vous souhaitez participer en rajoutant des descriptions des épisodes, contactez-moi :)
Les codes d'erreur retournés par l'API consistent en 4 caractères numériques : XYYY où X est le type d'erreur et YYY l'erreur en elle-même.
<errors>
<error>
<code>XYYY</code>
<content>Texte de l'erreur</content>
</error>
</errors>
1003 : Action invalide
2 : Erreurs utilisateur
2007 : Les options de l'utilisateur ne sont pas valides
3 : Erreurs de variable
3006 : Adresse e-mail invalide
4 : Erreurs de la base
On est des mecs bien, cependant il y a quelques règles à respecter pour que cette API fonctionne au mieux :
En utilisant l'API avec votre clé, vous acceptez implicitement ces conditions d'utilisation.
GET http://api.betaseries.com/shows/search.xml?title=<search>
Liste les séries qui contiennent exactement la portion search dans leur titre.
shows: show*
show:
string url: url of the show
string title: name of the show
GET http://api.betaseries.com/shows/display/<url>.xml
Donne des informations sur la série (identifiée par son url).
Note : Si url est à all, la fonction retourne toutes les séries de BetaSeries.
show:
string title: title of the show
int id_thetvdb: id of the show on tvdb
string url: url of the show
text description: description of the show
enum status: status of the show (Continuing, Ended, On Hiatus, Other)
url banner: image of the show
list seasons: season*, list of seasons and number of episodes
list genres: genre*, list of genres
string genre: a genre for the show
note:
int members: number of members who gave a note
float mean: mean of the total notes
int self: note given by the authenticated user
GET http://api.betaseries.com/shows/episodes/<url>.xml<?season=N><&episode=N><&summary=1>
Liste les épisodes d'une série donnée. Vous pouvez préciser une saison (et un épisode) en paramètre.
Si le paramètre summary est spécifié, la description et la capture d'écran de l'épisode ne seront pas retournées.
Note : Si vous spécifiez un token, vous saurez si le membre identifié a vu cet épisode ou non.
seasons: season*
season:
int number: number of the season
list episodes: episode*, list of episodes
episode:
int episode: number of the episode
string number: number of the episode with the season
timestamp date: date of the episode
string title: title of the episode
text description: description of the episode
url screen: a screen of the episode
bool has_seen: did the user see the episode
note:
int members: number of members who gave a note
float mean: mean of the total notes
int self: note given by the authenticated user
GET http://api.betaseries.com/shows/add/<url>.xml
Ajoute la série dans le compte du membre identifié.
GET http://api.betaseries.com/shows/remove/<url>.xml
Retire la série du compte du membre identifié.
GET http://api.betaseries.com/shows/recommend/<url>.xml?friend=<login>
Recommande une série à un des amis de l'utilisateur identifié.
GET http://api.betaseries.com/shows/archive/<url>.xml
Archive une série pour l'utilisateur identifié.
GET http://api.betaseries.com/shows/unarchive/<url>.xml
Sort des archives une série pour l'utilisateur identifié.
GET http://api.betaseries.com/shows/characters/<url>.xml(?summary=1)(&id=N)
Affiche les fiches personnages pour la série spécifiée. Si vous spécifiez summary, seuls l'id et le nom du personnage seront renvoyés. Vous pouvez ne demander qu'une seule fiche personnage en spécifiant son id.
GET http://api.betaseries.com/shows/similar/<url>.xml
Retourne les séries similaires à la série soumise.
GET http://api.betaseries.com/subtitles/last.xml<?number=N><&language=(VO|VF)>
Affiche les derniers sous-titres récupérés par BetaSeries, dans la limite de 100. Possibilité de spécifier la langue et/ou une série en particulier.
subtitles: subtitle*
subtitle:
string title: title of the episode
int season: number of the season of the episode
int episode: number of the episode
string language: language of the subtitle
enum source: source of the subtitle (addic7ed, seriessub, soustitres, tvsubtitles, usub)
file file: name of the file of the subtitle
url url: url to the subtitle
int quality: quality of the subtitle (1 the worst, 5 the best)
GET http://api.betaseries.com/subtitles/show/<url>.xml<?language=(VO|VF)><&season=N><&episode=N>
Affiche les sous-titres récupérés par BetaSeries d'une certaine série, dans la limite de 100. Possibilité de spécifier la langue et/ou une saison, un épisode en particulier.
Nouveau : Vous pouvez maintenant récupérer des sous-titres directement grâce au nom des fichiers vidéo :
GET http://api.betaseries.com/subtitles/show.xml?file=X<&language=(VO|VF)>
subtitles: subtitle*
subtitle:
string title: title of the episode
int season: number of the season of the episode
int episode: number of the episode
string language: language of the subtitle
enum source: source of the subtitle (addic7ed, seriessub, soustitres, tvsubtitles, usub)
file file: name of the file of the subtitle
url url: url to the subtitle
int quality: quality of the subtitle (1 the worst, 5 the best)
GET http://api.betaseries.com/planning/general.xml
Affiche tous les épisodes diffusés les 8 derniers jours jusqu'aux 8 prochains jours.
planning: episode*
episode:
string number: number of the episode with the season
int season: season number of the episode
int episode: number of the episode
timestamp date: date of the episode
string show: name of the show of the subtitle
string url: url of the show
string title: title of the episode
GET http://api.betaseries.com/planning/member[/<login>].xml<?view=unseen>
Affiche le planning du membre identifié ou d'un autre membre (l'accès varie selon les options vie privée de chaque membre). Vous pouvez rajouter le paramètre view pour n'afficher que les épisodes encore non-vus.
planning: episode*
episode:
string number: number of the episode with the season
int season: season number of the episode
int episode: number of the episode
timestamp date: date of the episode
string show: name of the show of the subtitle
string url: url of the show
string title: title of the episode
GET http://api.betaseries.com/members/auth.xml?login=<login>&password=<md5>
Identifie le membre avec son login et le hash MD5. Retourne le token à utiliser pour les requêtes futures.
GET http://api.betaseries.com/members/oauth.xml
Récupère une clé à utiliser en paramètre de https://www.betaseries.com/oauth?key=<key> pour identifier l'utilisateur sans avoir à envoyer un mot de passe sur l'API. L'utilisateur est ensuite redirigé sur l'URL de callback que vous avez spécifiée.
GET http://api.betaseries.com/members/is_active.xml
Fonction sans action si ce n'est celle de vérifier si le token spécifié est actif.
GET http://api.betaseries.com/members/destroy.xml
Détruit instantanément le token spécifié.
GET http://api.betaseries.com/members/infos[/<login>].xml<?nodata=1><&since=N>
Renvoie les informations principales du membre identifié ou d'un autre membre (l'accès varie selon les options vie privée de chaque membre). Si vous spécifiez le paramètre nodata, seuls le login et la date du cache seront retournés. Si vous spécifiez le paramètre since (valeur timestamp), l'API ne renverra les informations complètes que si elles ont été mises à jour depuis.
member:
string login: login of the member
timestamp cached: date of last cached data
url avatar: url to the avatar
stats:
int shows: number of shows followed
int seasons: number of seasons
int episodes: number of episodes
string progress: general progress
int episodes_to_watch: number of episodes to watch
timestamp time_on_tv: minutes spended watching shows
timestamp time_to_spend: remaining time to spend
int badges: number of badges
shows: show*
options:
boolean downloaded: has the "mark as downloaded" option enabled
boolean notation: has the notation option enabled
boolean decalage: has the decalage option enabled
show:
string url: url of the show
string title: title of the show
boolean archive: show archived (1), or not (0)
GET http://api.betaseries.com/members/episodes/(all|vf|vovf).xml<?show=X><&view=next|NN>
Liste les épisodes restant à regarder du membre identifié. Vous pouvez affiner par type de sous-titres : Tous (même les épisodes sans sous-titres), VF ou VF et VO. En spécifiant view=next, l'API ne retourne que le premier épisode de chaque série à regarder.
Si vous spécifiez un nombre à view, les NN prochains épisodes seront retournés.
Si vous spécifiez show, les épisodes à voir de cette série uniquement seront retournés.
episodes: episode*
episode:
string show: name of the show
string episode: episode of the shwo with the season
string url: url of the show
string title: title of the episode
timestamp date: date of the episode
bool downloaded: whether has the user marked the episode as downloaded or not
GET http://api.betaseries.com/members/watched/<url>.xml?season=<N>&episode=<N><¬e=N>
Marque l'épisode episode de la saison season de la série url comme vu. Vous pouvez spécifier une note entre 1 et 5.
Note : Si l'épisode marqué comme vu ne suit pas directement le précédent épisode vu, tous les épisodes entre les deux seront quand même marqués comme vus. Pour mettre à zéro une série, marquez l'épisode 0 de la saison 0.
GET http://api.betaseries.com/members/note/<url>.xml?season=<N>&episode=<N>¬e=<N>
Donne une note entre 1 et 5 à l'épisode episode de la saison season de la série url.
Note : Pour noter la série entière, il faut indiquer episode=0 et season=0.
GET http://api.betaseries.com/members/downloaded/<url>.xml?season=<N>&episode=<N>
Marque l'épisode episode de la saison season de la série url comme récupéré.
GET http://api.betaseries.com/members/notifications.xml(<?summary=yes>|<&number=N><&last_id=N><&sort=(asc|desc)>)
Afficher dans l'ordre chronologique les notifications reçues par le membre (nouveaux sous-titres, nouveaux épisodes sortis, etc.). En paramètres il peut être spécifié de commencer à partir d'un certain ID ou encore de limiter le nombre de résultats.
Nous vous conseillons de ne pas utiliser l'argument "sort" si vous utilisez déjà "last_id", vous risqueriez de ne pas récupérer toutes les dernières notifications.
Note : Si vous utilisez le paramètre "summary", l'API ne retournera que le nombre de notifications non-vues.
Note : Chaque notification retournée par l'API sera automatiquement marquée comme vue et supprimée.
notifications: notification*
notification:
int id: id of the notification
text html: content of the notification
timestamp date: date of the notification
GET http://api.betaseries.com/members/option/<option>.xml[?value=<value>]
Pour voir (ou modifier si value est renseigné à 1 ou 0) l'option d'un membre identifié.
Options autorisées en lecture : downloaded, notation, decalage
Options autorisées en écriture : downloaded, notation, decalage
GET http://api.betaseries.com/members/signup.xml?login=<login>&password=<password>&mail=<mail>
Crée instantanément un compte avec les identifiants et le mail spécifiés. (Taille maximale pour le login : 24 caractères)
GET http://api.betaseries.com/members/friends</login>.xml
Retourne la liste d'amis soit de l'utilisateur identifié par son token, soit de l'utilisateur spécifié dans l'URL.
GET http://api.betaseries.com/members/badges</login>.xml
Retourne la liste des badges soit de l'utilisateur identifié par son token, soit de l'utilisateur spécifié dans l'URL.
GET http://api.betaseries.com/members/add/<login>.xml
Ajoute un utilisateur comme ami.
GET http://api.betaseries.com/members/delete/<login>.xml
Enlève un utilisateur des amis de l'utilisateur identifié.
GET http://api.betaseries.com/members/search.xml?login=<search>
Liste les 10 premiers membres dont le pseudo commence par le terme login.
members: member*
member:
string login: member login
GET http://api.betaseries.com/members/block/<login>.xml
Bloque le membre spécifié.
GET http://api.betaseries.com/members/unblock/<login>.xml
Débloque le membre spécifié.
GET http://api.betaseries.com/members/options.xml
Récupère les options du membre. Pour le moment, les sources de sous-titres qu'il a sélectionnées.
GET http://api.betaseries.com/comments/show/<url>.xml
Affiche les commentaires de la série spécifiée.
comments: comment*
comment:
string login: login of the user who has posted the comment
int date: date of the comment
string text: content of the comment
int inner_id: internal id of the comment
int in_reply_to: comment id of the replied comment
GET http://api.betaseries.com/comments/episode/<url>.xml?season=N&episode=N
Affiche les commentaires de l'épisode spécifié.
GET http://api.betaseries.com/comments/member/<login>.xml
Affiche les commentaires du membre spécifié.
GET http://api.betaseries.com/comments/post/show.xml?show=X&text=X<&in_reply_to=N>
Poste un commentaire sur la fiche d'une série. Vous pouvez spécifier s'il s'agit d'une réponse à un autre commentaire en précisant son ID.
GET http://api.betaseries.com/comments/post/episode.xml?show=X&season=N&episode=N&text=X<&in_reply_to=N>
Poste un commentaire sur la fiche d'un épisode. Vous pouvez spécifier s'il s'agit d'une réponse à un autre commentaire en précisant son ID.
GET http://api.betaseries.com/comments/post/member.xml?member=X&text=X<&in_reply_to=N>
Poste un commentaire sur le profil d'un membre. Vous pouvez spécifier s'il s'agit d'une réponse à un autre commentaire en précisant son ID.
GET http://api.betaseries.com/timeline/home.xml<?number=N>
Affiche les N derniers évènements du site. Maximum 100.
timeline: item*
item:
enum type: type of the item (friend_add, friend_delete, markas, add_serie, del_serie, archive,
unarchive, recommandation, recommandation_decline, recommandation_accept,
inscription, update, subtitles, comment, badge)
string ref: reference for the item
string login: login of the user
text html: content of the item
timestamp date: date of the item
data:
string number: episode number if type is: markas, comment
string url: episode url if type is: markas
string title: episode title if type is: markas
data:
int note: a mark (from 1 to 5) if type is: markas
GET http://api.betaseries.com/timeline/friends.xml<?number=N>
Affiche les N derniers évènements des amis du membre identifié. Maximum 100.
timeline: item*
item:
enum type: type of the item (friend_add, friend_delete, markas, add_serie, del_serie, archive,
unarchive, recommandation, recommandation_decline, recommandation_accept,
inscription, update, subtitles, comment, badge)
string ref: reference for the item
string login: login of the user
text html: content of the item
timestamp date: date of the item
GET http://api.betaseries.com/timeline/member/<login>.xml<?number=N>
Affiche les N derniers évènements de login (l'accès varie selon les options vie privée de chaque membre). Maximum 100.
timeline: item*
item:
enum type: type of the item (friend_add, friend_delete, markas, add_serie, del_serie, archive,
unarchive, recommandation, recommandation_decline, recommandation_accept,
inscription, update, subtitles, comment, badge)
string ref: reference for the item
string login: login of the user
text html: content of the item
timestamp date: date of the item
GET http://api.betaseries.com/messages/inbox.xml<?page=N>
Affiche la liste derniers messages dans la boîte de réception dans l'ordre antéchronologique, par page de 15.
GET http://api.betaseries.com/messages/discussion/<id>.xml<?page=N>
Affiche les messages de la discussion spécifiée dans l'ordre chronologique, par page de 15.
GET http://api.betaseries.com/messages/send.xml?message=<message><&title=X&recipient=X|&discussion_id=N>
Envoie un nouveau message, soit démarre une discussion en spécifiant title et récipient, soit une réponse à une discussion en spécifiant discussion_id.
Note : Préférez envoyer cette requête en POST pour éviter des erreurs avec les paramètres.
Note : Ces trois fonctions ne renvoient PAS de XML ou JSON℗, il s'agit directement des images en JPG.
GET http://api.betaseries.com/pictures/show/<show>.jpg
Retourne l'image correspondant à la série, si elle existe.
GET http://api.betaseries.com/pictures/episode/<show>.jpg?season=<N>&episode=<N>
Retourne l'image correspondant à l'épisode, si elle existe.
GET http://api.betaseries.com/pictures/member/<login>.jpg
Retourne l'avatar du membre, s'il existe.
Bonjour. N'y aurait-il pas un bug avec l'api de /members/episodes ? Lorsque l'on rajoute une série via le site, l'API ne remonte pas cette série dans la liste des épisodes à regarder. J'ai testé avec mon compte et avec des comptes de tests.
Comment fait on pour marquer un episode comme non vu ?
(Le premier épisode de de la première saison ?)
Pour laisser un commentaire, vous devez avoir un compte sur BetaSeries. Si vous n'êtes pas déjà inscrit, c'est très simple et ne prend que quelques secondes.
La crise sous toutes ses formes : Du petit au grand écran
Pour les fans, voir sa série portée à l’écran relève d’une haute récompense. C’est quelque part, la consécration de la réussite, de la qualité de la série.
(Concours) BetaSeries sur SubsMarine pour Mac OS X
SubsMarine, le client Mac pour trouver automatiquement des sous-titres, vient d'ajouter BetaSeries à ses services.
Grâce à BetaSeries, vous pouvez enfin gérer vos séries de A à Z : De la gestion de votre planning au téléchargement des derniers sous-titres, en passant par la découverte de nouvelles séries... Tout cela entouré de la communauté BetaSeries ainsi que de vos amis, directement sur le site !
BetaSeries.com réalisé par Maxime VALETTE
© 2008-2012.
La documentation n'a pas l'air à jour sur la partie "Code d'erreur". Il est indiqué qu'on devrait recevoir un texte de cette forme :
<errors>
<error code="XYYY">Texte de l'erreur</error>
</errors>
Mais ce que je reçois dans mon appli est de la forme :
<errors>
<error>
<code>XYYY</code>
<content>Texte de l'erreur</content>
</error>
</errors>
Je peux modifier la doc par moi-même mais je préfère m'assurer que c'est correct avant de faire des bêtises :).