Gêneros e listas de consulta

Obter a lista de gêneros de filmes

GET /3/genre/movie/list retorna todos os gêneros de filmes como um id e um name. Os ids são os números que genre_ids traz nos itens de lista e que with_genres espera no discover. Os nomes seguem o parâmetro language.

O exemplo carrega a lista e monta um mapa de id para nome, a primeira coisa de que a maioria dos apps precisa.

curl -s "https://api.amodb.dev/3/genre/movie/list?language=en-US" \
  -H "Authorization: Bearer $AMODB_KEY"

const url = 'https://api.amodb.dev/3/genre/movie/list?language=en-US';
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } });
if (!res.ok) throw new Error(`amodb returned ${res.status}`);
const { genres } = await res.json();
const names = new Map(genres.map((g) => [g.id, g.name]));
console.log(names.get(878), names.size);

import os
import requests

r = requests.get(
    "https://api.amodb.dev/3/genre/movie/list",
    params={"language": "en-US"},
    headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
    timeout=10,
)
r.raise_for_status()
names = {g["id"]: g["name"] for g in r.json()["genres"]}
print(names[878], len(names))

<?php
$url = 'https://api.amodb.dev/3/genre/movie/list?language=en-US';
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AMODB_KEY')],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status !== 200) {
    throw new RuntimeException("amodb returned $status");
}
$names = [];
foreach (json_decode($body, true)['genres'] as $g) {
    $names[$g['id']] = $g['name'];
}
echo $names[878], ' ', count($names), PHP_EOL;

package main

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

type Genres struct {
	Genres []struct {
		ID   int    `json:"id"`
		Name string `json:"name"`
	} `json:"genres"`
}

func main() {
	url := "https://api.amodb.dev/3/genre/movie/list?language=en-US"
	req, _ := http.NewRequest("GET", url, nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("AMODB_KEY"))
	client := &http.Client{Timeout: 10 * time.Second}
	res, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		panic(res.Status)
	}
	var g Genres
	if err := json.NewDecoder(res.Body).Decode(&g); err != nil {
		panic(err)
	}
	names := map[int]string{}
	for _, x := range g.Genres {
		names[x.ID] = x.Name
	}
	fmt.Println(names[878], len(names))
}

Parâmetros

• api_keyconsultaum dos dois
  Sua chave. Use este parâmetro ou o header Authorization: Bearer.
• languageconsulta
  Tag do TMDB como en-US, ru-RU ou pt-BR. Os nomes voltam nesse idioma. Padrão en-US.

Campos da resposta

Exemplo de resposta

{
  "genres": [
    { "id": 12, "name": "Adventure" },
    { "id": 14, "name": "Fantasy" },
    { "id": 16, "name": "Animation" },
    { "id": 18, "name": "Drama" }
  ]
}

A resposta tem 27 gêneros ordenados por id. Esta foi cortada para os 4 primeiros.

Ids de gênero

Os dois caminhos de gênero retornam estes 27 gêneros, ordenados por id. Os nomes abaixo são os em inglês. Os outros idiomas retornam os mesmos ids com nomes traduzidos.

Lista de gêneros de TV

GET /3/genre/tv/list aceita o mesmo parâmetro language e retorna a lista idêntica, então um só mapa de id para nome cobre filmes e TV. Nos dados de listas, os ids 10759 e 10762 a 10768 aparecem só em itens de TV, e ids como 28, 12 e 878 aparecem em itens de filme. Ao filtrar TV no discover, use os ids de TV, por exemplo 10765 para Sci-Fi e Fantasia.

Listas de consulta

Estes caminhos retornam dados de referência para formulários, filtros e telas de configuração. Todos exigem a chave; nenhum aceita page.

/configuration/countries e /configuration/languages ignoram language e sempre retornam os mesmos nomes. O native_name da lista de regiões segue language. O amodb não oferece /configuration/timezones.

Uma entrada de classificação indicativa traz o nome da classificação, o que ela significa e a ordem de exibição. As entradas são agrupadas por código de país, então uma só chamada cobre todos os mercados. A lista de filmes tem os textos das classificações. Na lista de TV, meaning é uma string vazia.

{
  "certifications": {
    "US": [
      { "certification": "PG", "meaning": "Some material may not be suitable for children under 10.", "order": 3 },
      { "certification": "R", "meaning": "Under 17 requires accompanying parent or adult guardian.", "order": 5 }
    ]
  }
}

O exemplo foi cortado para 2 das 6 entradas dos EUA. A lista de filmes cobre AU, BR, CA, DE, ES, FR, GB, IT, RU e US.

Uma entrada de provedor tem provider_id, provider_name, logo_path, display_priority e display_priorities, um mapa de código de país para prioridade. Sem watch_region, você recebe todos os provedores. Com watch_region=US, ficam só os provedores que atendem esse país. Uma região desconhecida retorna um array results vazio. Passe um código de /watch/providers/regions. Os logos dos provedores carregam do host de imagens, veja imagens.

{
  "display_priorities": { "AT": 1, "DE": 1, "GB": 1, "JP": 1, "US": 3 },
  "display_priority": 3,
  "logo_path": "/gMZdpavHmxFNnLpMHwVxfqeux2g.png",
  "provider_name": "Amazon Prime Video",
  "provider_id": 9
}

Esta é uma entrada de /watch/providers/movie?watch_region=US.

Erros

Os detalhes de cada código estão em erros. Os limites dos planos estão em limites de requisições.

Notas práticas

• Carregue as listas uma vez por idioma na inicialização e mantenha-as na memória ou em um arquivo. A borda guarda em cache os caminhos /configuration por 24 horas, então uma atualização diária do seu lado basta.
• Guarde ids de gênero no seu banco de dados, não nomes. O nome muda com o idioma, o id não.
• Os dois caminhos de gênero retornam as mesmas 27 entradas, então um só mapa cobre filmes e TV. Os ids 10759 e 10762 a 10768 aparecem só em itens de TV.
• with_genres=28,12 no discover significa Ação e Aventura juntos. with_genres=28|12 significa qualquer um dos dois.
• Os nomes dos gêneros seguem o parâmetro language. Uma tag fora dos 14 idiomas base de idiomas volta para o inglês, e alguns nomes ficam em inglês em certos idiomas, por exemplo 10759 em italiano.