Ендпойнти за тенденции и списъци

Вземане на заглавия в тенденция

GET /3/trending/{media_type}/{time_window} връща подредена страница с това, което хората гледат или търсят в момента. media_type е all, movie, tv или person. time_window е day или week. Класациите за ден се менят бързо и пасват на лента „тази вечер“. Класациите за седмица са по-стабилни и пасват на начална страница.

Примерът иска седмичната класация на филмите и отпечатва първите десет заглавия.

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

Параметри

• media_typeпътзадължителен
  all, movie, tv или person.
• time_windowпътзадължителен
  day или week.
• api_keyзаявкаедин от двата
  Вашият ключ. Ползвайте него или заглавката Authorization: Bearer.
• languageзаявка
  Таг на TMDB, например en-US или ru-RU. Поддържат се 14 основни езика, всичко друго се заменя с английски.
• pageзаявка
  Номер на страница от 1 до 500. Всяка страница съдържа 20 резултата.

Полета на отговора

Примерен отговор

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

Отговорът е взет от работещото API и съкратен до 3 от 20-те записа на страница 1. Дългите низове overview са съкратени, а класирането и бройките се менят при всяко обновяване.

Списъци с филми

Класациите на филмите имат една форма: странициран масив results с обекти на филми. now_playing и upcoming добавят обект dates с minimum и maximum, прозореца на излизане, който списъкът покрива. И четирите приемат language, page и region.

Истински обект dates изглежда така:

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

region е код по ISO 3166-1 с главни букви, например DE или GB. При now_playing и upcoming запазва само заглавията, излезли в тази държава, така че списъкът е малка част от световния. Непознат код връща празен списък. При popular и top_rated само заменя release_date с местната дата и не променя класирането. За да видите къде върви един филм, съчетайте now_playing с прожекции.

Списъци със сериали

Класациите за сериали връщат същите полета за странициране. Елементите ползват name, original_name, first_air_date и origin_country вместо имената за филми. И четирите приемат language и page.

timezone е име по IANA, например Europe/Rome. Тя решава кой календарен ден се брои за „днес“, така че airing_today връща различен набор за Asia/Tokyo и за Pacific/Auckland. Списъците за сериали нямат параметър region.

Списъци с хора

GET /person/popular връща странициран списък с хора, подредени по популярност, с language и page. Всеки запис има id, name, original_name, known_for_department, gender, profile_path, popularity и масив known_for с до 3 карти на филми или сериали, всяка с media_type. Отворете личност на страницата личности.

{
  "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 не предлага person/latest и потоците changes.

Изберете правилния списък за екран

Грешки

Пълната таблица е на страницата грешки. Лимитите по планове са на страницата лимити на заявките.

Практически бележки

• Edge кешира списъците с тенденции, популярни, now playing и on the air за 30 минути и всеки ключ споделя един и същ запис. Задача за обновяване, която върви на 30 минути, е достатъчна.
• Страниците вървят от 1 до 500. Списъците с популярни отчитат total_results със стойност 20001, което е таван, а не реален брой. След страница 500 ползвайте откриване по филтри с sort_by и филтри, което стига до заглавия, които класацията никога не показва.
• Елементите в списъците съдържат само полетата, нужни за карта. За продължителност, imdb_id или участници извикайте детайли за филм с append_to_response, веднъж за всяка карта, която потребителят отвори.
• language управлява езика на заглавията и описанията. Заглавия без превод се връщат в оригиналния текст, затова проверявайте за празни низове, преди да визуализирате карта.
• Пазете id от списъка, а не позицията. Класирането се променя при всяко обновяване.