Альтернатива TVmaze API

Выбирайте по охвату и бюджету

TVmaze охватывает только сериалы. Он бесплатен как публичный API с лимитами на IP-адрес, а его данные идут под лицензией с указанием источника, поэтому подробности смотрите в их документации. amodb платный и охватывает сериалы, фильмы и людей. Если ваше приложение это трекер сериалов и вам хватает бесплатного источника, TVmaze разумное начало. Если вы показываете еще и фильмы, страницы актеров или постеры на нескольких языках, один ключ amodb заменит несколько источников.

Что значит охват для вашего приложения

Строка про фильмы решает большинство случаев. Если у вас нет страниц фильмов, дополнительный охват вам не нужен.

Что проверить до переезда

Эндпоинты сезонов и серий следуют форме TMDB, и некоторые их части приходят пустыми. Проверьте экраны, которые ими пользуются.

• Актеры серии. У серии cast это пустой массив. Поля guest_stars и crew заполнены, а основной актерский состав есть в вызове /credits сериала.
• Дополнения сезона. Поля images, videos и translations сезона пусты, поэтому постер сезона берется из записи сезона, а не из списка изображений.
• Внешние ID. Поля external_ids у сезонов и серий все равны null. Сопоставляйте серии со своими записями по season_number и episode_number.
• Создатели. Поле created_by у сериала для большинства шоу пусто.
• Нет ленты изменений. В amodb нет эндпоинта, который перечисляет шоу, изменившиеся с определенной даты.

Сравнение возможностей

Чем отличается amodb

• Лимит следует за ключом. Все ваши серверы делят один счетчик в скользящем окне 60 секунд, а в ответах есть X-RateLimit-Remaining. Ничто не зависит от того, с какого адреса ушел запрос.
• Фильмы, сериалы и люди в одном месте. Один клиент, один формат ошибок и один набор заголовков покрывают все приложение.
• Языки. Названия и описания приходят на любом из 14 языков, а original_name сохраняет название на родном языке.
• Устоявшийся протокол. Библиотеки, написанные для чтения TMDB v3, работают с новым базовым URL. Эндпоинты сериалов описаны на странице API сериалов.

Когда TVmaze подходит лучше

• Нет бюджета. Он бесплатен, поэтому студенческому проекту или трекеру выходного дня платить не нужно. В amodb нет ни бесплатного тарифа, ни пробного периода.
• Только сериалы, без лишнего. Если ваша модель данных состоит из шоу и серий и ничего больше, API, ориентированный на сериалы, ей соответствует.
• Собственные соглашения. Приложения, уже построенные вокруг модели TVmaze, экономят силы, оставаясь на нем.

Если вы остаетесь, соблюдайте его лицензию с указанием источника. Формулировку смотрите в их документации.

Миграция на amodb

Начните с задачи сопоставления. Прочитайте внешние ID, которые перечислены в сохраненных записях TVmaze (названия полей смотрите в их документации), и разрешите их через /3/find. Программа ниже сопоставляет один ID IMDb с сериалом и печатает дату следующей серии.

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)
	}
}

Указательный тип у NextEpisode справляется с null, который возвращают завершенные шоу. Выполните сопоставление один раз, сохраните ID amodb в каждой своей записи и дальше вызывайте /3/tv/{id}. На 429 приходит Retry-After, а другие источники ID перечислены на странице поиск по внешнему ID.

Расчет ночной синхронизации

Допустим, вы обновляете 300 шоу каждую ночь. Это 300 запросов, потому что один вызов сериала возвращает одно шоу. При 20 запросах в минуту задача займет 15 минут, при 40 это 7.5 минут, а при 120 это 2.5 минуты. Добавьте append_to_response=credits,ratings к каждому вызову, чтобы актерский состав и оценки приходили в том же запросе, а не стоили еще двух на шоу. Читайте X-RateLimit-Remaining и делайте паузу, когда значение достигает нуля, затем продолжайте через X-RateLimit-Reset секунд.

Цены

amodb работает по предоплате и никогда не продлевается сам. Выберите 1, 3, 6, 12 или 24 месяца и тариф на 20, 40 или 120 запросов в минуту. Длинные периоды дешевле на 10, 20, 30 или 40 процентов, а каждый тариф включает все данные. Суммы указаны на странице цены.