# Buscar por ID externo > GET /3/find/{external_id} converte um id do IMDb, TVDB, Wikidata, Kinopoisk, Facebook, Twitter ou Instagram em resultados no formato do TMDB, e os endpoints external_ids fazem o caminho inverso. Um endpoint do Wikidata acrescenta orçamento, bilheteria, prêmios e títulos ligados de um filme ou série. Tudo usa a sua chave normal. ## Endpoint `GET /3/find/{external_id}` ```bash curl "https://api.amodb.dev/3/find/tt0137523?external_source=imdb_id" \ -H "Authorization: Bearer $AMODB_KEY" ``` Resposta: ```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": [] } ``` ## Encontrar um título por ID externo `GET /3/find/{external_id}` recebe um id de outro sistema e retorna os registros correspondentes. O caminho contém o id, e o parâmetro de consulta `external_source` informa de qual sistema ele vem. O amodb aceita doze fontes, e sete delas resolvem para registros: `imdb_id`, `tvdb_id`, `wikidata_id`, `kinopoisk_id`, `facebook_id`, `twitter_id` e `instagram_id`. O exemplo converte o id do IMDb `tt0137523` em um id do 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) } ``` ### Parâmetros | Parâmetro | Em | Obrigatório | Descrição | | ----------------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `external_id` | caminho | sim | O id no outro sistema, por exemplo `tt0137523`. | | `external_source` | consulta | sim | Um entre `imdb_id`, `tvdb_id`, `wikidata_id`, `kinopoisk_id`, `facebook_id`, `twitter_id`, `instagram_id`. Outros cinco são aceitos e não retornam nada: `freebase_mid`, `freebase_id`, `tvrage_id`, `tiktok_id`, `youtube_id`. | | `language` | consulta | não | Um de 14 idiomas, como `en` ou `ru-RU`. Outros valores voltam para `en`. | | `api_key` | consulta | um dos dois | Sua chave. Use este parâmetro ou o header `Authorization: Bearer`. | Um `external_source` ausente, ou que não consta na lista, responde 400 com `status_code` 22. O valor precisa estar em minúsculas. ### Campos da resposta | Campo | Tipo | Observações | | -------------------- | ----- | ---------------------------------------------------------------------------------------------------------------- | | `movie_results` | array | Registros de filmes com os mesmos campos de um resultado de busca, mais `media_type` definido como `movie`. | | `person_results` | array | Pessoas encontradas pelo id. Cada uma tem `known_for` como um array vazio e `media_type` definido como `person`. | | `tv_results` | array | Registros de séries de TV com `media_type` definido como `tv`. | | `tv_episode_results` | array | Sempre vazio. | | `tv_season_results` | array | Sempre vazio. | ### Exemplo de resposta ```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": [] } ``` A sinopse foi cortada. ### Qual fonte encontra o quê | `external_source` | Aparência do id | Exemplo | Array de resultado usual | | ------------------------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------- | | `imdb_id` | `tt` mais dígitos para títulos, `nm` mais dígitos para pessoas | `tt0137523`, `nm0000093` (Brad Pitt) | `movie_results`, `tv_results` ou `person_results` | | `tvdb_id` | Número | `81189` (Breaking Bad) | `tv_results` | | `wikidata_id` | `Q` mais dígitos | `Q190050` (Fight Club), `Q1079` (Breaking Bad), `Q35332` (Brad Pitt) | `movie_results`, `tv_results` ou `person_results` | | `kinopoisk_id` | Número | `361` (Fight Club), `404900` (Breaking Bad) | `movie_results` ou `tv_results` | | `facebook_id`, `twitter_id`, `instagram_id` | Nome da conta | `FightClub` | Depende da conta | Um nome de conta pode corresponder a mais de um título. Por exemplo, `instagram_id=breakingbad` retorna a série e o filme El Camino, então leia todos os arrays. ```bash curl -sf "https://api.amodb.dev/3/find/361?external_source=kinopoisk_id" \ -H "Authorization: Bearer $AMODB_KEY" ``` ## IDs externos de um título conhecido O sentido inverso é um conjunto de endpoints `external_ids`. Eles retornam os ids que outros sistemas usam para um registro que você já tem. | Método e caminho | Retorna | Parâmetros | | -------------------------------------- | ------------------------------------------------------------------------------------------------ | ----------- | | `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` | Os mesmos, mais `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` | Um id que o título não tem volta como `null`. `kinopoisk_id` é uma string e só aparece em um filme ou série quando o amodb o conhece. Uma resposta real para `/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" } ``` Uma resposta real para `/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" } ``` Os endpoints `external_ids` de temporada e de episódio existem, mas todos os ids neles são `null` hoje, então ignore-os. ## Dados do Wikidata `GET /3/movie/{movie_id}/wikidata` e `GET /3/tv/{tv_id}/wikidata` retornam o id do Wikidata de um título e dados sobre ele: valores em dinheiro, títulos vizinhos em uma série, páginas da Wikipedia, prêmios e locais. Todas as chaves estão sempre presentes. Um dado que não é conhecido vale `null` para um valor único e `[]` para uma lista. | Método e caminho | Retorna | Parâmetros | | -------------------------------- | -------------------------------------------- | ------------------------------------ | | `GET /movie/{movie_id}/wikidata` | Id do Wikidata e dados | `movie_id`, `language` | | `GET /tv/{tv_id}/wikidata` | Id do Wikidata e dados | `tv_id`, `language` | | `append_to_response=wikidata` | O mesmo bloco sob `wikidata`, com o seu `id` | Adicionado a uma chamada de detalhes | Esta é a resposta para Fight Club (filme 550), cortada até um tamanho legível: ```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": [] } ``` O objeto `sitelinks` tem 14 entradas e `awards` tem 5. Os dois foram cortados aqui. | Campo | Tipo | Observações | | ------------------------------------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `id` | inteiro | Id do título no TMDB. Ele permanece quando você usa `append_to_response`. | | `wikidata_id` | string ou null | Item do Wikidata, como `Q190050`. | | `budget` | objeto ou null | `value` é um inteiro arredondado e `currency` é um código ISO ou `null`. | | `box_office` | objeto ou null | Igual a `budget`, mais `worldwide` definido como `true` ou `false`. | | `follows`, `followed_by` | objeto ou null | O título anterior e o seguinte em uma série de filmes, como um link. | | `sitelinks` | objeto | Mapeia um código de idioma para o título da página da Wikipedia. As chaves são os 14 idiomas atendidos. `{}` quando não há nenhum. | | `awards`, `nominations` | array | Links com um `year` opcional. | | `based_on` | array | Obras de origem com `wikidata_id`, `label` e um objeto `author` ou `null`. | | `filming_locations`, `narrative_locations`, `original_broadcasters` | array | Links. Breaking Bad tem a AMC em `original_broadcasters`. | Um link tem `wikidata_id`, `label` e, quando o item é um título do catálogo, `tmdb_id` e `media_type`. Para The Matrix Reloaded (filme 604), os vizinhos são links para os filmes 603 e 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" } } ``` Cada `label` vem no `language` da requisição e volta para o inglês quando não há tradução. Com `language=ru`, o autor acima aparece como `Чак Паланик`. ## Erros Os erros usam o corpo do TMDB, por exemplo `{"success": false, "status_code": 7, "status_message": "Invalid API key: You must be granted a valid key."}`. | HTTP | status_code | Quando | | ---- | ----------- | --------------------------------------------------------------------------------------------- | | 400 | 22 | `external_source` está ausente, não está em minúsculas ou não consta na lista. | | 401 | 7 | A chave está ausente ou incorreta. | | 402 | 36 | O período do plano terminou. | | 404 | 34 | O id do título em um caminho `wikidata` não existe. | | 429 | 25 | Acima do seu limite de requisições por minuto. Espere os segundos indicados em `Retry-After`. | Um id externo desconhecido no `find` não é um erro: espere os cinco arrays vazios. Os endpoints `external_ids` também não respondem 404 para um id desconhecido. Eles respondem 200 com todos os ids `null`. Veja [erros](https://amodb.dev/pt/errors/) e [autenticação](https://amodb.dev/pt/authentication/). ## Notas práticas - Salve o id do TMDB na primeira vez que resolver um id externo. As chamadas seguintes pulam o `find` e vão direto ao caminho de detalhes, o que economiza uma requisição por título. - Sempre teste se o array que você quer tem um item. O `find` pode retornar vários arrays de uma vez para um mesmo id. - Os detalhes e os ids externos ficam em cache na borda por 6 horas. Uma consulta repetida nesse intervalo retorna a resposta guardada. - `wikidata_id` funciona nos dois sentidos: passe-o ao `find` para obter um título, ou leia-o em `external_ids` para criar um link externo. - Para trazer as consultas ao IMDb no estilo OMDb, veja o [endpoint OMDb](https://amodb.dev/pt/omdb-endpoint/). Para as notas depois de resolver um título, veja [avaliações](https://amodb.dev/pt/ratings/). ## Perguntas e respostas ### Quais fontes externas o find aceita? Doze valores são aceitos em external_source. Sete deles resolvem: imdb_id, tvdb_id, wikidata_id, kinopoisk_id, facebook_id, twitter_id e instagram_id. Os outros cinco retornam arrays vazios. O valor é obrigatório, em minúsculas e exato, por exemplo external_source=imdb_id. ### Por que o find retorna cinco arrays? Um id pode apontar para um filme, uma pessoa, uma série, um episódio ou uma temporada, então a resposta tem um array para cada tipo. No amodb, só movie_results, person_results e tv_results trazem itens. tv_episode_results e tv_season_results estão sempre vazios. ### O que acontece quando o id é desconhecido? Você recebe status 200 com os cinco arrays vazios, como no TMDB. Confira se pelo menos um array tem um item antes de lê-lo. Um external_source ausente ou desconhecido é diferente: responde 400 com status_code 22. ### Como obtenho o id do Kinopoisk de um título que eu já tenho? Chame o endpoint external_ids do filme ou da série. Ele retorna kinopoisk_id como string, como 361 para Fight Club, ou null quando o amodb não o conhece. Passe essa string ao find com external_source=kinopoisk_id para fazer o caminho de volta. ### Posso anexar wikidata a uma chamada de detalhes? Sim. Acrescente append_to_response=wikidata a uma requisição de detalhes de filme ou de TV e o bloco do Wikidata chega na chave wikidata, na mesma requisição e sem chamada extra. ## Páginas relacionadas - [API de detalhes de filmes](https://amodb.dev/pt/movies/): API de detalhes de filmes com caminhos e JSON do TMDB v3. Busque um filme por id e junte créditos, avaliações e moods com append_to_response, em 14 idiomas. - [API de séries de TV](https://amodb.dev/pt/tv-series/): API de séries de TV com os mesmos caminhos e JSON do TMDB v3. Busque uma série por id com temporadas, emissoras, próximo episódio e classificações. - [Avaliações de filmes e séries](https://amodb.dev/pt/ratings/): API de avaliações de filmes com as notas do IMDb, Kinopoisk, Metacritic, Rotten Tomatoes e TMDB em uma só chamada, com null se a fonte for desconhecida. - [API de detalhes de pessoas](https://amodb.dev/pt/people/): API de detalhes de pessoas com os caminhos e o JSON do TMDB v3. Busque um ator ou membro da equipe por id, com biografia, filmografia e ids externos. - [Endpoint compatível com OMDb](https://amodb.dev/pt/omdb-endpoint/): Endpoint compatível com OMDb API em api.amodb.dev/omdb/. Busque por i ou t, pesquise com s, leia o array Ratings e mantenha seu cliente trocando só a URL base. - [Autenticação](https://amodb.dev/pt/authentication/): Como enviar sua chave do amodb: api_key na consulta, um cabeçalho Authorization Bearer ou apikey nas chamadas OMDb. Formato, armazenamento, rotação e erros 401. Atualizado: 2026-10-18. Source: https://amodb.dev/pt/find-by-external-id/