Tendances et points de terminaison de listes

Obtenir les titres tendance

GET /3/trending/{media_type}/{time_window} renvoie une page classée de ce que les gens regardent ou recherchent en ce moment. media_type vaut all, movie, tv ou person. time_window vaut day ou week. Les classements du jour bougent vite et conviennent à un bandeau « ce soir ». Les classements de la semaine sont plus stables et conviennent à une page d'accueil.

L'exemple demande le classement hebdomadaire des films et affiche les dix premiers titres.

curl -s "https://api.amodb.dev/3/trending/movie/week?language=en-US&page=1" \
  -H "Authorization: Bearer $AMODB_KEY"

const url = 'https://api.amodb.dev/3/trending/movie/week?language=en-US&page=1';
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } });
if (!res.ok) throw new Error(`amodb returned ${res.status}`);
const chart = await res.json();
for (const [i, m] of chart.results.slice(0, 10).entries()) {
  console.log(i + 1, m.title, m.release_date);
}

import os
import requests

r = requests.get(
    "https://api.amodb.dev/3/trending/movie/week",
    params={"language": "en-US", "page": 1},
    headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
    timeout=10,
)
r.raise_for_status()
for i, m in enumerate(r.json()["results"][:10], start=1):
    print(i, m["title"], m.get("release_date"))

<?php
$url = 'https://api.amodb.dev/3/trending/movie/week?language=en-US&page=1';
$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");
}
$chart = json_decode($body, true);
foreach (array_slice($chart['results'], 0, 10) as $i => $m) {
    echo ($i + 1), ' ', $m['title'], ' ', $m['release_date'] ?? '', PHP_EOL;
}

package main

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

type Chart struct {
	Results []struct {
		Title       string `json:"title"`
		ReleaseDate string `json:"release_date"`
	} `json:"results"`
}

func main() {
	url := "https://api.amodb.dev/3/trending/movie/week?language=en-US&page=1"
	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 chart Chart
	if err := json.NewDecoder(res.Body).Decode(&chart); err != nil {
		panic(err)
	}
	for i, m := range chart.Results {
		if i == 10 {
			break
		}
		fmt.Println(i+1, m.Title, m.ReleaseDate)
	}
}

Paramètres

• media_typecheminobligatoire
  all, movie, tv ou person.
• time_windowcheminobligatoire
  day ou week.
• api_keyrequêtel'un des deux
  Votre clé. Utilisez-la ou l'en-tête Authorization: Bearer.
• languagerequête
  Balise TMDB comme en-US ou ru-RU. 14 langues de base sont servies, tout le reste se replie sur l'anglais.
• pagerequête
  Numéro de page de 1 à 500. Chaque page contient 20 résultats.

Champs de la réponse

Exemple de réponse

{
  "page": 1,
  "results": [
    {
      "adult": false,
      "backdrop_path": "/7ULXMNvmZSi13zN3EZjz8wbER9B.jpg",
      "genre_ids": [28, 53],
      "id": 1561726,
      "original_language": "en",
      "original_title": "Masterplan",
      "overview": "When a legendary thief sets his sights on the Mona Lisa, he recruits two young strangers to help him before...",
      "popularity": 189.8286,
      "poster_path": "/3x3AfF0qVwSUDDciTaNKcPHZUN8.jpg",
      "release_date": "2026-10-16",
      "title": "Masterplan",
      "video": false,
      "vote_average": 7.279,
      "vote_count": 61,
      "media_type": "movie"
    },
    {
      "adult": false,
      "backdrop_path": "/mBZKC8ActTlM4W3HEGI1Cl1RtO3.jpg",
      "genre_ids": [878, 9648, 28],
      "id": 1058424,
      "original_language": "ko",
      "original_title": "호프",
      "overview": "In the remote South Korean village of Hope Harbor, police chief Bum-seok and officer Sung-ae are called to...",
      "popularity": 294.6518,
      "poster_path": "/bcK5naYzzfY0JBCgrPrsrbV6NO1.jpg",
      "release_date": "2026-07-15",
      "title": "Hope",
      "video": false,
      "vote_average": 6.917,
      "vote_count": 246,
      "media_type": "movie"
    },
    {
      "adult": false,
      "backdrop_path": "/5YfPIIMzGBkIjHt3PTXBWyfBTGS.jpg",
      "genre_ids": [28, 14],
      "id": 1153576,
      "original_language": "en",
      "original_title": "Street Fighter",
      "overview": "In 1993, estranged Street Fighters Ryu and Ken Masters are thrown back into combat when the mysterious Chun...",
      "popularity": 209.3923,
      "poster_path": "/utKzCSCz2HtXwcDGfWLj2IHhSob.jpg",
      "release_date": "2026-10-13",
      "title": "Street Fighter",
      "video": false,
      "vote_average": 6.316,
      "vote_count": 76,
      "media_type": "movie"
    }
  ],
  "total_pages": 500,
  "total_results": 10000
}

La réponse a été récupérée depuis l'API réelle et réduite à 3 des 20 entrées de la page 1. Les longues chaînes overview sont raccourcies, et les rangs et les compteurs changent à chaque actualisation.

Listes de films

Les classements de films partagent une même forme : un tableau results paginé d'objets de films. now_playing et upcoming ajoutent un objet dates avec minimum et maximum, la fenêtre de sortie que couvre la liste. Les quatre acceptent language, page et region.

Un vrai objet dates ressemble à ceci :

{ "dates": { "maximum": "2026-10-21", "minimum": "2026-09-09" } }

region est un code ISO 3166-1 en majuscules comme DE ou GB. Sur now_playing et upcoming, il ne garde que les titres sortis dans ce pays : la liste n'est donc qu'une petite partie de la liste mondiale. Un code inconnu renvoie une liste vide. Sur popular et top_rated, il remplace seulement release_date par la date locale et ne change pas le classement. Pour voir où un film passe, associez now_playing à séances.

Listes de séries

Les classements de séries renvoient les mêmes champs de pagination. Les éléments utilisent name, original_name, first_air_date et origin_country à la place des noms de films. Les quatre acceptent language et page.

timezone est un nom IANA comme Europe/Rome. Il décide quel jour du calendrier compte pour « aujourd'hui » : airing_today renvoie donc un ensemble différent pour Asia/Tokyo et pour Pacific/Auckland. Les listes de séries n'ont pas de paramètre region.

Listes de personnes

GET /person/popular renvoie une liste paginée de personnes classées par popularité, avec language et page. Chaque entrée a id, name, original_name, known_for_department, gender, profile_path, popularity et un tableau known_for d'au plus 3 cartes de films ou de séries, chacune avec media_type. Ouvrez une personne sur personnes.

{
  "page": 1,
  "results": [
    {
      "adult": false,
      "gender": 1,
      "id": 1247604,
      "known_for_department": "Acting",
      "name": "Agnez Mo",
      "original_name": "Agnez Mo",
      "popularity": 45.8988,
      "profile_path": "/7GuBJxf5szQRCKLk3iG2ztfCo39.jpg",
      "known_for": [
        {
          "adult": false,
          "backdrop_path": "/pF0qkRsrHkdYadPWY9AMeFZfcwk.jpg",
          "first_air_date": "2022-02-03",
          "genre_ids": [10759],
          "id": 108978,
          "name": "Reacher",
          "origin_country": ["US"],
          "original_language": "en",
          "original_name": "Reacher",
          "overview": "Jack Reacher, a veteran military police investigator, has just recently enter...",
          "popularity": 411.841,
          "poster_path": "/f1VCQIG2iCyOookdgOzwtUpwWC0.jpg",
          "vote_average": 8.1,
          "vote_count": 3508,
          "media_type": "tv"
        }
      ]
    }
  ],
  "total_pages": 1001,
  "total_results": 20001
}

amodb ne propose ni person/latest ni les flux changes.

Choisir la bonne liste pour un écran

Erreurs

Le tableau complet est sur la page erreurs. Les limites par offre sont sur limites de débit.

Remarques pratiques

• La périphérie met en cache 30 minutes les listes de tendances, de populaires, à l'affiche et en cours de diffusion, et chaque clé partage la même entrée. Une tâche d'actualisation toutes les 30 minutes suffit.
• Les pages vont de 1 à 500. Les listes de populaires annoncent un total_results de 20001, qui est un plafond et non un vrai compte. Au-delà de la page 500, utilisez découverte avec sort_by et des filtres, qui atteint des titres qu'un classement ne montre jamais.
• Les éléments de liste ne contiennent que les champs nécessaires à une carte. Pour la durée, imdb_id ou les crédits, appelez les détails du film avec append_to_response, une fois par carte que l'utilisateur ouvre.
• language contrôle la langue des titres et des résumés. Les titres sans traduction reviennent dans le texte d'origine : testez donc les chaînes vides avant d'afficher une carte.
• Stockez l'id d'une liste, pas la position. Les rangs changent à chaque actualisation.