API discover

Descoperă filme

GET /3/discover/movie întoarce o listă paginată de filme care se potrivesc cu fiecare filtru trimis, în ordinea pe care o alegi. Este endpoint-ul pentru pagini de răsfoire, liste „cele mai bune” și recomandări pe fațete și nu cere text query. Când ai un titlu tastat de un utilizator, folosește în schimb căutare.

Exemplul listează filme științifico-fantastice (ID de gen 878) cu cel puțin 1000 de voturi, cele mai bine cotate primele.

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

Parametri

• api_keyinterogareuna dintre cele două
  Cheia ta. Folosește-o pe aceasta sau antetul Authorization: Bearer.
• sort_byinterogare
  Câmp și direcție, precum vote_average.desc. Câmpuri: popularity, vote_average, vote_count, primary_release_date, revenue, title, original_title, fiecare cu .asc sau .desc. title și original_title sortează amândouă după titlul original. O valoare necunoscută revine la popularity.desc, care este și valoarea implicită.
• with_genresinterogare
  ID-uri de gen. Virgula înseamnă AND, bara verticală înseamnă OR.
• without_genresinterogare
  ID-uri de gen de exclus.
• with_cast, with_crewinterogare
  ID-uri de persoane. Găsește-le cu căutare.
• with_peopleinterogare
  ID-uri de persoane care apar ca distribuție sau echipă.
• with_companies, without_companiesinterogare
  ID-uri de companii de producție de cerut sau de exclus. Virgula și bara verticală funcționează ca la with_genres.
• with_keywords, without_keywordsinterogare
  ID-uri de cuvinte-cheie de cerut sau de exclus. Vezi cuvinte-cheie.
• with_origin_countryinterogare
  Cod de țară de producție din 2 litere majuscule, precum FR.
• primary_release_yearinterogare
  An din patru cifre al datei principale de lansare.
• yearinterogare
  An din patru cifre. Se potrivește cu orice dată de lansare din acel an, deci întoarce mai multe titluri decât primary_release_year.
• primary_release_date.gte, primary_release_date.lteinterogare
  Limita inferioară și superioară pentru data principală de lansare, YYYY-MM-DD.
• release_date.gte, release_date.lteinterogare
  Limita inferioară și superioară pentru orice dată de lansare din orice țară, YYYY-MM-DD.
• regioninterogare
  Cod de țară din 2 litere majuscule. Înlocuiește release_date din fiecare rezultat cu data din acea țară. Nu elimină titluri.
• certification_country, certificationinterogare
  Filtru de clasificare pe vârste, de exemplu US și PG. certification este ignorat fără o țară. certification.gte și certification.lte dau un interval.
• vote_average.gte, vote_average.lteinterogare
  Scorul mediu minim și maxim, de la 0 la 10.
• vote_count.gte, vote_count.lteinterogare
  Numărul minim și maxim de voturi.
• with_runtime.gte, with_runtime.lteinterogare
  Durata minimă și maximă în minute.
• with_original_languageinterogare
  Limba originală ca cod din 2 litere, precum fr sau ko.
• with_watch_providersinterogare
  ID-uri de furnizori. Cere watch_region și este ignorat fără el. ID-urile vin de la genuri și liste de referință.
• watch_regioninterogare
  Cod de țară din 2 litere majuscule pentru disponibilitatea furnizorilor.
• include_adultinterogare
  Acceptat și ignorat. Titlurile pentru adulți nu sunt întoarse niciodată.
• languageinterogare
  Etichetă TMDB precum en-US sau pl-PL. Sunt servite 14 limbi de bază. Implicit en-US.
• pageinterogare
  Numărul paginii de la 1 la 500. Implicit 1.

Câmpurile răspunsului

Exemplu de răspuns

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

Răspunsul a fost preluat de la API-ul live pentru cererea din exemplu. Este tăiat la 3 din cele 20 de intrări de pe pagina 1, iar șirurile overview lungi sunt scurtate.

Combină filtrele

Parametrii separați se combină cu AND. În interiorul unui parametru, virgula înseamnă AND, iar bara verticală înseamnă OR. Într-un URL brut bara se scrie %7C, iar clienții care codifică valorile interogării fac asta pentru tine.

with_original_language filtrează după limba în care a fost făcut un titlu și acceptă coduri din afara celor 14 limbi servite, de exemplu ja sau ko. Parametrul language decide în continuare limba textului primit înapoi. În rândul cu furnizorul, 8 este Netflix. Citește ID-urile furnizorilor de la /watch/providers/movie.

Descoperă seriale TV

GET /3/discover/tv folosește același plic și aceeași paginare. Intrările conțin name, original_name, first_air_date, origin_country și genre_ids, iar ID-urile de gen vin de la /genre/tv/list, care conține ID-urile TV îmbinate, precum 10765 pentru Sci-Fi and Fantasy.

O cerere precum /discover/tv?first_air_date.gte=2025-01-01&with_genres=18&vote_count.gte=100&sort_by=popularity.desc listează serialele dramă care au început în 2025 sau mai târziu. Citește un rezultat în detaliu la seriale TV.

Erori

Un set de filtre care nu se potrivește cu nimic nu este o eroare. Primești HTTP 200 cu un array results gol și total_results 0. Vezi erori și limite de cereri.

Note practice

• Marginea ține în cache fiecare set distinct de filtre 30 de minute și îl partajează între chei. Cheia de cache folosește interogarea sortată, deci ordinea parametrilor tăi nu contează.
• O pagină are 20 de intrări, iar ultima pagină este 500, deci un set de filtre ajunge la 10,000 de intrări. Împarte pe ferestre de date ca să mergi mai adânc. Un filtru larg raportează total_results 20001, ceea ce este un plafon și nu o numărătoare reală.
• Asociază mereu sort_by=vote_average.desc cu vote_count.gte. Fără el, titlurile cu câteva voturi aglomerează vârful.
• ID-urile din filtre sunt numerice. Ia ID-urile de persoane de la căutare, iar ID-urile de gen și de furnizor de la genuri și liste de referință.
• Pentru liste gata făcute, precum populare sau în cinematografe acum, vezi tendințe și liste.