Many, many months ago, we worked with API calls for Weather Underground. Actually, it was in part 11 which was back in issue #37. Well, we are going to deal with APIs again, this time for a website named TVRage (http://tvrage.com). If you aren’t familiar with this site, it deals with television shows. So far, every TV show that I could think of has been in their system. In this series of articles, we are going to revisit XML, APIs, and ElementTree to create a wrapper library that will allow us to create a small library which simplifies our retrieval of TV information on our favorite shows.

Il y a plusieurs longs mois, nous avons travaillé avec des appels d'API pour Weather Underground. En fait, c'était dans la partie 11, parue dans le numéro 37. Eh bien, nous allons à nouveau traiter d'API, cette fois pour un site web nommé TVRage (http://tvrage.com). Si vous ne connaissez pas ce site, il traite des émissions de télévision. Jusqu'à présent, toutes les émissions télévisées auxquelles je pouvais penser étaient dans leur système. Dans cette série d'articles, nous allons revenir sur XML, les API et ElementTree pour créer une couche d'abstraction qui nous permettra de créer une petite bibliothèque qui simplifiera notre recherche d'information sur nos émissions préférées.

Now, I mentioned a wrapper library. What’s that? In simple terms, when you create or use a wrapper library, you are using a set of code that “wraps” the complexity of the website’s API into an easy-to-use library. Before we get started, I need to make a few things clear. First, this is a free service. However, they do request donations for use of their API. If you feel that this is a worthwhile service, please consider donating $10 US or more. Second, you should register at their website and get your own API key. It’s free, so there’s really no reason not to, especially if you are going to use the information provided here. In addition, you have access to a few other fields of information like series and episode summaries that are not included in the unregistered version. Third, they are hard at work at updating the API. This means that when you get to seeing this article, their API might have changed. We’ll be using the public feeds, which are free for everyone to use as of December 2012. The API website is located at http://services.tvrage.com/info.php?page=main and shows a few examples of the types of information that are available.

Bon, j'ai mentionné une couche d'abstraction. Qu'est-ce que c'est ? En termes simples, lorsque vous créez ou utilisez une bibliothèque, vous utilisez des morceaux de code qui « enveloppent » la complexité de l'API du site Web dans une bibliothèque facile à utiliser. Avant de commencer, je dois éclaircir quelques petites choses. Tout d'abord, il s'agit d'un service gratuit. Cependant, ils demandent des dons pour l'utilisation de leur API. Si vous pensez que c'est un service utile, prière d'envisager de faire un don de 8 € ou plus. Deuxièmement, vous devez vous inscrire sur leur site et obtenir votre clé personnelle pour l'API. C'est gratuit, donc il n'y a vraiment aucune raison de ne pas le faire, surtout si vous envisagez d'utiliser les informations fournies. En outre, vous avez accès à quelques autres champs d'information comme les résumés des séries et des épisodes qui ne sont pas inclus dans la version sans inscription. Troisièmement, ils sont à pied d'œuvre sur la mise à jour de l'API. Cela signifie que quand vous lirez le présent article, leur API peut avoir changé. Nous allons utiliser les flux publics, qui sont gratuits pour tout le monde depuis décembre 2012. Le site de l'API est situé à http://services.tvrage.com/info.php?page=main et montre quelques exemples des types d'informations qui sont disponibles.

Now, let’s begin looking at the API and how we can use it. Using their API, we can get very specific information about the show itself and/or we can get episode level information. There are basically three steps to finding information about TV Shows. Here are the steps: • Search their database looking for the show name to get the specific Show ID which must be used to get more data. Think of the showid value as a key directly into a record set in a database, which in this case it is. • Once you have the Show ID, obtain the show level information. • Finally, gather the information about a specific episode. This comes from a list of each and every episode that the show has had to date.

Bon, commençons à regarder l'API pour voir comment nous pouvons l'utiliser.

En utilisant leur API, nous pouvons obtenir des informations très précises sur l'émission elle-même et/ou sur chacun des épisodes. Il faut en fait trois étapes pour trouver des informations sur une émission. Les voici : • Rechercher dans leur base de données le nom de l'émission pour obtenir son identifiant (« Show ID ») que l'on doit utiliser pour obtenir plus de données. Pensez à la valeur showid comme une clé permettant d'accéder directement à un enregistrement dans la base de données ; c'est exactement ça. • Une fois que vous avez l'ID, obtenez les informations sur l'émission. • Enfin, recherchez les informations sur un épisode spécifique. Elles viendront d'une liste des épisodes de l'émission jusqu'à aujourd'hui.

There are three basic web calls we will make to get this information. First is the search call, second the show information call, and finally the the episode list call. Here are the base calls that we will use… • Search for ShowID based on a show name - http://services.tvrage.com/feeds/search.php?show={SomeShow} • Pull the show level data based on the Show ID (sid) - http://services.tvrage.com/feeds/showinfo.php?sid={SomeShowID} • Pull the episode list for Show ID (sid) - http://services.tvrage.com/feeds/episode_list.php?sid={SomeShowID}

Nous utiliserons trois appels web de base pour obtenir cette information. Le premier pour la recherche, le deuxième pour les informations sur l'émission et le dernier pour obtenir la liste des épisodes.

Voici les appels de base que nous allons utiliser : • Recherche de l'identifiant ShowID à partir du nom de l'émission - http://services.tvrage.com/feeds/search.php?show={UneEmission}

• Récupération des données de l'émission à partir du ShowID (sid) - http://services.tvrage.com/feeds/showinfo.php?sid={UnIdentifiant}

• Récupération de la liste des épisodes pour ShowID (sid) - http://services.tvrage.com/feeds/episode_list.php?sid={UnIdentifiant}

What gets returned is a stream of data in XML format. Let’s take a moment to review what XML looks like. The first line should always be similar to the one shown below to be considered a proper XML data stream (below). Every piece of data is enclosed within a defining tag and end-tag. Sometimes you will have a child tag that is a parent tag in itself like this… <CHILD PARENT TAG> <CHILD TAG 1>DATA</CLOSING CHILD TAG 1> </CLOSING CHILD PARENT TAG> You also may see a tag that has an attribute associated with it: <TAG INFORMATION = VALUE> <CHILD TAG>DATA</CLOSING CHILD TAG> </CLOSING TAG>

On reçoit en retour un flux de données au format XML. Prenons un moment pour revoir à quoi ressemble XML. La première ligne doit toujours être similaire à celle illustrée ci-dessous pour être considérée comme un bon flux de données XML (ci-dessous).

Chaque donnée est entourée par une balise de définition et une balise de fin. Parfois, vous aurez une balise enfant qui est aussi elle-même une balise parent comme ceci :

<BALISE ENFANT PARENT>

<BALISE ENFANT 1>DONNÉES</FIN DE BALISE ENFANT 1>

</FIN DE BALISE ENFANT PARENT>

Vous pouvez également trouver une balise à laquelle est associé un attribut :

<BALISE INFORMATION = VALEUR>

<BALISE ENFANT>DONNÉES</FIN BALISE ENFANT>

</FIN BALISE>

Sometimes, you might see a tag with no data associated with it. It would come across like this… <prodnum/> Sometimes, if there is no information for a specific tag, the tag itself just won’t be there. Your program will have to deal with these possibilities. So, when we go through and deal with the XML data, we start with the root tag, and parse each tag – looking for the data we care about. In some instances we want everything; in others, we care about only certain pieces of the information. Now, let’s look at the first call and see what gets returned. Assume the show we are looking for is Buffy the Vampire Slayer. Our search call would look like this: http://services.tvrage.com/feeds/search.php?show=buffy

Parfois, vous pourrez voir une balise sans données associées. Cela ressemblera à ceci :

<prodnum/>

Parfois, s'il n'y a pas d'information pour une certaine balise, cette balise ne sera tout simplement pas présente. Votre programme devra faire face à ces possibilités.

Donc, pour recevoir et traiter les données XML, nous commençons par la balise racine et analysons chaque balise, à la recherche des données qui nous intéressent. Dans certains cas, nous voulons tout récupérer, dans d'autres nous nous préoccupons seulement de certains morceaux de l'information.

Maintenant, penchons-nous sur le premier appel et regardons ce qui est retourné. Supposons que l'émission que nous cherchons est Buffy contre les vampires. Notre appel de recherche devrait ressembler à ceci :

http://services.tvrage.com/feeds/search.php?show=buffy

The returned XML file would look like this: http://pastebin.com/Eh6ZtJ9N. Note that I put the indents in myself to make it easier for you to read. Now let’s break down the XML file to see what we actually have. <Results> - This is the ROOT of the XML data. The last line of the stream we get back should be the closing tag </Results>. Basically, this marks the beginning and end of the XML stream. There could be zero results or fifty results. <show> This is the parent node that says “What follows (until the end show tag) is the information about a single tv show”. Again, it’s ended by its end tag </show>. Anything within these two tags should be considered one show’s worth of information. <showid>2930</show> This is the showid tag. This holds the sid that we have to use to get the show information, in this case 2930. <name>Buffy the Vampire Slayer</name> This is the name of the show <link>…</link> This would be the link to the show itself (or, in the case of an episode, the episode information) on the TVRage website. <country>…</country> The country of origin for the show. … </show> </Results>

Le fichier XML retourné devrait ressembler à ceci : http://pastebin.com/Eh6ZtJ9N.

Notez que j'ai indenté moi-même pour vous faciliter la lecture. Maintenant, nous allons décomposer le fichier XML pour voir ce qu'il contient.

<Results> - Il s'agit de la racine des données XML. La dernière ligne du flux retourné doit être la balise de fermeture </Results>. Fondamentalement, cela marque le début et la fin du flux XML. Il pourrait n'y avoir aucun résultat ou cinquante résultats. <show> - C'est le nœud parent qui dit : « Ce qui suit (jusqu'à la balise fermante) est l'information sur une émission de télévision ». Encore une fois, il se termine par la balise de fin </show>. Tout ce qui est entre ces deux balises concerne une émission. <showid>2930</showid> - Cette balise showid contient le sid que nous devons utiliser pour obtenir les informations de l'émission, dans ce cas 2930. <name>Buffy contre les vampires</name> - C'est le nom de l'émission. <link>…</link> - C'est le lien vers l'émission elle-même (ou vers l'épisode dans le cas d'un épisode) sur le site TVRage. <country>…</country> - Le pays d'origine de l'émission. … </show> </Results>

In the case of our program, we would be really interested in only the two fields <showid> and <name>. We might also consider paying attention to the <started> field as well. This is because we rarely get back just one set of data, especially if we didn’t give the absolutely complete show name. For example, if we were interested in the show “The Big Bang Theory,” and searched using only the string “Big Bang”, we would get twenty or so data sets back because anything that even remotely matched “big” or “bang” would be returned. However, if we were interested in the show “NCIS,” and we searched for that, we would get back many responses. Some not what we would expect right away. Not only would we get “NCIS”, “NCIS: Los Angeles”, “The Real NCIS”, but also “The Streets of San Francisco” and “Da Vinci’s Inquest”, and many more, since the letters “N” “C” “I” and “S” are in all of those, pretty much in that order.

Dans le cas de notre programme, nous ne sommes vraiment intéressés que par les deux balises <showid> et <name>. Nous pourrions également envisager de prêter attention au champ <started>. Ceci, parce que nous recevons rarement un seul ensemble de données, surtout si l'on ne donne pas le nom absolument complet de l'émission. Par exemple, si nous nous étions intéressés à l'émission « The Big Bang Theory » et l'avions recherchée en utilisant uniquement la chaîne « Big Bang » ou à «», nous aurions obtenu une vingtaine d'ensembles de données en retour car tout ce qui s'approche, même de loin, à « big » ou à « bang »serait renvoyé. De même, si nous nous étions intéressés à l'émission “NCIS” et avions cherché cela, nous trouverions de nombreuses réponses. Certains ne correspondent pas à ce que nous attendons. Non seulement nous obtenons « NCIS », « NCIS : Los Angeles », « The Real NCIS », mais aussi « Les rues de San Francisco » et « L'enquête Da Vinci », et beaucoup plus, puisque les lettres « N » « C » « I » et « S » sont contenus dans tous ceux-ci, à peu près dans cet ordre.

Once we know the show id that we want, then we can request the show information for that ID. The data is similar to the data we just got back in the search response, but more detailed. Again, using Buffy as our example request, here (next page, right) is an abbreviated version of the XML file. You can see that much of the data is included in the original search response stream. However, things like network, network country, runtime, air day and time, are specific to this response set. Next, we would request the episode list. If the show is only one season long and has/had only six episodes, this stream would be short. However, let’s take the case of one of my favorite TV shows, Doctor Who. Doctor Who is a British TV show that, in its original form, started in 1963 and ran for 26 seasons (‘series’ for our friends in the UK) until 1989. Its first season alone had 42 episodes, while other seasons/series have around 24 episodes. You can see where you might have a HUGE stream to parse through.

Une fois que nous connaissons l'identifiant d'émission, nous pouvons demander l'information sur l'émission pour cet ID-là. Les données sont similaires à celles que nous venons de recevoir dans la réponse à la recherche, mais plus détaillées. En utilisant encore une fois Buffy comme exemple, voici (page suivante, à droite) une version abrégée du fichier XML.

Vous pouvez voir que la plupart des données étaient déjà dans le flux de réponse à la recherche originale. Cependant, des choses comme la chaîne, le pays de la chaîne, l'exécution, le jour et l'heure de diffusion, sont spécifiques à cette série de réponses.

Ensuite, nous allons demander la liste des épisodes. Si l'émission n'a qu'une saison et a/avait seulement six épisodes, ce flux sera court. Cependant, prenons le cas d'une de mes émissions préférées, Doctor Who. Doctor Who est une émission britannique qui, dans sa forme originale, a commencé en 1963 et a duré 26 saisons jusqu'en 1989. Sa première saison compte 42 épisodes, tandis que les autres saisons/séries ont environ 24 épisodes. Vous pouvez voir que vous pourriez avoir un ÉNORME flux à analyser.

What we get back from the episode list request is as shown on the next page (again using Buffy as our example); I’m going to just use part of the stream so you get a good idea of what comes back. So to recap, the information we really want/need in the search for show id by name stream would be… <showid> <name> <started>

Ce que nous obtenons après la demande de la liste des épisodes est indiqué sur la page suivante (en utilisant encore Buffy comme exemple) ; je vais juste utiliser une partie du flux pour que vous ayez une bonne idée de ce qu'on reçoit.

Pour résumer, donc, l'information dont nous avons vraiment besoin après la recherche de l'identifiant de l'émission à partir de son nom serait : <showid> <name> <started>

In the Show Information stream we would (normally) want… <seasons> <started> <start date> <origin_country> <status> <genres> <runtime> <network> <airtime> <airday> <timezone>

Dans le flux d'information sur l'émission, nous voudrions (normalement) : <seasons> <started> <start date> <origin_country> <status> <genres> <runtime> <network> <airtime> <airday> <timezone>

and from the episode list stream : <Season> <episode number> <season number> <production number> <airdate> <link> <title>

et dans le flux de la liste des épisodes : <Season> <episode number> <season number> <production number> <airdate> <link> <title>

A word of “warning” here. Season number and Episode number data are not what you might think right away. In the case of the data from TVRage, the season number is the number of the episode within the season. The episode number is the number for that episode within the total life span of the series. The production number is a number that was used internally to the series, that, for many people, means little if anything. Now that we have refreshed our memory on XML file structures and examined the TVRage API calls, we are ready to start our coding, but that will have to wait until next time. Until then, have a good holiday season.

Un petit « avertissement » ici. Le numéro de saison et les numéros des épisodes ne sont pas forcément ce à quoi vous pensez. Dans le cas des données de TVRage, le numéro de saison est le numéro de l'épisode dans la saison. Le numéro d'épisode est le numéro de cet épisode dans la durée de vie totale de la série. Le numéro de production est un numéro qui a été utilisé en interne pour la série et qui, pour beaucoup de gens, n'a pas vraiment de signification.

Maintenant que nous avons rafraîchi notre mémoire sur la structure des fichiers XML et examiné les appels à l'API de TVRage, nous sommes prêts à commencer à coder, mais cela devra attendre jusqu'à la prochaine fois.

Jusque-là, passez de bonnes vacances.