Endpoint-uri pentru tendințe și liste

Obține titlurile în tendințe

GET /3/trending/{media_type}/{time_window} întoarce o pagină ierarhizată cu ce urmăresc sau caută oamenii chiar acum. media_type este all, movie, tv sau person. time_window este day sau week. Topurile pe zi se mișcă repede și se potrivesc unei benzi „în seara asta”. Topurile pe săptămână sunt mai stabile și se potrivesc unei pagini principale.

Exemplul cere topul săptămânal de filme și afișează primele zece titluri.

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

Parametri

• media_typecaleobligatoriu
  all, movie, tv sau person.
• time_windowcaleobligatoriu
  day sau week.
• api_keyinterogareuna dintre cele două
  Cheia ta. Folosește-o pe aceasta sau antetul Authorization: Bearer.
• languageinterogare
  Etichetă TMDB precum en-US sau ru-RU. Sunt servite 14 limbi de bază, orice altceva revine la engleză.
• pageinterogare
  Numărul paginii de la 1 la 500. Fiecare pagină are 20 de rezultate.

Câmpurile răspunsului

Exemplu de răspuns

{
  "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
}

Răspunsul a fost preluat de la API-ul live și tăiat la 3 din cele 20 de intrări de pe pagina 1. Șirurile overview lungi sunt scurtate, iar rangurile și numărătorile se schimbă la fiecare reîmprospătare.

Liste de filme

Topurile de filme au aceeași structură: un array results paginat cu obiecte de film. now_playing și upcoming adaugă un obiect dates cu minimum și maximum, fereastra de lansare pe care o acoperă lista. Toate patru primesc language, page și region.

Un obiect dates real arată așa:

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

region este un cod ISO 3166-1 cu majuscule, precum DE sau GB. La now_playing și upcoming păstrează doar titlurile lansate în acea țară, deci lista este o mică parte din cea mondială. Un cod necunoscut întoarce o listă goală. La popular și top_rated doar înlocuiește release_date cu data locală și nu schimbă clasamentul. Ca să vezi unde rulează un film, asociază now_playing cu program de proiecții.

Liste TV

Topurile TV întorc aceleași câmpuri de paginare. Elementele folosesc name, original_name, first_air_date și origin_country în locul numelor de la filme. Toate patru primesc language și page.

timezone este un nume IANA precum Europe/Rome. Decide ce zi calendaristică se numără ca „azi”, deci airing_today întoarce un set diferit pentru Asia/Tokyo decât pentru Pacific/Auckland. Listele TV nu au parametrul region.

Liste de persoane

GET /person/popular întoarce o listă paginată de persoane ordonate după popularitate, cu language și page. Fiecare intrare are id, name, original_name, known_for_department, gender, profile_path, popularity și un array known_for de până la 3 carduri de film sau TV, fiecare cu media_type. Deschide o persoană la persoane.

{
  "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 nu oferă person/latest sau fluxurile changes.

Alege lista potrivită pentru un ecran

Erori

Tabelul complet este pe pagina erori. Limitele pe plan sunt la limite de cereri.

Note practice

• Marginea ține în cache listele trending, popular, now playing și on the air 30 de minute, iar fiecare cheie partajează aceeași intrare. Un job de reîmprospătare care rulează la fiecare 30 de minute ajunge.
• Paginile merg de la 1 la 500. Listele populare raportează total_results 20001, ceea ce este un plafon și nu o numărătoare reală. Dincolo de pagina 500, folosește descoperire cu sort_by și filtre, care ajunge la titluri pe care un top nu le arată niciodată.
• Elementele din liste conțin doar câmpurile necesare unui card. Pentru durată, imdb_id sau credite, apelează detalii film cu append_to_response, o dată pentru fiecare card pe care îl deschide utilizatorul.
• language controlează limba titlurilor și a descrierilor. Titlurile fără traducere revin în textul original, deci verifică dacă sunt șiruri goale înainte să afișezi un card.
• Stochează id-ul dintr-o listă, nu poziția. Rangurile se schimbă la fiecare reîmprospătare.