# Hledání podle externího ID

> GET /3/find/{external_id} převádí ID z IMDb, TVDB, Wikidata, Kinopoisk, Facebooku, Twitteru nebo Instagramu na výsledky ve stylu TMDB a endpointy external_ids fungují opačně. Endpoint Wikidata přidává rozpočet, tržby, ocenění a propojené tituly filmu nebo seriálu. Vše používá váš běžný klíč API.

## Endpoint

`GET /3/find/{external_id}`

```bash
curl "https://api.amodb.dev/3/find/tt0137523?external_source=imdb_id" \
  -H "Authorization: Bearer $AMODB_KEY"
```

Odpověď:

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

## Najděte titul podle externího ID

`GET /3/find/{external_id}` převezme ID z jiného systému a vrátí odpovídající záznamy. Cesta obsahuje ID a parametr dotazu `external_source` říká, z jakého systému pochází. amodb přijímá dvanáct zdrojů a sedm z nich se převede na záznamy: `imdb_id`, `tvdb_id`, `wikidata_id`, `kinopoisk_id`, `facebook_id`, `twitter_id` a `instagram_id`.

Ukázka převede ID z IMDb `tt0137523` na ID z 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)
}
```

### Parametry

| Parametr          | Kde   | Povinný       | Popis                                                                                                                                                                                                                         |
| ----------------- | ----- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `external_id`     | path  | ano           | ID v jiném systému, například `tt0137523`.                                                                                                                                                                                    |
| `external_source` | query | ano           | Jedna z hodnot `imdb_id`, `tvdb_id`, `wikidata_id`, `kinopoisk_id`, `facebook_id`, `twitter_id`, `instagram_id`. Dalších pět se přijímá a nic nevrací: `freebase_mid`, `freebase_id`, `tvrage_id`, `tiktok_id`, `youtube_id`. |
| `language`        | query | ne            | Jeden ze 14 jazyků, například `en` nebo `ru-RU`. Jiné hodnoty se vrátí k `en`.                                                                                                                                                |
| `api_key`         | query | jeden ze dvou | Váš klíč. Použijte jej, nebo hlavičku `Authorization: Bearer`.                                                                                                                                                                |

Chybějící `external_source` nebo hodnota, která není v seznamu, odpoví 400 se `status_code` 22. Hodnota musí být malými písmeny.

### Pole odpovědi

| Pole                 | Typ   | Poznámky                                                                                            |
| -------------------- | ----- | --------------------------------------------------------------------------------------------------- |
| `movie_results`      | array | Záznamy filmů se stejnými poli jako výsledek vyhledávání plus `media_type` nastavené na `movie`.    |
| `person_results`     | array | Osoby odpovídající ID. Každá má `known_for` jako prázdné pole a `media_type` nastavené na `person`. |
| `tv_results`         | array | Záznamy seriálů s `media_type` nastaveným na `tv`.                                                  |
| `tv_episode_results` | array | Vždy prázdné.                                                                                       |
| `tv_season_results`  | array | Vždy prázdné.                                                                                       |

### Příklad odpovědi

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

Popis je zkrácen.

### Který zdroj co najde

| `external_source`                           | ID vypadá jako                                       | Příklad                                                              | Obvyklé pole s výsledkem                            |
| ------------------------------------------- | ---------------------------------------------------- | -------------------------------------------------------------------- | --------------------------------------------------- |
| `imdb_id`                                   | `tt` plus číslice u titulů, `nm` plus číslice u osob | `tt0137523`, `nm0000093` (Brad Pitt)                                 | `movie_results`, `tv_results` nebo `person_results` |
| `tvdb_id`                                   | Číslo                                                | `81189` (Breaking Bad)                                               | `tv_results`                                        |
| `wikidata_id`                               | `Q` plus číslice                                     | `Q190050` (Fight Club), `Q1079` (Breaking Bad), `Q35332` (Brad Pitt) | `movie_results`, `tv_results` nebo `person_results` |
| `kinopoisk_id`                              | Číslo                                                | `361` (Fight Club), `404900` (Breaking Bad)                          | `movie_results` nebo `tv_results`                   |
| `facebook_id`, `twitter_id`, `instagram_id` | Název účtu                                           | `FightClub`                                                          | Záleží na účtu                                      |

Jeden název účtu může odpovídat více titulům. Například `instagram_id=breakingbad` vrací seriál i film El Camino, čtěte proto všechna pole.

```bash
curl -sf "https://api.amodb.dev/3/find/361?external_source=kinopoisk_id" \
  -H "Authorization: Bearer $AMODB_KEY"
```

## Externí ID známého titulu

Opačný směr zajišťuje sada endpointů `external_ids`. Vracejí ID, která jiné systémy používají pro záznam, který už máte.

| Metoda a cesta                         | Vrací                                                                                            | Parametry   |
| -------------------------------------- | ------------------------------------------------------------------------------------------------ | ----------- |
| `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`         | Totéž plus `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, které titul nemá, přijde jako `null`. `kinopoisk_id` je řetězec a u filmu nebo seriálu je přítomno jen tehdy, když ho amodb zná. Skutečná odpověď pro `/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"
}
```

Skutečná odpověď pro `/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"
}
```

Endpointy `external_ids` pro sezóny a epizody existují, ale každé ID v nich je dnes `null`, takže je přeskočte.

## Fakta z Wikidata

`GET /3/movie/{movie_id}/wikidata` a `GET /3/tv/{tv_id}/wikidata` vracejí ID Wikidata titulu a fakta o něm: peníze, sousedy v sérii, stránky Wikipedie, ocenění a místa. Každý klíč je vždy přítomen. Neznámý fakt je `null` u jedné hodnoty a `[]` u seznamu.

| Metoda a cesta                   | Vrací                                   | Parametry                   |
| -------------------------------- | --------------------------------------- | --------------------------- |
| `GET /movie/{movie_id}/wikidata` | ID Wikidata a fakta                     | `movie_id`, `language`      |
| `GET /tv/{tv_id}/wikidata`       | ID Wikidata a fakta                     | `tv_id`, `language`         |
| `append_to_response=wikidata`    | Stejný blok pod `wikidata`, s jeho `id` | Přidává se k volání detailů |

Toto je odpověď pro Fight Club (film 550), zkrácená na čitelnou velikost:

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

Objekt `sitelinks` má 14 položek a `awards` má 5. Obojí je zde zkráceno.

| Pole                                                                | Typ              | Poznámky                                                                                                   |
| ------------------------------------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------- |
| `id`                                                                | integer          | ID titulu z TMDB. Zůstává při použití `append_to_response`.                                                |
| `wikidata_id`                                                       | string nebo null | Položka Wikidata, například `Q190050`.                                                                     |
| `budget`                                                            | object nebo null | `value` je zaokrouhlené celé číslo a `currency` je kód ISO nebo `null`.                                    |
| `box_office`                                                        | object nebo null | Stejné jako `budget` plus `worldwide` nastavené na `true` nebo `false`.                                    |
| `follows`, `followed_by`                                            | object nebo null | Předchozí a následující titul v sérii filmů jako odkaz.                                                    |
| `sitelinks`                                                         | object           | Mapuje kód jazyka na název stránky Wikipedie. Klíče jsou 14 podporovaných jazyků. `{}`, když žádné nejsou. |
| `awards`, `nominations`                                             | array            | Odkazy s volitelným `year`.                                                                                |
| `based_on`                                                          | array            | Zdrojová díla s `wikidata_id`, `label` a objektem `author` nebo `null`.                                    |
| `filming_locations`, `narrative_locations`, `original_broadcasters` | array            | Odkazy. Breaking Bad má v `original_broadcasters` AMC.                                                     |

Odkaz má `wikidata_id`, `label` a, když je položka titulem v katalogu, `tmdb_id` a `media_type`. U The Matrix Reloaded (film 604) jsou sousedé odkazy na filmy 603 a 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"
  }
}
```

Každý `label` přichází v `language` požadavku a vrací se k angličtině. S `language=ru` se autor výše čte `Чак Паланик`.

## Chyby

Chyby používají tělo TMDB, například `{"success": false, "status_code": 7, "status_message": "Invalid API key: You must be granted a valid key."}`.

| HTTP | status_code | Kdy                                                                                   |
| ---- | ----------- | ------------------------------------------------------------------------------------- |
| 400  | 22          | `external_source` chybí, není malými písmeny nebo není v seznamu.                     |
| 401  | 7           | Klíč chybí nebo je nesprávný.                                                         |
| 402  | 36          | Platnost tarifu skončila.                                                             |
| 404  | 34          | ID titulu v cestě `wikidata` neexistuje.                                              |
| 429  | 25          | Překročen počet požadavků za minutu. Počkejte tolik sekund, kolik říká `Retry-After`. |

Neznámé externí ID u `find` není chyba: počítejte s tím, že všech pět polí bude prázdných. Endpointy `external_ids` také neodpovídají 404 pro neznámé ID. Odpovídají 200 se všemi ID `null`. Viz [chyby](https://amodb.dev/cs/errors/) a [autentizace](https://amodb.dev/cs/authentication/).

## Praktické poznámky

- ID z TMDB uložte při prvním převodu externího ID. Další volání pak přeskočí `find` a půjdou rovnou na cestu detailů, což ušetří jeden požadavek na titul.
- Vždy ověřte, že pole, které chcete, má položku. `find` může pro jedno ID vrátit několik polí najednou.
- Detaily a externí ID se na edge cachují 6 hodin. Opakované vyhledání v tomto čase vrátí uloženou odpověď.
- `wikidata_id` funguje oběma směry: předejte jej do `find` a získáte titul, nebo jej přečtěte z `external_ids` a odkažte ven.
- Vyhledávání IMDb ve stylu OMDb převedete podle stránky [endpoint OMDb](https://amodb.dev/cs/omdb-endpoint/). Skóre po převodu titulu najdete na stránce [hodnocení](https://amodb.dev/cs/ratings/).

## Otázky a odpovědi

### Které externí zdroje find přijímá?

Pro external_source se přijímá dvanáct hodnot. Sedm z nich se převede na záznam: imdb_id, tvdb_id, wikidata_id, kinopoisk_id, facebook_id, twitter_id a instagram_id. Ostatních pět vrací prázdná pole. Hodnota je povinná, malými písmeny a přesná, například external_source=imdb_id.

### Proč find vrací pět polí?

ID může ukazovat na film, osobu, seriál, epizodu nebo sezónu, takže odpověď má jedno pole pro každý druh. V amodb obsahují položky jen movie_results, person_results a tv_results. tv_episode_results a tv_season_results jsou vždy prázdná.

### Co se stane, když je ID neznámé?

Dostanete status 200 se všemi pěti poli prázdnými, stejně jako u TMDB. Než pole přečtete, ověřte, že má alespoň jednu položku. Jinak se chová chybějící nebo neznámé external_source: odpoví 400 se status_code 22.

### Jak získám ID z Kinopoisku pro titul, který už mám?

Zavolejte endpoint external_ids filmu nebo seriálu. Vrací kinopoisk_id jako řetězec, například 361 pro Fight Club, nebo null, když ho amodb nezná. Tento řetězec předejte do find s external_source=kinopoisk_id a vrátíte se zpět.

### Mohu přidat wikidata k volání detailů?

Ano. Přidejte append_to_response=wikidata k požadavku na detail filmu nebo seriálu a blok Wikidata přijde pod klíčem wikidata, ve stejném požadavku a bez dalšího volání.

## Související stránky

- [API detailu filmu](https://amodb.dev/cs/movies/): API detailu filmu se stejnými cestami a JSON jako TMDB v3. Načtěte film podle ID, přidejte obsazení, hodnocení a nálady přes append_to_response, 14 jazyků.
- [API detailu seriálu](https://amodb.dev/cs/tv-series/): API detailu seriálu se stejnými cestami a JSON jako TMDB v3. Seriál podle ID se sezónami, sítěmi, věkovým hodnocením a poskytovateli streamování.
- [Hodnocení filmů a seriálů](https://amodb.dev/cs/ratings/): API hodnocení filmů, které vrací skóre z IMDb, Kinopoisk, Metacritic, Rotten Tomatoes a TMDB pro titul jedním voláním, s null u každého neznámého zdroje.
- [API detailu osoby](https://amodb.dev/cs/people/): API detailu osoby se stejnými cestami a JSON jako TMDB v3. Herec či člen štábu podle ID s biografií, filmografií, externími ID a seznamem populárních osob.
- [Endpoint kompatibilní s OMDb](https://amodb.dev/cs/omdb-endpoint/): Endpoint kompatibilní s OMDb na api.amodb.dev/omdb/: dotazy i a t, hledání přes s, pole Ratings. Klient funguje dál po změně základní URL a klíče.
- [Autentizace](https://amodb.dev/cs/authentication/): Jak poslat klíč amodb: api_key v dotazu, hlavička Authorization Bearer nebo apikey pro volání OMDb. Formát klíče, uložení, rotace a chyby 401.

Aktualizováno: 2026-10-18. Source: https://amodb.dev/cs/find-by-external-id/