# חיפוש לפי מזהה חיצוני > GET /3/find/{external_id} הופך מזהה של IMDb, TVDB, Wikidata, Kinopoisk, Facebook, Twitter או Instagram לתוצאות בסגנון TMDB, ונקודות הקצה external_ids עושות את הכיוון ההפוך. נקודת קצה של Wikidata מוסיפה תקציב, הכנסות קופות, פרסים וכותרים קשורים לסרט או לסדרה. הכול משתמש במפתח הרגיל שלכם. ## נקודת קצה `GET /3/find/{external_id}` ```bash curl "https://api.amodb.dev/3/find/tt0137523?external_source=imdb_id" \ -H "Authorization: Bearer $AMODB_KEY" ``` תגובה: ```json { "movie_results": [ { "adult": false, "backdrop_path": "/c6OLXfKAk5BKeR6broC8pYiCquX.jpg", "genre_ids": [ 18, 53 ], "id": 550, "original_language": "en", "original_title": "Fight Club", "overview": "A ticking-time-bomb insomniac and a slippery soap salesman channel primal male aggression into a shocking new form of therapy. Their concept catches on, with underground \"fight clubs\" forming in every town, until an eccentric gets in the wa...", "popularity": 39.0054, "poster_path": "/jSziioSwPVrOy9Yow3XhWIBDjq1.jpg", "release_date": "1999-10-15", "title": "Fight Club", "video": false, "vote_average": 8.437, "vote_count": 33042, "media_type": "movie" } ], "person_results": [], "tv_results": [], "tv_episode_results": [], "tv_season_results": [] } ``` ## חיפוש כותר לפי מזהה חיצוני `GET /3/find/{external_id}` מקבל מזהה ממערכת אחרת ומחזיר את הרשומות התואמות. הנתיב מחזיק את המזהה, והפרמטר `external_source` אומר מאיזו מערכת הוא מגיע. amodb מקבל שנים עשר מקורות ושבעה מהם נפתרים לרשומות: `imdb_id`, `tvdb_id`, `wikidata_id`, `kinopoisk_id`, `facebook_id`, `twitter_id` ו-`instagram_id`. הדוגמה ממפה את מזהה ה-IMDb בשם `tt0137523` למזהה TMDB. ```bash curl -sf "https://api.amodb.dev/3/find/tt0137523?external_source=imdb_id" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js const url = 'https://api.amodb.dev/3/find/tt0137523?external_source=imdb_id'; const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } }); if (!res.ok) throw new Error(`amodb returned ${res.status}`); const found = await res.json(); const movie = found.movie_results[0]; console.log(movie ? `${movie.id} ${movie.title}` : 'no match'); ``` ```python import os import requests r = requests.get( "https://api.amodb.dev/3/find/tt0137523", params={"external_source": "imdb_id"}, headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"}, timeout=10, ) r.raise_for_status() results = r.json()["movie_results"] print(f"{results[0]['id']} {results[0]['title']}" if results else "no match") ``` ```php 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"); } $movies = json_decode($body, true)['movie_results']; echo $movies ? $movies[0]['id'] . ' ' . $movies[0]['title'] : 'no match', PHP_EOL; ``` ```go package main import ( "encoding/json" "fmt" "net/http" "os" "time" ) type Found struct { MovieResults []struct { ID int `json:"id"` Title string `json:"title"` } `json:"movie_results"` } func main() { url := "https://api.amodb.dev/3/find/tt0137523?external_source=imdb_id" req, _ := http.NewRequest("GET", url, 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 f Found if err := json.NewDecoder(res.Body).Decode(&f); err != nil { panic(err) } if len(f.MovieResults) == 0 { fmt.Println("no match") return } fmt.Println(f.MovieResults[0].ID, f.MovieResults[0].Title) } ``` ### פרמטרים | פרמטר | מיקום | חובה | תיאור | | ----------------- | ------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `external_id` | נתיב | כן | המזהה במערכת האחרת, למשל `tt0137523`. | | `external_source` | שאילתה | כן | אחד מ-`imdb_id`, `tvdb_id`, `wikidata_id`, `kinopoisk_id`, `facebook_id`, `twitter_id`, `instagram_id`. עוד חמישה מתקבלים ולא מחזירים דבר: `freebase_mid`, `freebase_id`, `tvrage_id`, `tiktok_id`, `youtube_id`. | | `language` | שאילתה | לא | אחת מ-14 שפות כמו `en` או `ru-RU`. ערכים אחרים חוזרים ל-`en`. | | `api_key` | שאילתה | אחד משניים | המפתח שלכם. השתמשו בו או בכותרת `Authorization: Bearer`. | `external_source` חסר, או כזה שאינו ברשימה, עונה 400 עם `status_code` 22. הערך חייב להיות באותיות קטנות. ### שדות התגובה | שדה | סוג | הערות | | -------------------- | ----- | ------------------------------------------------------------------------------------------ | | `movie_results` | array | רשומות סרטים עם אותם שדות כמו בתוצאת חיפוש, בתוספת `media_type` שמוגדר ל-`movie`. | | `person_results` | array | אנשים שהמזהה תואם אליהם. בכל אחד `known_for` הוא מערך ריק ו-`media_type` מוגדר ל-`person`. | | `tv_results` | array | רשומות סדרות עם `media_type` שמוגדר ל-`tv`. | | `tv_episode_results` | array | ריק תמיד. | | `tv_season_results` | array | ריק תמיד. | ### תגובה לדוגמה ```json { "movie_results": [ { "adult": false, "backdrop_path": "/c6OLXfKAk5BKeR6broC8pYiCquX.jpg", "genre_ids": [18, 53], "id": 550, "original_language": "en", "original_title": "Fight Club", "overview": "A ticking-time-bomb insomniac and a slippery soap salesman channel primal male aggression into a shocking n...", "popularity": 39.0054, "poster_path": "/jSziioSwPVrOy9Yow3XhWIBDjq1.jpg", "release_date": "1999-10-15", "title": "Fight Club", "video": false, "vote_average": 8.437, "vote_count": 33039, "media_type": "movie" } ], "person_results": [], "tv_results": [], "tv_episode_results": [], "tv_season_results": [] } ``` התקציר קוצר. ### איזה מקור מוצא מה | `external_source` | איך נראה המזהה | דוגמה | מערך התוצאות הרגיל | | ------------------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------- | | `imdb_id` | `tt` ואחריו ספרות לכותרים, `nm` ואחריו ספרות לאנשים | `tt0137523`, `nm0000093` (Brad Pitt) | `movie_results`, `tv_results` או `person_results` | | `tvdb_id` | מספר | `81189` (Breaking Bad) | `tv_results` | | `wikidata_id` | `Q` ואחריו ספרות | `Q190050` (Fight Club), `Q1079` (Breaking Bad), `Q35332` (Brad Pitt) | `movie_results`, `tv_results` או `person_results` | | `kinopoisk_id` | מספר | `361` (Fight Club), `404900` (Breaking Bad) | `movie_results` או `tv_results` | | `facebook_id`, `twitter_id`, `instagram_id` | שם חשבון | `FightClub` | תלוי בחשבון | שם חשבון אחד יכול להתאים ליותר מכותר אחד. למשל `instagram_id=breakingbad` מחזיר את הסדרה ואת הסרט El Camino, ולכן קראו כל מערך. ```bash curl -sf "https://api.amodb.dev/3/find/361?external_source=kinopoisk_id" \ -H "Authorization: Bearer $AMODB_KEY" ``` ## מזהים חיצוניים של כותר מוכר הכיוון ההפוך הוא קבוצה של נקודות קצה `external_ids`. הן מחזירות את המזהים שמערכות אחרות משתמשות בהם לרשומה שכבר יש לכם. | שיטה ונתיב | מה מוחזר | פרמטרים | | -------------------------------------- | ------------------------------------------------------------------------------------------------ | ----------- | | `GET /movie/{movie_id}/external_ids` | `imdb_id`, `wikidata_id`, `facebook_id`, `instagram_id`, `twitter_id`, `kinopoisk_id` | `movie_id` | | `GET /tv/{tv_id}/external_ids` | אותו דבר, ובנוסף `freebase_mid`, `freebase_id`, `tvdb_id`, `tvrage_id` | `tv_id` | | `GET /person/{person_id}/external_ids` | `imdb_id`, `wikidata_id`, `facebook_id`, `instagram_id`, `tiktok_id`, `twitter_id`, `youtube_id` | `person_id` | מזהה שאין לכותר חוזר כ-`null`. המזהה `kinopoisk_id` הוא מחרוזת ונוכח בסרט או בסדרה רק כש-amodb מכיר אותו. תשובה אמיתית עבור `/3/movie/550/external_ids`: ```json { "id": 550, "imdb_id": "tt0137523", "wikidata_id": "Q190050", "facebook_id": "FightClub", "instagram_id": null, "twitter_id": null, "kinopoisk_id": "361" } ``` תשובה אמיתית עבור `/3/tv/1396/external_ids`: ```json { "id": 1396, "imdb_id": "tt0903747", "freebase_mid": null, "freebase_id": null, "tvdb_id": 81189, "tvrage_id": null, "wikidata_id": "Q1079", "facebook_id": "BreakingBad", "instagram_id": "breakingbad", "twitter_id": "BreakingBad", "kinopoisk_id": "404900" } ``` נקודות הקצה `external_ids` של עונה ופרק קיימות, אבל כל המזהים בהן הם `null` כיום, ולכן דלגו עליהן. ## עובדות Wikidata `GET /3/movie/{movie_id}/wikidata` ו-`GET /3/tv/{tv_id}/wikidata` מחזירים את מזהה ה-Wikidata של כותר ועובדות עליו: כסף, שכנים בסדרת סרטים, עמודי ויקיפדיה, פרסים ומקומות. כל מפתח קיים תמיד. עובדה לא ידועה היא `null` לערך בודד ו-`[]` לרשימה. | שיטה ונתיב | מה מוחזר | פרמטרים | | -------------------------------- | --------------------------------------- | ---------------------- | | `GET /movie/{movie_id}/wikidata` | מזהה Wikidata ועובדות | `movie_id`, `language` | | `GET /tv/{tv_id}/wikidata` | מזהה Wikidata ועובדות | `tv_id`, `language` | | `append_to_response=wikidata` | אותו בלוק תחת `wikidata`, עם ה-`id` שלו | מתווסף לקריאת פרטים | זו התשובה עבור Fight Club (סרט 550), מקוצרת לגודל קריא: ```json { "id": 550, "wikidata_id": "Q190050", "budget": { "value": 63000000, "currency": "USD" }, "box_office": { "value": 101209702, "currency": "USD", "worldwide": true }, "follows": null, "followed_by": null, "sitelinks": { "en": "Fight Club", "ru": "Бойцовский клуб (фильм)", "uk": "Бійцівський клуб (фільм)" }, "awards": [ { "wikidata_id": "Q28044798", "label": "Empire Awards, UK for best british actress" }, { "wikidata_id": "Q943908", "label": "Jupiter Award", "year": 2000 } ], "nominations": [ { "wikidata_id": "Q488645", "label": "Academy Award for Best Sound Editing", "year": 2000 } ], "based_on": [ { "wikidata_id": "Q837283", "label": "Fight Club", "author": { "wikidata_id": "Q268181", "label": "Chuck Palahniuk" } } ], "filming_locations": [ { "wikidata_id": "Q65", "label": "Los Angeles" } ], "narrative_locations": [ { "wikidata_id": "Q65", "label": "Los Angeles" } ], "original_broadcasters": [] } ``` באובייקט `sitelinks` יש 14 פריטים וב-`awards` יש 5. שניהם קוצרו כאן. | שדה | סוג | הערות | | ------------------------------------------------------------------- | -------------- | -------------------------------------------------------------------------- | | `id` | integer | מזהה ה-TMDB של הכותר. הוא נשאר כשמשתמשים ב-`append_to_response`. | | `wikidata_id` | string או null | פריט Wikidata כמו `Q190050`. | | `budget` | object או null | `value` הוא מספר שלם מעוגל ו-`currency` הוא קוד ISO או `null`. | | `box_office` | object או null | כמו `budget`, ובנוסף `worldwide` שמוגדר ל-`true` או ל-`false`. | | `follows`, `followed_by` | object או null | הכותר הקודם והבא בסדרת סרטים, כקישור. | | `sitelinks` | object | ממפה קוד שפה לשם עמוד בוויקיפדיה. המפתחות הם 14 השפות המוגשות. `{}` כשאין. | | `awards`, `nominations` | array | קישורים עם `year` אופציונלי. | | `based_on` | array | יצירות מקור עם `wikidata_id`, `label` ואובייקט `author` או `null`. | | `filming_locations`, `narrative_locations`, `original_broadcasters` | array | קישורים. ב-Breaking Bad יש AMC ב-`original_broadcasters`. | לקישור יש `wikidata_id`, `label` וכשהפריט הוא כותר בקטלוג גם `tmdb_id` ו-`media_type`. עבור The Matrix Reloaded (סרט 604) השכנים הם קישורים לסרטים 603 ו-605: ```json { "follows": { "wikidata_id": "Q83495", "label": "The Matrix", "tmdb_id": 603, "media_type": "movie" }, "followed_by": { "wikidata_id": "Q207536", "label": "The Matrix Revolutions", "tmdb_id": 605, "media_type": "movie" } } ``` כל `label` מגיע ב-`language` של הבקשה וחוזר לאנגלית. עם `language=ru` המחבר שלמעלה מופיע כ-`Чак Паланик`. ## שגיאות שגיאות משתמשות בגוף של TMDB, למשל `{"success": false, "status_code": 7, "status_message": "Invalid API key: You must be granted a valid key."}`. | HTTP | status_code | מתי | | ---- | ----------- | ----------------------------------------------------- | | 400 | 22 | `external_source` חסר, לא באותיות קטנות או לא ברשימה. | | 401 | 7 | המפתח חסר או שגוי. | | 402 | 36 | תקופת המסלול הסתיימה. | | 404 | 34 | מזהה הכותר בנתיב `wikidata` לא קיים. | | 429 | 25 | מעל הבקשות שלכם לדקה. המתינו `Retry-After` שניות. | מזהה חיצוני לא מוכר ב-`find` אינו שגיאה: צפו לחמשת המערכים ריקים. נקודות הקצה `external_ids` גם הן לא עונות 404 למזהה לא מוכר. הן עונות 200 עם כל מזהה `null`. ראו [שגיאות](https://amodb.dev/he/errors/) ו[אימות](https://amodb.dev/he/authentication/). ## הערות מעשיות - שמרו את מזהה ה-TMDB בפעם הראשונה שאתם פותרים מזהה חיצוני. קריאות מאוחרות יותר מדלגות על `find` ועוברות ישר לנתיב הפרטים, וזה חוסך בקשה אחת לכל כותר. - תמיד בדקו שהמערך שאתם רוצים מכיל פריט. `find` יכול להחזיר כמה מערכים בבת אחת למזהה אחד. - פרטים ומזהים חיצוניים נשמרים בקצה במטמון 6 שעות. חיפוש חוזר בתוך הזמן הזה מחזיר את התשובה השמורה. - `wikidata_id` עובד בשני הכיוונים: העבירו אותו ל-`find` כדי לקבל כותר, או קראו אותו מ-`external_ids` כדי ליצור קישור החוצה. - להעברת חיפושי IMDb בסגנון OMDb ראו [נקודת הקצה OMDb](https://amodb.dev/he/omdb-endpoint/). לציונים אחרי שפתרתם כותר ראו [דירוגים](https://amodb.dev/he/ratings/). ## שאלות ותשובות ### אילו מקורות חיצוניים find מקבל? שנים עשר ערכים מתקבלים ב-external_source. שבעה מהם נפתרים: imdb_id, tvdb_id, wikidata_id, kinopoisk_id, facebook_id, twitter_id ו-instagram_id. חמשת האחרים מחזירים מערכים ריקים. הערך חובה, באותיות קטנות ומדויק, למשל external_source=imdb_id. ### למה find מחזיר חמישה מערכים? מזהה יכול להצביע על סרט, אדם, סדרה, פרק או עונה, ולכן בתגובה יש מערך אחד לכל סוג. ב-amodb רק movie_results, person_results ו-tv_results מכילים פריטים. tv_episode_results ו-tv_season_results ריקים תמיד. ### מה קורה כשהמזהה לא מוכר? מקבלים סטטוס 200 עם חמשת המערכים ריקים, כמו ב-TMDB. בדקו שלפחות מערך אחד מכיל פריט לפני שקוראים אותו. external_source חסר או לא מוכר שונה: הוא עונה 400 עם status_code 22. ### איך משיגים מזהה Kinopoisk לכותר שכבר יש לי? קראו לנקודת הקצה external_ids של הסרט או הסדרה. היא מחזירה את kinopoisk_id כמחרוזת, למשל 361 ל-Fight Club, או null כש-amodb לא מכיר אותו. העבירו את המחרוזת ל-find עם external_source=kinopoisk_id כדי לחזור. ### אפשר לצרף את wikidata לקריאת פרטים? כן. הוסיפו append_to_response=wikidata לבקשת פרטים של סרט או סדרה, ובלוק ה-Wikidata יגיע תחת המפתח wikidata, באותה בקשה ובלי קריאה נוספת. ## עמודים קשורים - [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} עם עונות, רשתות והפרק הבא, וגם סיווגי גיל וספקי צפייה. - [דירוגי סרטים וסדרות](https://amodb.dev/he/ratings/): API דירוגי סרטים וסדרות שמחזיר ציוני IMDb, Kinopoisk, Metacritic, Rotten Tomatoes ו-TMDB לכותר בקריאה אחת, עם value ו-votes ו-null לכל מקור שאינו ידוע. - [API פרטי אדם](https://amodb.dev/he/people/): API פרטי אדם עם אותם נתיבים ו-JSON כמו TMDB v3. קבלו שחקן או איש צוות לפי מזהה, עם ביוגרפיה, פילמוגרפיה, מזהים חיצוניים, תמונות פרופיל והרשימה הפופולרית. - [נקודת קצה תואמת OMDb](https://amodb.dev/he/omdb-endpoint/): נקודת קצה תואמת OMDb API בכתובת api.amodb.dev/omdb/. חפשו לפי i או t, חפשו עם s, קראו את המערך Ratings ושמרו את הלקוח שלכם בהחלפת כתובת הבסיס. - [אימות](https://amodb.dev/he/authentication/): איך שולחים את מפתח amodb: api_key בשאילתה, כותרת Authorization Bearer או apikey בקריאות OMDb. פורמט המפתח, שמירה, החלפה ושגיאות 401 שכדאי להכיר. עודכן: 2026-10-18. Source: https://amodb.dev/he/find-by-external-id/