Alternative à l'API TVmaze

Choisir selon la portée et le budget

TVmaze ne couvre que les séries. C'est une API publique gratuite avec des limites par adresse IP, et ses données sont sous licence d'attribution : consultez leur documentation pour les détails. amodb est payant et couvre séries, films et personnes. Si votre application est un suivi de séries et qu'une source gratuite répond à vos besoins, TVmaze est un départ raisonnable. Si vous affichez aussi des films, des pages de distribution ou des affiches en plusieurs langues, une seule clé amodb remplace plusieurs sources.

Ce que chaque portée signifie pour votre application

La ligne des films tranche la plupart des cas. Si vous n'avez pas de pages de films, la portée supplémentaire ne vous apporte rien.

Écarts à vérifier avant de migrer

Les points de terminaison de saisons et d'épisodes suivent la forme TMDB, et quelques-unes de leurs parties reviennent vides. Testez les écrans qui les utilisent.

• Distribution d'un épisode. Sur un épisode, cast est un tableau vide. guest_stars et crew sont remplis, et l'appel /credits de la série contient la distribution principale.
• Extras de saison. Les images, videos et translations d'une saison sont vides : l'affiche d'une saison vient donc de la fiche de saison et non d'une liste d'images.
• Identifiants externes. Les external_ids des saisons et des épisodes sont tous nuls. Associez les épisodes à vos propres données par season_number et episode_number.
• Créateurs. created_by sur une série est vide pour la plupart des séries.
• Pas de flux de changements. amodb n'a pas de point de terminaison qui liste les séries modifiées depuis une date.

Comparatif des fonctionnalités

Ce qui distingue amodb

• La limite suit la clé. Tous vos serveurs partagent un seul compteur dans une fenêtre glissante de 60 secondes, et les réponses portent X-RateLimit-Remaining. Rien ne dépend de l'adresse d'où part une requête.
• Films, séries et personnes au même endroit. Un seul client, un seul format d'erreur et un seul jeu d'en-têtes couvrent toute l'application.
• Langues. Titres et résumés reviennent dans l'une des 14 langues, et original_name garde le titre d'origine.
• Un protocole établi. Les bibliothèques écrites pour les lectures TMDB v3 fonctionnent avec une nouvelle URL de base. Voir la page API de séries TV pour les points de terminaison de séries.

Quand TVmaze convient mieux

• Pas de budget. L'usage est gratuit : un projet d'étudiant ou un suivi de week-end n'a besoin d'aucun paiement. amodb n'a ni offre gratuite ni essai.
• Séries uniquement, en restant simple. Si votre modèle de données ne contient que des séries et des épisodes, une API centrée sur les séries lui correspond.
• Ses propres conventions. Les applications déjà construites autour du modèle TVmaze économisent du travail en y restant.

Si vous restez, respectez sa licence d'attribution. Consultez leur documentation pour le libellé.

Migrer vers amodb

Commencez par un travail d'association. Lisez les identifiants externes que listent vos fiches TVmaze stockées (voir leur documentation pour les noms de champs) et résolvez-les via /3/find. Le programme ci-dessous associe un identifiant IMDb à une série et affiche la date du prochain épisode.

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"os"
	"time"
)

type findResult struct {
	TVResults []struct {
		ID   int    `json:"id"`
		Name string `json:"name"`
	} `json:"tv_results"`
}

type episode struct {
	AirDate       string `json:"air_date"`
	SeasonNumber  int    `json:"season_number"`
	EpisodeNumber int    `json:"episode_number"`
}

type series struct {
	Name        string   `json:"name"`
	Status      string   `json:"status"`
	NextEpisode *episode `json:"next_episode_to_air"`
}

var client = &http.Client{Timeout: 10 * time.Second}

func get(path string, out any) error {
	req, err := http.NewRequest(http.MethodGet, "https://api.amodb.dev/3"+path, nil)
	if err != nil {
		return err
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("AMODB_KEY"))
	res, err := client.Do(req)
	if err != nil {
		return err
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		return fmt.Errorf("amodb returned %s", res.Status)
	}
	return json.NewDecoder(res.Body).Decode(out)
}

func main() {
	var found findResult
	if err := get("/find/tt0903747?external_source=imdb_id", &found); err != nil {
		fmt.Println(err)
		return
	}
	if len(found.TVResults) == 0 {
		fmt.Println("no match")
		return
	}
	var s series
	if err := get(fmt.Sprintf("/tv/%d", found.TVResults[0].ID), &s); err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(s.Name, s.Status)
	if s.NextEpisode != nil {
		fmt.Println("next episode:", s.NextEpisode.AirDate)
	}
}

Le type pointeur de NextEpisode gère le null que renvoient les séries terminées. Lancez l'association une fois, enregistrez l'identifiant amodb avec chacune de vos fiches, puis appelez /3/tv/{id} ensuite. Une réponse 429 vient avec Retry-After, et la page recherche par identifiant externe liste les autres sources d'identifiants.

Dimensionner une synchronisation nocturne

Supposons que vous actualisiez 300 séries chaque nuit. Cela fait 300 requêtes, puisqu'un appel de série renvoie une série. À 20 requêtes par minute, le travail prend 15 minutes, à 40 il prend 7,5 minutes, et à 120 il prend 2,5 minutes. Ajoutez append_to_response=credits,ratings à chaque appel pour que la distribution et les notes arrivent dans la même requête, au lieu de coûter deux requêtes de plus par série. Lisez X-RateLimit-Remaining et faites une pause quand il atteint zéro, puis reprenez après les secondes de X-RateLimit-Reset.

Tarifs

amodb est prépayé et ne se renouvelle jamais tout seul. Choisissez 1, 3, 6, 12 ou 24 mois et une offre de 20, 40 ou 120 requêtes par minute. Les périodes plus longues coûtent 10, 20, 30 ou 40 pour cent de moins, et chaque offre inclut toutes les données. Les montants sont sur les tarifs.