# Пошук за зовнішнім ID > GET /3/find/{external_id} перетворює 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": [] } ``` ## Пошук проєкту за зовнішнім ID `GET /3/find/{external_id}` приймає id з іншої системи й повертає відповідні записи. Шлях містить id, а параметр запиту `external_source` вказує, з якої системи він походить. amodb приймає дванадцять джерел, і сім із них повертають записи: `imdb_id`, `tvdb_id`, `wikidata_id`, `kinopoisk_id`, `facebook_id`, `twitter_id` та `instagram_id`. Приклад зіставляє id IMDb `tt0137523` з id 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` | шлях | так | id в іншій системі, наприклад `tt0137523`. | | `external_source` | query | так | Одне з `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` | query | ні | Одна з 14 мов, наприклад `en` або `ru-RU`. Інші значення відкочуються на `en`. | | `api_key` | query | одне з двох | Ваш ключ. Використовуйте його або заголовок `Authorization: Bearer`. | Відсутній `external_source` або значення поза списком дають відповідь 400 зі `status_code` 22. Значення має бути малими літерами. ### Поля відповіді | Поле | Тип | Примітки | | -------------------- | ----- | ------------------------------------------------------------------------------------------------------ | | `movie_results` | array | Записи фільмів з тими самими полями, що й у результаті пошуку, плюс `media_type` зі значенням `movie`. | | `person_results` | array | Персони, знайдені за id. Кожна має `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` | Як виглядає id | Приклад | Зазвичай заповнений масив | | ------------------------------------------- | -------------------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------- | | `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" ``` ## Зовнішні ID відомого проєкту Зворотний напрямок забезпечує набір ендпоінтів `external_ids`. Вони повертають id, якими користуються інші системи, для запису, який у вас уже є. | Метод і шлях | Що повертає | Параметри | | -------------------------------------- | ------------------------------------------------------------------------------------------------ | ----------- | | `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` | 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` для сезонів і серій існують, але всі id в них нині `null`, тож пропустіть їх. ## Факти Wikidata `GET /3/movie/{movie_id}/wikidata` і `GET /3/tv/{tv_id}/wikidata` повертають id Wikidata проєкту та факти про нього: гроші, сусідні частини серії, сторінки Wikipedia, нагороди й місця. Кожен ключ присутній завжди. Невідомий факт це `null` для одиночного значення і `[]` для списку. | Метод і шлях | Що повертає | Параметри | | -------------------------------- | ------------------------------------------------- | ---------------------------- | | `GET /movie/{movie_id}/wikidata` | id Wikidata і факти | `movie_id`, `language` | | `GET /tv/{tv_id}/wikidata` | id 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 | id проєкту в 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 | Зіставляє код мови з назвою сторінки Wikipedia. Ключі це 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 | id проєкту в шляху `wikidata` не існує. | | 429 | 25 | Перевищено ліміт запитів на хвилину. Зачекайте стільки секунд, скільки вказано в `Retry-After`. | Невідомий зовнішній id у `find` не є помилкою: очікуйте, що всі п'ять масивів будуть порожніми. Ендпоінти `external_ids` для невідомого id також не повертають 404. Вони повертають 200, де кожен id дорівнює `null`. Див. [помилки](https://amodb.dev/uk/errors/) та [автентифікація](https://amodb.dev/uk/authentication/). ## Практичні поради - Збережіть id TMDB, щойно вперше розв'язали зовнішній id. Наступні виклики тоді пропускають `find` і йдуть одразу до шляху деталей, що економить один запит на проєкт. - Завжди перевіряйте, що потрібний масив має запис. `find` може повернути кілька масивів одночасно для одного id. - Деталі й зовнішні id кешуються на рівні CDN на 6 годин. Повторний пошук протягом цього часу повертає збережену відповідь. - `wikidata_id` працює в обидва боки: передайте його у `find`, щоб отримати проєкт, або прочитайте з `external_ids`, щоб послатися назовні. - Щоб перенести пошук за IMDb у стилі OMDb, див. [ендпоінт OMDb](https://amodb.dev/uk/omdb-endpoint/). Оцінки після розв'язання проєкту дивіться на сторінці [рейтинги](https://amodb.dev/uk/ratings/). ## Запитання й відповіді ### Які зовнішні джерела приймає find? Для external_source приймається дванадцять значень. Сім із них дають результат: imdb_id, tvdb_id, wikidata_id, kinopoisk_id, facebook_id, twitter_id та instagram_id. Решта п'ять повертають порожні масиви. Значення обов'язкове, пишеться малими літерами й точно, наприклад external_source=imdb_id. ### Чому find повертає п'ять масивів? Id може вказувати на фільм, персону, серіал, серію або сезон, тому відповідь містить окремий масив для кожного виду. В amodb записи містять лише movie_results, person_results і tv_results. Масиви tv_episode_results та tv_season_results завжди порожні. ### Що буде, якщо id невідомий? Ви отримаєте статус 200 з усіма п'ятьма порожніми масивами, як у TMDB. Перш ніж читати результат, переконайтеся, що хоча б один масив має запис. Відсутній або невідомий external_source це інший випадок: відповідь 400 зі status_code 22. ### Як отримати id 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/uk/movies/): API деталей фільму з тими самими шляхами та JSON, що в TMDB v3. Отримайте фільм за id, додайте акторів, рейтинги й настрої через append_to_response, 14 мовами. - [API серіалів](https://amodb.dev/uk/tv-series/): API серіалів з тими самими шляхами та JSON, що в TMDB v3. Отримайте серіал за id із сезонами, телемережами й наступною серією, плюс вікові рейтинги. - [Рейтинги фільмів і серіалів](https://amodb.dev/uk/ratings/): API рейтингів фільмів повертає оцінки IMDb, Kinopoisk, Metacritic, Rotten Tomatoes і TMDB для фільму чи серіалу одним викликом, з null для невідомих джерел. - [API деталей персони](https://amodb.dev/uk/people/): API деталей персони з тими самими шляхами та JSON, що в TMDB v3. Отримайте актора чи режисера за id: біографія, фільмографія, зовнішні id і список популярних. - [Ендпоінт, сумісний з OMDb](https://amodb.dev/uk/omdb-endpoint/): Сумісний з OMDb API ендпоінт на api.amodb.dev/omdb/. Шукайте за i або t, робіть пошук через s, читайте масив Ratings і зберігайте клієнт, змінивши базовий URL. - [Автентифікація](https://amodb.dev/uk/authentication/): Як надсилати ключ amodb: api_key у запиті, заголовок Authorization Bearer або apikey для викликів OMDb. Формат ключа, зберігання, заміна та помилки 401. Оновлено: 2026-10-18. Source: https://amodb.dev/uk/find-by-external-id/