# Поиск по внешнему 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` | строка запроса | да | Одно из значений `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` | массив | Записи фильмов с теми же полями, что и в результате поиска, плюс `media_type` со значением `movie`. | | `person_results` | массив | Персоны, найденные по ID. У каждой `known_for` это пустой массив, а `media_type` равно `person`. | | `tv_results` | массив | Записи сериалов, у которых `media_type` равно `tv`. | | `tv_episode_results` | массив | Всегда пустой. | | `tv_season_results` | массив | Всегда пустой. | ### Пример ответа ```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 проекта и факты о нем: деньги, соседние части серии, страницы Википедии, награды и места. Все ключи присутствуют всегда. Неизвестный факт равен `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` | целое число | ID проекта в TMDB. Сохраняется и при использовании `append_to_response`. | | `wikidata_id` | строка или null | Элемент Wikidata, например `Q190050`. | | `budget` | объект или null | `value` это округленное целое число, а `currency` это код ISO или `null`. | | `box_office` | объект или null | Как `budget`, плюс `worldwide` со значением `true` или `false`. | | `follows`, `followed_by` | объект или null | Предыдущий и следующий проект в серии фильмов, в виде ссылки. | | `sitelinks` | объект | Сопоставляет код языка с названием страницы Википедии. Ключи это 14 поддерживаемых языков. `{}`, если страниц нет. | | `awards`, `nominations` | массив | Ссылки с необязательным `year`. | | `based_on` | массив | Исходные произведения с `wikidata_id`, `label` и объектом `author` или `null`. | | `filming_locations`, `narrative_locations`, `original_broadcasters` | массив | Ссылки. У Breaking Bad в `original_broadcasters` указан AMC. | Ссылка содержит `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/ru/errors/) и [аутентификация](https://amodb.dev/ru/authentication/). ## Практические замечания - Сохраняйте ID TMDB при первом разрешении внешнего ID. Следующие вызовы пропускают `find` и сразу идут на путь сведений, что экономит один запрос на проект. - Всегда проверяйте, что в нужном массиве есть запись. `find` может вернуть сразу несколько массивов для одного ID. - Сведения и внешние ID кэшируются на edge-серверах на 6 часов. Повторный поиск в течение этого времени возвращает сохраненный ответ. - `wikidata_id` работает в обе стороны: передайте его в `find`, чтобы получить проект, или прочитайте из `external_ids`, чтобы сослаться на внешний ресурс. - Чтобы перенести поиск по IMDb в стиле OMDb, см. [эндпоинт OMDb](https://amodb.dev/ru/omdb-endpoint/). Об оценках после поиска проекта читайте на странице [рейтинги](https://amodb.dev/ru/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. ### Как получить Kinopoisk ID для проекта, который у меня уже есть? Вызовите эндпоинт 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/ru/movies/): API деталей фильма с теми же путями и JSON, что в TMDB v3. Получите фильм по ID, добавьте актеров, рейтинги и настроения через append_to_response, на 14 языках. - [API сериалов](https://amodb.dev/ru/tv-series/): API сериалов с теми же путями и JSON, что в TMDB v3. Сериал по id с сезонами, телесетями и следующей серией, а также возрастные рейтинги и сервисы просмотра. - [Рейтинги фильмов и сериалов](https://amodb.dev/ru/ratings/): API рейтингов фильмов: оценки IMDb, Kinopoisk, Metacritic, Rotten Tomatoes и TMDB для тайтла одним запросом, с null для источника, о котором нет данных. - [API деталей человека](https://amodb.dev/ru/people/): API деталей человека с теми же путями и JSON, что в TMDB v3. Получайте актера или члена съемочной группы по ID: биография, фильмография, внешние ID, популярные. - [Эндпоинт, совместимый с OMDb](https://amodb.dev/ru/omdb-endpoint/): Эндпоинт, совместимый с OMDb API, на api.amodb.dev/omdb/. Поиск по i или t, список через s, массив Ratings. Смените базовый URL, и клиент продолжит работать. - [Аутентификация](https://amodb.dev/ru/authentication/): Как передать ключ amodb: api_key в запросе, заголовок Authorization Bearer или apikey для вызовов OMDb. Формат ключа, хранение, ротация и ошибки 401. Обновлено: 2026-10-18. Source: https://amodb.dev/ru/find-by-external-id/