# Пошук па вонкавым ідэнтыфікатары

> 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": []
}
```

## Пошук назвы па вонкавым ідэнтыфікатары

`GET /3/find/{external_id}` бярэ id з іншай сістэмы і вяртае адпаведныя запісы. Шлях утрымлівае id, а параметр запыту `external_source` кажа, з якой сістэмы ён. amodb прымае дванаццаць крыніц, і сем з іх даюць запісы: `imdb_id`, `tvdb_id`, `wikidata_id`, `kinopoisk_id`, `facebook_id`, `twitter_id` і `instagram_id`.

У прыкладзе IMDb id `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
<?php
$url = 'https://api.amodb.dev/3/find/tt0137523?external_source=imdb_id';
$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");
}
$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 для назвы і факты пра яе: грошы, суседзі ў серыі, старонкі 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`                                                                | цэлы лік        | 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`                                                         | аб’ект          | Супастаўляе код мовы з назвай старонкі Wikipedia. Ключы гэта 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` таксама не адказваюць 404 на невядомы id. Яны адказваюць 200, і кожны id роўны `null`. Гл. [памылкі](https://amodb.dev/be/errors/) і [аўтэнтыфікацыя](https://amodb.dev/be/authentication/).

## Практычныя заўвагі

- Захавайце id TMDB пры першым вызначэнні вонкавага id. Наступныя выклікі прапускаюць `find` і ідуць наўпрост на шлях дэталяў, што эканоміць адзін запыт на назву.
- Заўсёды правярайце, што ў патрэбным масіве ёсць элемент. `find` можа вярнуць некалькі масіваў адразу для аднаго id.
- Дэталі і вонкавыя id кэшуюцца на edge на 6 гадзін. Паўторны пошук у гэты час вяртае захаваны адказ.
- `wikidata_id` працуе ў абодва бакі: перадайце яго ў `find`, каб атрымаць назву, або прачытайце з `external_ids`, каб спаслацца вонкі.
- Каб перанесці пошукі IMDb у стылі OMDb, гл. [эндпоінт OMDb](https://amodb.dev/be/omdb-endpoint/). Ацэнкі пасля вызначэння назвы гл. на старонцы [рэйтынгі](https://amodb.dev/be/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/be/movies/): API дэталяў фільма з тымі ж шляхамі і JSON, што ў TMDB v3. Адзін фільм па id, а акцёры, рэйтынгі і настрой праз append_to_response, на 14 мовах.
- [API серыялаў](https://amodb.dev/be/tv-series/): API серыялаў з тымі ж шляхамі і JSON, што ў TMDB v3. Серыял па id з сезонамі, тэлеканаламі і наступным эпізодам, плюс узроставыя рэйтынгі і сэрвісы прагляду.
- [Рэйтынгі фільмаў і серыялаў](https://amodb.dev/be/ratings/): API рэйтынгаў фільмаў вяртае ацэнкі IMDb, Kinopoisk, Metacritic, Rotten Tomatoes і TMDB для назвы адным выклікам, з null для крыніцы, якая невядомая.
- [API дэталяў персоны](https://amodb.dev/be/people/): API дэталяў персоны з тымі ж шляхамі і JSON, што ў TMDB v3. Акцёр ці член групы па id з біяграфіяй, фільмаграфіяй, вонкавымі id і спісам папулярных.
- [Эндпоінт, сумяшчальны з OMDb](https://amodb.dev/be/omdb-endpoint/): Эндпоінт, сумяшчальны з OMDb API, па адрасе api.amodb.dev/omdb/. Пошук па i або t, спіс праз s, масіў Ratings. Змяніце базавы URL, і кліент працуе далей.
- [Аўтэнтыфікацыя](https://amodb.dev/be/authentication/): Як перадаваць ключ amodb: api_key у запыце, загаловак Authorization Bearer або apikey для выклікаў OMDb. Фармат ключа, захоўванне, замена і памылкі 401.

Абноўлена: 2026-10-18. Source: https://amodb.dev/be/find-by-external-id/