API חיפוש

חיפוש סרטים

GET /3/search/movie מקבל שאילתת טקסט ומחזיר רשימה מחולקת לעמודים של סרטים תואמים, ההתאמה הטובה ביותר ראשונה. השתמשו בו כדי להפוך את מה שהמשתמש הקליד למזהה סרט, ואז קראו לפרטי סרט עם המזהה הזה.

הדוגמה מחפשת את Inception, מוגבלת ל-2010, ומדפיסה מזהה, כותרת ותאריך יציאה.

curl -sSf --get "https://api.amodb.dev/3/search/movie" \
  --data-urlencode "query=inception" \
  --data-urlencode "year=2010" \
  -H "Authorization: Bearer $AMODB_KEY"

const params = new URLSearchParams({ query: 'inception', year: '2010', language: 'en-US' });
const res = await fetch(`https://api.amodb.dev/3/search/movie?${params}`, {
  headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` },
});
if (!res.ok) throw new Error(`amodb returned ${res.status}`);
const { results, total_results } = await res.json();
console.log(`${total_results} matches`);
for (const m of results.slice(0, 5)) console.log(m.id, m.title, m.release_date);

import os
import requests

r = requests.get(
    "https://api.amodb.dev/3/search/movie",
    params={"query": "inception", "year": 2010, "language": "en-US"},
    headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
    timeout=10,
)
r.raise_for_status()
data = r.json()
print(data["total_results"], "matches")
for m in data["results"][:5]:
    print(m["id"], m["title"], m["release_date"])

<?php
$url = 'https://api.amodb.dev/3/search/movie?' . http_build_query([
    'query' => 'inception',
    'year' => 2010,
    '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['id'], ' ', $m['title'], ' ', $m['release_date'], PHP_EOL;
}

package main

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

type SearchPage struct {
	TotalResults int `json:"total_results"`
	Results      []struct {
		ID          int    `json:"id"`
		Title       string `json:"title"`
		ReleaseDate string `json:"release_date"`
	} `json:"results"`
}

func main() {
	q := url.Values{"query": {"inception"}, "year": {"2010"}, "language": {"en-US"}}
	req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/search/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 SearchPage
	if err := json.NewDecoder(res.Body).Decode(&p); err != nil {
		panic(err)
	}
	fmt.Println(p.TotalResults, "matches")
	for _, m := range p.Results {
		fmt.Println(m.ID, m.Title, m.ReleaseDate)
	}
}

פרמטרים

• queryשאילתהחובה
  טקסט לחיפוש. קודדו אותו כ-URL: רווחים הופכים ל-%20 או ל-+.
• api_keyשאילתהאחד משניים
  המפתח שלכם. השתמשו בו או בכותרת Authorization: Bearer.
• yearשאילתה
  שנה בת ארבע ספרות. משאיר סרטים עם תאריך יציאה כלשהו באותה שנה, בכל מדינה.
• primary_release_yearשאילתה
  שנה בת ארבע ספרות. מתאים רק לתאריך היציאה הראשי, ולכן יכול להחזיר פחות כותרים מ-year.
• regionשאילתה
  קוד מדינה של 2 אותיות גדולות, כמו US. מחליף את release_date בתאריך באותה מדינה כשהוא ידוע. הוא לא מסיר כותרים.
• include_adultשאילתה
  מתקבל ומתעלמים ממנו. כותרי תוכן למבוגרים לא מוחזרים לעולם.
• languageשאילתה
  תגית TMDB כמו en-US או it-IT. מוגשות 14 שפות בסיס, וכל שפה אחרת חוזרת לאנגלית. ברירת מחדל en-US.
• pageשאילתה
  מספר עמוד מ-1 עד 500. ברירת מחדל 1.

שדות התגובה

תגובה לדוגמה

{
  "page": 1,
  "results": [
    {
      "adult": false,
      "backdrop_path": "/zSBVQIvx4UIHoFf1oDvixHyIQrz.jpg",
      "genre_ids": [28, 878, 80],
      "id": 27205,
      "original_language": "en",
      "original_title": "Inception",
      "overview": "Cobb, a skilled thief who commits corporate espionage by infiltrating the subconscious of his targets is of...",
      "popularity": 60.9811,
      "poster_path": "/xlaY2zyzMfkhk0HSC5VUwzoZPU1.jpg",
      "release_date": "2010-07-15",
      "title": "Inception",
      "video": false,
      "vote_average": 8.373,
      "vote_count": 40459
    },
    {
      "adult": false,
      "backdrop_path": "/p8K8Z4yjaslJx5mTsIC5L6LJxQB.jpg",
      "genre_ids": [16, 28, 53],
      "id": 64956,
      "original_language": "en",
      "original_title": "Inception: The Cobol Job",
      "overview": "Cobb, Arthur and Nash are enlisted by Cobol Engineering.",
      "popularity": 1.9401,
      "poster_path": "/sNxqwtyHMNQwKWoFYDqcYTui5Ok.jpg",
      "release_date": "2010-12-07",
      "title": "Inception: The Cobol Job",
      "video": false,
      "vote_average": 7.2,
      "vote_count": 320
    },
    {
      "adult": false,
      "backdrop_path": null,
      "genre_ids": [10402],
      "id": 973484,
      "original_language": "en",
      "original_title": "Inception: Music from the Motion Picture",
      "overview": "The Special Features Blu-ray disc contains a lossless DTS-HD MA 5.1 surround mix of the Inception soundtrack.",
      "popularity": 0.4911,
      "poster_path": "/7uM4DyRVAcgagvhZoWrkrqMPbqV.jpg",
      "release_date": "2010-12-07",
      "title": "Inception: Music from the Motion Picture",
      "video": true,
      "vote_average": 7,
      "vote_count": 3
    }
  ],
  "total_pages": 1,
  "total_results": 3
}

התגובה כוללת את שלוש ההתאמות. היא נשלפה מה-API החי, ורק מחרוזות overview ארוכות קוצרו.

נקודות קצה נוספות לחיפוש

כל נתיב בהמשך חולק את בסיס הכתובת https://api.amodb.dev/3, דורש query ומחזיר את אותה מעטפת page, results, total_pages ו-total_results. כל אחד מקבל גם page מ-1 עד 500. הפרמטר include_adult מתקבל בכולם ומתעלמים ממנו.

בסדרות, first_air_date_year משאיר סדרות שתאריך השידור הראשון שלהן באותה שנה, ואילו year משאיר גם סדרות ישנות יותר ששודרו באותה שנה. חיפוש של the עם year=2010 מחזיר את The Simpsons, ששודרה לראשונה ב-1989, ואילו אותו חיפוש עם first_air_date_year=2010 לא מחזיר אותה. אם שולחים את שניהם, שניהם חייבים להתאים. פריטי אנשים נושאים עד 3 כותרי known_for, כל אחד עם media_type. הנתיב /search/multi מתעלם מ-year.

ישויות שנמצאו כאן ממשיכות בסדרות טלוויזיה, באנשים, באוספים, בחברות ורשתות ובמילות מפתח.

חיפוש multi

הערך media_type הוא movie, tv או person, והוא אומר לכם אילו שדות לצפות. פריטי סרטים נושאים title, ופריטי סדרות ואנשים נושאים name.

const byType = { movie: [], tv: [], person: [] };
for (const r of results) byType[r.media_type]?.push(r.title || r.name);
console.log(byType);

שגיאות

הנתיבים /search/tv ו-/search/person עונים על שאילתה בלי התאמה ב-HTTP 200, מערך results ריק ו-total_results שהוא 0. כרגע /search/movie, /search/multi, /search/keyword, /search/company ו-/search/collection עונים על אותו מצב ב-HTTP 500 עם status_code 11. התייחסו ל-500 בנתיבים האלה כאל אין תוצאות, אלא אם הוא חוזר גם בשאילתות שאתם יודעים שמתאימות.

הרשימה המלאה בעמוד שגיאות, והחלונות בעמוד מגבלות קצב.

הערות מעשיות

• הקצה שומר חיפוש במטמון 10 דקות ומשתף את העותק בין מפתחות. כל קריאה עדיין נספרת מול 20, 40 או 120 הבקשות שלכם לדקה, כי מגבלת הקצב רצה לפני המטמון.
• בתיבת חיפוש, המתינו 300 מילישניות אחרי ההקשה האחרונה וביטלו את הבקשה שבדרך. תיבה ששולחת בקשה בכל הקשה יכולה לנצל מסלול של 20 בקשות לדקה בתוך שניות.
• הפכו את השאילתה לאותיות קטנות וחתכו רווחים לפני שאתם משתמשים בה כמפתח מטמון בצד שלכם.
• כדי לחפש כותר לפי מזהה IMDb, דלגו על החיפוש והשתמשו בחיפוש לפי מזהה חיצוני.
• מזהה מילת מפתח מ-/search/keyword מזין את המסנן with_keywords בAPI גילוי, ומזהה חברה מזין את with_companies.