# API חיפוש > נקודות הקצה של החיפוש הופכות שאילתת טקסט למזהים. GET /3/search/movie מוצא סרטים, ונתיבים אחים מוצאים סדרות, אנשים, אוספים, חברות ומילות מפתח, או את כל המדיה בבת אחת עם multi. ה-JSON זהה ל-TMDB v3, התוצאות מחולקות ל-20 בעמוד, והקצה שומר שאילתה במטמון 10 דקות. ## נקודת קצה `GET /3/search/movie` ```bash curl "https://api.amodb.dev/3/search/movie?query=inception&year=2010" \ -H "Authorization: Bearer $AMODB_KEY" ``` תגובה: ```json { "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 offered a chance to regain his old life as payment for a task considered to be impossible: \"inception\", the implantation of another per...", "popularity": 60.9811, "poster_path": "/xlaY2zyzMfkhk0HSC5VUwzoZPU1.jpg", "release_date": "2010-07-15", "title": "Inception", "video": false, "vote_average": 8.373, "vote_count": 40461 }, { "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 } ``` ## חיפוש סרטים `GET /3/search/movie` מקבל שאילתת טקסט ומחזיר רשימה מחולקת לעמודים של סרטים תואמים, ההתאמה הטובה ביותר ראשונה. השתמשו בו כדי להפוך את מה שהמשתמש הקליד למזהה סרט, ואז קראו ל[פרטי סרט](https://amodb.dev/he/movies/) עם המזהה הזה. הדוגמה מחפשת את Inception, מוגבלת ל-2010, ומדפיסה מזהה, כותרת ותאריך יציאה. ```bash curl -sSf --get "https://api.amodb.dev/3/search/movie" \ --data-urlencode "query=inception" \ --data-urlencode "year=2010" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js 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); ``` ```python 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 '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; } ``` ```go 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` | integer | העמוד שביקשתם. | | `results` | array | עד 20 פריטים, ההתאמה הטובה ביותר ראשונה. | | `total_pages`, `total_results` | integer | גודל קבוצת התוצאות לשאילתה הזו. מוגבל ל-500 עמודים ול-10000 תוצאות. | | `id` | integer | מזהה הסרט לנקודת הקצה של הפרטים. | | `title`, `original_title` | string | הכותרת המתורגמת והכותרת המקורית. | | `original_language` | string | קוד של שתי אותיות לשפה שבה הסרט נוצר. | | `overview` | string | טקסט מתורגם, ריק כשאין תרגום. | | `release_date` | string | `YYYY-MM-DD`, ריק לכותרים בלי תאריך. | | `genre_ids` | array of integers | מזהי ז'אנרים, לא שמות. מפו אותם עם [ז'אנרים](https://amodb.dev/he/genres/). | | `poster_path`, `backdrop_path` | string או null | מצרפים ל-`https://img.amodb.dev/t/p/{size}`. | | `popularity`, `vote_average`, `vote_count` | number | ערכי דירוג וציון. | | `adult`, `video` | boolean | `adult` תמיד `false`. הערך `video` הוא `true` בפריטים שסומנו כתוכן וידאו. | ### תגובה לדוגמה ```json { "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` מתקבל בכולם ומתעלמים ממנו. | שיטה ונתיב | מה נמצא | פרמטרים נוספים | שדות הפריט | | ------------------------ | ----------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------- | | `GET /search/tv` | סדרות | `first_air_date_year`, `year`, `language` | `name`, `original_name`, `first_air_date`, `origin_country` | | `GET /search/person` | אנשים | `language` | `name`, `original_name`, `known_for_department`, `gender`, `profile_path`, `known_for` | | `GET /search/multi` | סרטים, סדרות ואנשים יחד | `language` | `media_type` ושדות הסוג הזה | | `GET /search/collection` | אוספי סרטים | `language` | `name`, `original_name`, `overview`, `poster_path`, `backdrop_path` | | `GET /search/company` | חברות הפקה | אין | `name`, `logo_path`, `origin_country` | | `GET /search/keyword` | מילות מפתח | אין | `id`, `name` | בסדרות, `first_air_date_year` משאיר סדרות שתאריך השידור הראשון שלהן באותה שנה, ואילו `year` משאיר גם סדרות ישנות יותר ששודרו באותה שנה. חיפוש של `the` עם `year=2010` מחזיר את The Simpsons, ששודרה לראשונה ב-1989, ואילו אותו חיפוש עם `first_air_date_year=2010` לא מחזיר אותה. אם שולחים את שניהם, שניהם חייבים להתאים. פריטי אנשים נושאים עד 3 כותרי `known_for`, כל אחד עם `media_type`. הנתיב `/search/multi` מתעלם מ-`year`. ישויות שנמצאו כאן ממשיכות ב[סדרות טלוויזיה](https://amodb.dev/he/tv-series/), ב[אנשים](https://amodb.dev/he/people/), ב[אוספים](https://amodb.dev/he/collections/), ב[חברות ורשתות](https://amodb.dev/he/companies-networks/) וב[מילות מפתח](https://amodb.dev/he/keywords/). ### חיפוש multi הערך `media_type` הוא `movie`, `tv` או `person`, והוא אומר לכם אילו שדות לצפות. פריטי סרטים נושאים `title`, ופריטי סדרות ואנשים נושאים `name`. ```js 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 בנתיבים האלה כאל אין תוצאות, אלא אם הוא חוזר גם בשאילתות שאתם יודעים שמתאימות. | HTTP | status_code | מתי | | ---- | ----------- | ---------------------------------------------------------------------------------------- | | 401 | 7 | המפתח חסר או שגוי. | | 402 | 36 | תקופת המסלול הסתיימה. | | 405 | 37 | קראתם לשיטת כתיבה. | | 429 | 25 | מעל הבקשות שלכם לדקה. המתינו `Retry-After` שניות. | | 500 | 11 | שאילתת סרט, multi, מילת מפתח, חברה או אוסף שאין לה התאמה, או `page` מחוץ לטווח 1 עד 500. | | 504 | 24 | השרת האחורי לא ענה בזמן. נסו שוב פעם אחת. | הרשימה המלאה בעמוד [שגיאות](https://amodb.dev/he/errors/), והחלונות בעמוד [מגבלות קצב](https://amodb.dev/he/rate-limits/). ## הערות מעשיות - הקצה שומר חיפוש במטמון 10 דקות ומשתף את העותק בין מפתחות. כל קריאה עדיין נספרת מול 20, 40 או 120 הבקשות שלכם לדקה, כי מגבלת הקצב רצה לפני המטמון. - בתיבת חיפוש, המתינו 300 מילישניות אחרי ההקשה האחרונה וביטלו את הבקשה שבדרך. תיבה ששולחת בקשה בכל הקשה יכולה לנצל מסלול של 20 בקשות לדקה בתוך שניות. - הפכו את השאילתה לאותיות קטנות וחתכו רווחים לפני שאתם משתמשים בה כמפתח מטמון בצד שלכם. - כדי לחפש כותר לפי מזהה IMDb, דלגו על החיפוש והשתמשו ב[חיפוש לפי מזהה חיצוני](https://amodb.dev/he/find-by-external-id/). - מזהה מילת מפתח מ-`/search/keyword` מזין את המסנן `with_keywords` ב[API גילוי](https://amodb.dev/he/discover/), ומזהה חברה מזין את `with_companies`. ## שאלות ותשובות ### כמה תוצאות מחזיר עמוד חיפוש אחד? כל עמוד מכיל 20 תוצאות, והפרמטר page נע בין 1 ל-500. קראו את total_pages ו-total_results מהתגובה, וצמצמו שאילתות עמומות עם year או primary_release_year. ### האם חיפושים שמורים במטמון עדיין נספרים במגבלת הקצב שלי? כן. הקצה שומר חיפוש במטמון 10 דקות ומשתף את העותק בין מפתחות, אבל בדיקת המפתח ומגבלת הקצב רצות לפני חיפוש המטמון, ולכן כל קריאה נספרת פעם אחת. ### אפשר לחפש לפי מזהה IMDb בנקודות הקצה האלה? לא. השתמשו במקום זה ב-GET /3/find/{external_id} עם external_source=imdb_id. הוא מחזיר movie_results, tv_results ו-person_results למזהה הזה, והוא מוסבר בעמוד החיפוש לפי מזהה חיצוני. ### באיזו שפה התוצאות? הפרמטר language קובע כותרות ותקצירים, ברירת מחדל en-US. תגיות מחוץ ל-14 שפות הבסיס חוזרות לאנגלית. הכותרות המקוריות נשארות זמינות ב-original_title וב-original_name. ## עמודים קשורים - [API פרטי סרט](https://amodb.dev/he/movies/): API פרטי סרט עם אותם נתיבים ו-JSON כמו TMDB v3. קבלו סרט לפי מזהה, הוסיפו קרדיטים, דירוגים, מצבי רוח ופסקולים עם append_to_response, ב-14 שפות. - [API סדרות טלוויזיה](https://amodb.dev/he/tv-series/): API סדרות טלוויזיה עם אותם נתיבים ו-JSON כמו TMDB v3. קבלו סדרה לפי מזהה ב-GET /3/tv/{series_id} עם עונות, רשתות והפרק הבא, וגם סיווגי גיל וספקי צפייה. - [API פרטי אדם](https://amodb.dev/he/people/): API פרטי אדם עם אותם נתיבים ו-JSON כמו TMDB v3. קבלו שחקן או איש צוות לפי מזהה, עם ביוגרפיה, פילמוגרפיה, מזהים חיצוניים, תמונות פרופיל והרשימה הפופולרית. - [API גילוי](https://amodb.dev/he/discover/): Discover API עם אותם מסננים כמו TMDB v3. הציגו סרטים וסדרות לפי ז'אנר, שחקנים, חברה, מילת מפתח, שנה, דירוג, משך וספק סטרימינג, עם מיון ודפדוף בתוצאות. - [חיפוש לפי מזהה חיצוני](https://amodb.dev/he/find-by-external-id/): חפשו סרט, סדרה או אדם לפי מזהה IMDb, TVDB, Wikidata או Kinopoisk עם נקודת הקצה find של TMDB v3, וקראו מזהים חיצוניים ועובדות Wikidata על כל כותר. - [מגבלות קצב](https://amodb.dev/he/rate-limits/): amodb מגביל כל מפתח לפי בקשות לדקה בחלון נע של 60 שניות: 20, 40 או 120 בהתאם למסלול שלכם. קראו את כותרות מגבלת הקצב וטפלו ב-429 עם Retry-After. עודכן: 2026-10-18. Source: https://amodb.dev/he/search/