API גילוי

גילוי סרטים

GET /3/discover/movie מחזיר רשימה מדורגת של סרטים שמתאימים לכל מסנן ששלחתם, בסדר שבחרתם. זו נקודת הקצה לעמודי עיון, לרשימות "הטובים ביותר" ולהמלצות לפי היבט, והיא לא צריכה טקסט query. כשיש לכם כותרת שמשתמש הקליד, השתמשו בחיפוש במקום.

הדוגמה מציגה סרטי מדע בדיוני (מזהה ז'אנר 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שאילתה
  מזהי ז'אנרים. פסיק פירושו AND, תו קו אנכי פירושו OR.
• without_genresשאילתה
  מזהי ז'אנרים להחרגה.
• with_cast, with_crewשאילתה
  מזהי אנשים. מוצאים אותם עם חיפוש.
• with_peopleשאילתה
  מזהי אנשים שמופיעים כשחקנים או כצוות.
• with_companies, without_companiesשאילתה
  מזהי חברות הפקה לדרוש או להחריג. פסיק וקו אנכי פועלים כמו ב-with_genres.
• with_keywords, without_keywordsשאילתה
  מזהי מילות מפתח לדרוש או להחריג. ראו מילות מפתח.
• with_origin_countryשאילתה
  קוד מדינת הפקה בן 2 אותיות גדולות כמו 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שאילתה
  קוד מדינה בן 2 אותיות גדולות. מחליף את 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שאילתה
  שפת מקור כקוד בן 2 אותיות כמו fr או ko.
• with_watch_providersשאילתה
  מזהי ספקים. דורש watch_region, ומתעלמים ממנו בלעדיו. המזהים מגיעים מעמוד ז'אנרים ורשימות חיפוש.
• watch_regionשאילתה
  קוד מדינה בן 2 אותיות גדולות לזמינות אצל ספקים.
• 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 ארוכות קוצרו.

שילוב מסננים

פרמטרים נפרדים משתלבים עם AND. בתוך פרמטר אחד פסיק פירושו AND ותו קו אנכי פירושו OR. בכתובת גולמית הקו האנכי נכתב %7C, ולקוחות שמקודדים ערכי שאילתה עושים זאת בשבילכם.

with_original_language מסנן לפי השפה שבה הכותר נעשה, והוא מקבל גם קודים מחוץ ל-14 השפות המוגשות, למשל ja או ko. הפרמטר language עדיין קובע את שפת הטקסט שמקבלים בחזרה. בשורת הספקים, 8 הוא Netflix. את מזהי הספקים קראו מ-/watch/providers/movie.

גילוי סדרות

GET /3/discover/tv משתמש באותה מעטפת ובאותו דפדוף. הפריטים מחזיקים name, original_name, first_air_date, origin_country ו-genre_ids, ומזהי הז'אנרים מגיעים מ-/genre/tv/list, שמחזיק את מזהי הטלוויזיה המאוחדים כמו 10765 למדע בדיוני ופנטזיה.

בקשה כמו /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. ראו שגיאות ומגבלות קצב.

הערות מעשיות

• הקצה שומר כל קבוצת מסננים נפרדת במטמון 30 דקות ומשתף אותה בין מפתחות. מפתח המטמון משתמש בשאילתה ממוינת, ולכן סדר הפרמטרים שלכם לא משנה.
• עמוד מחזיק 20 פריטים והעמוד האחרון הוא 500, ולכן קבוצת מסננים אחת מגיעה ל-10,000 פריטים. פצלו לפי חלונות תאריכים כדי להעמיק. מסנן רחב מדווח על total_results של 20001, שהוא תקרה ולא ספירה אמיתית.
• תמיד שלבו את sort_by=vote_average.desc עם vote_count.gte. בלעדיו כותרים עם כמה הצבעות ממלאים את ראש הרשימה.
• המזהים במסננים הם מספריים. את מזהי האנשים קחו מעמוד חיפוש, ואת מזהי הז'אנרים והספקים מעמוד ז'אנרים ורשימות חיפוש.
• לרשימות מוכנות כמו פופולריים או מוצגים עכשיו, ראו טרנדים ורשימות.