Альтернатива 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 відсотків, а кожен тариф містить усі дані. Суми дивіться на сторінці ціни.