Discover API

Пошук фільмаў па фільтрах

GET /3/discover/movie вяртае пастаронкавы спіс фільмаў, якія адпавядаюць усім адпраўленым фільтрам, у абраным парадку. Гэта эндпоінт для старонак агляду, спісаў «лепшае» і рэкамендацый па фасетах, і тэкст query яму не патрэбны. Калі карыстальнік увёў назву, выкарыстоўвайце пошук.

У прыкладзе паказаны фантастычныя фільмы (id жанру 878) не менш чым з 1000 галасоў, спачатку з лепшым рэйтынгам.

curl -sSf --get "https://api.amodb.dev/3/discover/movie" \
  --data-urlencode "with_genres=878" \
  --data-urlencode "sort_by=vote_average.desc" \
  --data-urlencode "vote_count.gte=1000" \
  --data-urlencode "language=en-US" \
  -H "Authorization: Bearer $AMODB_KEY"

const params = new URLSearchParams({
  with_genres: '878',
  sort_by: 'vote_average.desc',
  'vote_count.gte': '1000',
  language: 'en-US',
});
const res = await fetch(`https://api.amodb.dev/3/discover/movie?${params}`, {
  headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` },
});
if (!res.ok) throw new Error(`amodb returned ${res.status}`);
const { results, total_pages } = await res.json();
console.log(`page 1 of ${total_pages}`);
for (const m of results.slice(0, 5)) console.log(m.vote_average, m.title, m.release_date);

import os
import requests

r = requests.get(
    "https://api.amodb.dev/3/discover/movie",
    params={
        "with_genres": 878,
        "sort_by": "vote_average.desc",
        "vote_count.gte": 1000,
        "language": "en-US",
    },
    headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
    timeout=10,
)
r.raise_for_status()
data = r.json()
print("page 1 of", data["total_pages"])
for m in data["results"][:5]:
    print(m["vote_average"], m["title"], m["release_date"])

<?php
$url = 'https://api.amodb.dev/3/discover/movie?' . http_build_query([
    'with_genres' => 878,
    'sort_by' => 'vote_average.desc',
    'vote_count.gte' => 1000,
    '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");
}
$data = json_decode($body, true);
foreach (array_slice($data['results'], 0, 5) as $m) {
    echo $m['vote_average'], ' ', $m['title'], PHP_EOL;
}

package main

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

type Page struct {
	TotalPages int `json:"total_pages"`
	Results    []struct {
		Title       string  `json:"title"`
		ReleaseDate string  `json:"release_date"`
		VoteAverage float64 `json:"vote_average"`
	} `json:"results"`
}

func main() {
	q := url.Values{
		"with_genres":    {"878"},
		"sort_by":        {"vote_average.desc"},
		"vote_count.gte": {"1000"},
		"language":       {"en-US"},
	}
	req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/discover/movie?"+q.Encode(), 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 p Page
	if err := json.NewDecoder(res.Body).Decode(&p); err != nil {
		panic(err)
	}
	fmt.Println("pages:", p.TotalPages)
	for _, m := range p.Results {
		fmt.Println(m.VoteAverage, m.Title, m.ReleaseDate)
	}
}

Параметры

• api_keyзапытадзін з двух
  Ваш ключ. Выкарыстоўвайце яго або загаловак Authorization: Bearer.
• sort_byзапыт
  Поле і напрамак, напрыклад vote_average.desc. Палі: popularity, vote_average, vote_count, primary_release_date, revenue, title, original_title, кожнае з .asc або .desc. title і original_title абодва сартуюць па арыгінальнай назве. Невядомае значэнне замяняецца на popularity.desc, якое таксама дзейнічае па змаўчанні.
• with_genresзапыт
  Id жанраў. Коска азначае І, вертыкальная рыска азначае АБО.
• without_genresзапыт
  Id жанраў, якія трэба выключыць.
• with_cast, with_crewзапыт
  Id персон. Знайдзіце іх праз пошук.
• with_peopleзапыт
  Id персон, якія ёсць у акцёрскім складзе або ў здымачнай групе.
• with_companies, without_companiesзапыт
  Id вытворчых кампаній, якіх трэба ўключыць або выключыць. Коска і вертыкальная рыска працуюць так жа, як у with_genres.
• with_keywords, without_keywordsзапыт
  Id ключавых слоў, якія трэба ўключыць або выключыць. Гл. ключавыя словы.
• with_origin_countryзапыт
  Двухлітарны код краіны вытворчасці вялікімі літарамі, напрыклад FR.
• primary_release_yearзапыт
  Чатырохзначны год асноўнай даты выхаду.
• yearзапыт
  Чатырохзначны год. Супадае з любой датай выхаду ў гэтым годзе, таму вяртае больш фільмаў, чым primary_release_year.
• primary_release_date.gte, primary_release_date.lteзапыт
  Ніжняя і верхняя мяжа асноўнай даты выхаду, YYYY-MM-DD.
• release_date.gte, release_date.lteзапыт
  Ніжняя і верхняя мяжа любой даты выхаду ў любой краіне, YYYY-MM-DD.
• regionзапыт
  Двухлітарны код краіны вялікімі літарамі. Замяняе release_date у кожным выніку датай у гэтай краіне. Фільмы не выдаляе.
• certification_country, certificationзапыт
  Фільтр узроставага рэйтынгу, напрыклад US і PG. Без краіны certification ігнаруецца. certification.gte і certification.lte задаюць дыяпазон.
• vote_average.gte, vote_average.lteзапыт
  Мінімальная і максімальная сярэдняя ацэнка, ад 0 да 10.
• vote_count.gte, vote_count.lteзапыт
  Мінімальная і максімальная колькасць галасоў.
• with_runtime.gte, with_runtime.lteзапыт
  Мінімальная і максімальная працягласць у хвілінах.
• with_original_languageзапыт
  Арыгінальная мова ў выглядзе двухлітарнага кода, напрыклад fr або ko.
• with_watch_providersзапыт
  Id стрымінгавых сэрвісаў. Патрабуе watch_region, без яго ігнаруецца. Id бяруцца са старонкі жанры і даведачныя спісы.
• watch_regionзапыт
  Двухлітарны код краіны вялікімі літарамі для даступнасці сэрвісу.
• include_adultзапыт
  Прымаецца і ігнаруецца. Фільмы для дарослых ніколі не вяртаюцца.
• languageзапыт
  Тэг TMDB, напрыклад en-US або pl-PL. Падтрымліваюцца 14 базавых моў. Па змаўчанні en-US.
• pageзапыт
  Нумар старонкі ад 1 да 500. Па змаўчанні 1.

Палі адказу

Прыклад адказу

{
  "page": 1,
  "results": [
    {
      "adult": false,
      "backdrop_path": "/wLWvHcQz7N13DvSOTV7bHgwGXpT.jpg",
      "genre_ids": [878, 12],
      "id": 687163,
      "original_language": "en",
      "original_title": "Project Hail Mary",
      "overview": "Science teacher Ryland Grace wakes up on a spaceship light years from home with no recollection of who he i...",
      "popularity": 101.0341,
      "poster_path": "/yihdXomYb5kTeSivtFndMy5iDmf.jpg",
      "release_date": "2026-03-15",
      "title": "Project Hail Mary",
      "video": false,
      "vote_average": 8.635,
      "vote_count": 8354
    },
    {
      "adult": false,
      "backdrop_path": "/Ys8UIGWJpd2TMuQk8fU77W3mBz.jpg",
      "genre_ids": [12, 18, 878],
      "id": 157336,
      "original_language": "en",
      "original_title": "Interstellar",
      "overview": "The adventures of a group of explorers who make use of a newly discovered wormhole to surpass the limitatio...",
      "popularity": 74.3949,
      "poster_path": "/yQvGrMoipbRoddT0ZR8tPoR7NfX.jpg",
      "release_date": "2014-11-04",
      "title": "Interstellar",
      "video": false,
      "vote_average": 8.491,
      "vote_count": 41526
    },
    {
      "adult": false,
      "backdrop_path": "/tanwf7KOwQ6dxZzehKsXkffIJOd.jpg",
      "genre_ids": [878, 28, 12],
      "id": 969681,
      "original_language": "en",
      "original_title": "Spider-Man: Brand New Day",
      "overview": "Fighting crime full-time as Spider-Man in a world that doesn't remember him...",
      "popularity": 663.5004,
      "poster_path": "/bjiS5ipwxb9JFy3XRRN4OAilSeX.jpg",
      "release_date": "2026-07-29",
      "title": "Spider-Man: Brand New Day",
      "video": false,
      "vote_average": 8.468,
      "vote_count": 5684
    }
  ],
  "total_pages": 39,
  "total_results": 772
}

Адказ атрыманы з жывога API для прыкладу запыту. Паказана 3 з 20 запісаў на старонцы 1, доўгія радкі overview скарочаны.

Спалучэнне фільтраў

Асобныя параметры спалучаюцца праз І. Унутры аднаго параметра коска азначае І, а вертыкальная рыска азначае АБО. У сырым URL вертыкальная рыска запісваецца як %7C, а кліенты, што кадуюць значэнні запыту, робяць гэта за вас.

with_original_language фільтруе па мове, на якой зняты фільм, і прымае коды па-за 14 падтрымліванымі мовамі, напрыклад ja або ko. Мову тэксту ў адказе па-ранейшаму вызначае параметр language. У радку са стрымінгавым сэрвісам 8 гэта Netflix. Id сэрвісаў чытайце з /watch/providers/movie.

Пошук серыялаў па фільтрах

GET /3/discover/tv выкарыстоўвае тую ж структуру адказу і тую ж пастаронкавую разбіўку. Запісы ўтрымліваюць name, original_name, first_air_date, origin_country і genre_ids, а id жанраў бяруцца з /genre/tv/list, дзе сабраны аб’яднаныя id для серыялаў, напрыклад 10765 для Sci-Fi і Fantasy.

Запыт /discover/tv?first_air_date.gte=2025-01-01&with_genres=18&vote_count.gte=100&sort_by=popularity.desc вяртае драматычныя серыялы, што пачалі выходзіць у 2025 годзе або пазней. Падрабязнасці па выніку глядзіце на старонцы серыялы.

Памылкі

Набор фільтраў, пад які нічога не падыходзіць, не з’яўляецца памылкай. Вы атрымаеце HTTP 200 з пустым масівам results і total_results, роўным 0. Гл. памылкі і ліміты запытаў.

Практычныя заўвагі

• Edge-кэш захоўвае кожны асобны набор фільтраў 30 хвілін і падзяляе яго паміж ключамі. Ключ кэшу будуецца па адсартаваным запыце, таму парадак вашых параметраў не мае значэння.
• На старонцы 20 запісаў, апошняя старонка 500, таму адзін набор фільтраў дае да 10 000 запісаў. Каб пайсці глыбей, дзяліце запыт на вокны дат. Шырокі фільтр паказвае total_results, роўны 20001, гэта абмежаванне, а не рэальная колькасць.
• Заўсёды спалучайце sort_by=vote_average.desc з vote_count.gte. Без гэтага ўверсе збіраюцца фільмы з некалькімі галасамі.
• Id у фільтрах лікавыя. Id персон бярыце праз пошук, а id жанраў і стрымінгавых сэрвісаў са старонкі жанры і даведачныя спісы.
• Гатовыя спісы, напрыклад папулярныя або тыя, што зараз у пракаце, глядзіце на старонцы трэнды і спісы.