# Търсене по външен идентификатор

> 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` връщат Wikidata id на заглавие и факти за него: пари, съседи в поредица, страници в Wikipedia, награди и места. Всеки ключ присъства винаги. Неизвестен факт е `null` за единична стойност и `[]` за списък.

| Метод и път                      | Какво връща                                    | Параметри                          |
| -------------------------------- | ---------------------------------------------- | ---------------------------------- |
| `GET /movie/{movie_id}/wikidata` | Wikidata id и факти                            | `movie_id`, `language`             |
| `GET /tv/{tv_id}/wikidata`       | Wikidata id и факти                            | `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 има 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` също не отговарят с 404 за непознато id. Те отговарят със 200 и всяко id е `null`. Вижте [грешки](https://amodb.dev/bg/errors/) и [удостоверяване](https://amodb.dev/bg/authentication/).

## Практически бележки

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

Обновено: 2026-10-18. Source: https://amodb.dev/bg/find-by-external-id/