# Buscar por id externo > GET /3/find/{external_id} convierte un id de IMDb, TVDB, Wikidata, Kinopoisk, Facebook, Twitter o Instagram en resultados al estilo TMDB, y los endpoints external_ids hacen el camino inverso. Un endpoint de Wikidata añade presupuesto, taquilla, premios y títulos relacionados de una película o serie. Todo usa tu clave 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" ``` Respuesta: ```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": [] } ``` ## Buscar un título por id externo `GET /3/find/{external_id}` toma un id de otro sistema y devuelve los registros que coinciden. La ruta contiene el id, y el parámetro de consulta `external_source` indica de qué sistema viene. amodb acepta doce fuentes y siete de ellas se resuelven en registros: `imdb_id`, `tvdb_id`, `wikidata_id`, `kinopoisk_id`, `facebook_id`, `twitter_id` e `instagram_id`. El ejemplo convierte el id de IMDb `tt0137523` en un id de 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 | En | Obligatorio | Descripción | | ----------------- | -------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `external_id` | ruta | sí | El id en el otro sistema, por ejemplo `tt0137523`. | | `external_source` | consulta | sí | Uno de `imdb_id`, `tvdb_id`, `wikidata_id`, `kinopoisk_id`, `facebook_id`, `twitter_id`, `instagram_id`. Se aceptan cinco más que no devuelven nada: `freebase_mid`, `freebase_id`, `tvrage_id`, `tiktok_id`, `youtube_id`. | | `language` | consulta | no | Uno de 14 idiomas como `en` o `ru-RU`. Otros valores recurren a `en`. | | `api_key` | consulta | uno de los dos | Tu clave. Usa esta o el encabezado `Authorization: Bearer`. | Un `external_source` ausente, o uno que no está en la lista, responde 400 con `status_code` 22. El valor debe ir en minúsculas. ### Campos de la respuesta | Campo | Tipo | Notas | | -------------------- | ----- | ------------------------------------------------------------------------------------------------------------------- | | `movie_results` | array | Registros de películas con los mismos campos que un resultado de búsqueda, más `media_type` fijado en `movie`. | | `person_results` | array | Personas que coinciden con el id. Cada una tiene `known_for` como un array vacío y `media_type` fijado en `person`. | | `tv_results` | array | Registros de series de TV con `media_type` fijado en `tv`. | | `tv_episode_results` | array | Siempre vacío. | | `tv_season_results` | array | Siempre vacío. | ### Ejemplo de respuesta ```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": [] } ``` La sinopsis está cortada. ### Qué fuente encuentra qué | `external_source` | Aspecto del id | Ejemplo | Array de resultados habitual | | ------------------------------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------ | | `imdb_id` | `tt` más dígitos para títulos, `nm` más dígitos para personas | `tt0137523`, `nm0000093` (Brad Pitt) | `movie_results`, `tv_results` o `person_results` | | `tvdb_id` | Número | `81189` (Breaking Bad) | `tv_results` | | `wikidata_id` | `Q` más dígitos | `Q190050` (Fight Club), `Q1079` (Breaking Bad), `Q35332` (Brad Pitt) | `movie_results`, `tv_results` o `person_results` | | `kinopoisk_id` | Número | `361` (Fight Club), `404900` (Breaking Bad) | `movie_results` o `tv_results` | | `facebook_id`, `twitter_id`, `instagram_id` | Nombre de cuenta | `FightClub` | Depende de la cuenta | Un mismo nombre de cuenta puede coincidir con más de un título. Por ejemplo, `instagram_id=breakingbad` devuelve la serie y la película El Camino, así que lee todos los arrays. ```bash curl -sf "https://api.amodb.dev/3/find/361?external_source=kinopoisk_id" \ -H "Authorization: Bearer $AMODB_KEY" ``` ## Ids externos de un título conocido La dirección inversa es un conjunto de endpoints `external_ids`. Devuelven los ids que otros sistemas usan para un registro que ya tienes. | Método y ruta | Devuelve | 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` | Los mismos más `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` | Un id que un título no tiene llega como `null`. `kinopoisk_id` es un texto y solo está presente en una película o serie cuando amodb lo conoce. Una respuesta 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" } ``` Una respuesta 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" } ``` Los endpoints `external_ids` de temporada y de episodio existen, pero hoy todos sus ids son `null`, así que puedes saltarlos. ## Datos de Wikidata `GET /3/movie/{movie_id}/wikidata` y `GET /3/tv/{tv_id}/wikidata` devuelven el id de Wikidata de un título y datos sobre él: dinero, títulos vecinos en una saga, páginas de Wikipedia, premios y lugares. Todas las claves están siempre presentes. Un dato desconocido es `null` para un valor único y `[]` para una lista. | Método y ruta | Devuelve | Parámetros | | -------------------------------- | -------------------------------------------- | ---------------------------------- | | `GET /movie/{movie_id}/wikidata` | Id de Wikidata y datos | `movie_id`, `language` | | `GET /tv/{tv_id}/wikidata` | Id de Wikidata y datos | `tv_id`, `language` | | `append_to_response=wikidata` | El mismo bloque bajo `wikidata`, con su `id` | Se añade a una llamada de detalles | Esta es la respuesta para Fight Club (película 550), recortada a un tamaño legible: ```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": [] } ``` El objeto `sitelinks` tiene 14 entradas y `awards` tiene 5. Ambos están recortados aquí. | Campo | Tipo | Notas | | ------------------------------------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `id` | entero | Id de TMDB del título. Se mantiene cuando usas `append_to_response`. | | `wikidata_id` | texto o null | Elemento de Wikidata como `Q190050`. | | `budget` | objeto o null | `value` es un entero redondeado y `currency` es un código ISO o `null`. | | `box_office` | objeto o null | Igual que `budget`, más `worldwide` con el valor `true` o `false`. | | `follows`, `followed_by` | objeto o null | El título anterior y el siguiente en una saga de películas, como un enlace. | | `sitelinks` | objeto | Asocia un código de idioma con el título de la página de Wikipedia. Las claves son los 14 idiomas servidos. `{}` cuando no hay ninguno. | | `awards`, `nominations` | array | Enlaces con un `year` opcional. | | `based_on` | array | Obras originales con `wikidata_id`, `label` y un objeto `author` o `null`. | | `filming_locations`, `narrative_locations`, `original_broadcasters` | array | Enlaces. Breaking Bad tiene a AMC en `original_broadcasters`. | Un enlace tiene `wikidata_id`, `label` y, cuando el elemento es un título del catálogo, `tmdb_id` y `media_type`. Para The Matrix Reloaded (película 604), los títulos vecinos son enlaces a las películas 603 y 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` llega en el `language` de la solicitud y recurre al inglés. Con `language=ru` el autor de arriba aparece como `Чак Паланик`. ## Errores Los errores usan el cuerpo de TMDB, por ejemplo `{"success": false, "status_code": 7, "status_message": "Invalid API key: You must be granted a valid key."}`. | HTTP | status_code | Cuándo | | ---- | ----------- | --------------------------------------------------------------------------- | | 400 | 22 | `external_source` falta, no está en minúsculas o no está en la lista. | | 401 | 7 | La clave falta o es incorrecta. | | 402 | 36 | El periodo del plan ha terminado. | | 404 | 34 | El id del título en una ruta `wikidata` no existe. | | 429 | 25 | Superaste tus solicitudes por minuto. Espera los segundos de `Retry-After`. | Un id externo desconocido en `find` no es un error: espera los cinco arrays vacíos. Los endpoints `external_ids` tampoco responden 404 ante un id desconocido. Responden 200 con todos los ids en `null`. Consulta [errores](https://amodb.dev/es/errors/) y [autenticación](https://amodb.dev/es/authentication/). ## Notas prácticas - Guarda el id de TMDB la primera vez que resuelvas un id externo. Así las llamadas posteriores se saltan `find` y van directo a la ruta de detalles, lo que ahorra una solicitud por título. - Comprueba siempre que el array que quieres tenga un elemento. `find` puede devolver varios arrays a la vez para un mismo id. - Los detalles y los ids externos se guardan en la caché perimetral 6 horas. Una consulta repetida dentro de ese tiempo devuelve la respuesta guardada. - `wikidata_id` funciona en ambos sentidos: pásalo a `find` para obtener un título, o léelo de `external_ids` para enlazar hacia fuera. - Para traer las consultas de IMDb al estilo OMDb, consulta el [endpoint de OMDb](https://amodb.dev/es/omdb-endpoint/). Para las puntuaciones después de resolver un título, consulta [puntuaciones](https://amodb.dev/es/ratings/). ## Preguntas y respuestas ### ¿Qué fuentes externas acepta find? Para external_source se aceptan doce valores. Siete de ellos se resuelven: imdb_id, tvdb_id, wikidata_id, kinopoisk_id, facebook_id, twitter_id e instagram_id. Los otros cinco devuelven arrays vacíos. El valor es obligatorio, va en minúsculas y debe ser exacto, por ejemplo external_source=imdb_id. ### ¿Por qué find devuelve cinco arrays? Un id puede apuntar a una película, una persona, una serie, un episodio o una temporada, así que la respuesta tiene un array para cada tipo. En amodb solo movie_results, person_results y tv_results contienen elementos. tv_episode_results y tv_season_results siempre están vacíos. ### ¿Qué pasa cuando el id es desconocido? Recibes el estado 200 con los cinco arrays vacíos, como en TMDB. Comprueba que al menos un array tenga un elemento antes de leerlo. Un external_source ausente o desconocido es distinto: responde 400 con status_code 22. ### ¿Cómo obtengo el id de Kinopoisk de un título que ya tengo? Llama al endpoint external_ids de la película o la serie. Devuelve kinopoisk_id como texto, por ejemplo 361 para Fight Club, o null cuando amodb no lo conoce. Pasa ese texto a find con external_source=kinopoisk_id para volver. ### ¿Puedo añadir wikidata a una llamada de detalles? Sí. Añade append_to_response=wikidata a una solicitud de detalles de película o de TV y el bloque de Wikidata llega bajo la clave wikidata, en la misma solicitud y sin ninguna llamada extra. ## Páginas relacionadas - [API de detalles de película](https://amodb.dev/es/movies/): API de detalles de película con rutas y JSON de TMDB v3. Obtén una película por id y añade créditos, puntuaciones y moods con append_to_response, en 14 idiomas. - [API de series de TV](https://amodb.dev/es/tv-series/): API de series de TV con las mismas rutas y JSON que TMDB v3. Obtén una serie con temporadas, cadenas y próximo episodio, más clasificaciones y plataformas. - [Puntuaciones de películas y series](https://amodb.dev/es/ratings/): API de puntuaciones de películas: IMDb, Kinopoisk, Metacritic, Rotten Tomatoes y TMDB de un título en una sola llamada, con null si falta una fuente. - [API de detalles de persona](https://amodb.dev/es/people/): API de detalles de persona con rutas y JSON de TMDB v3. Obtén un actor o miembro del equipo por id, con biografía, filmografía, ids externos y populares. - [Endpoint compatible con OMDb](https://amodb.dev/es/omdb-endpoint/): Endpoint compatible con la API de OMDb en api.amodb.dev/omdb/. Busca con i o t, explora con s, lee el array Ratings y conserva tu cliente cambiando la URL base. - [Autenticación](https://amodb.dev/es/authentication/): Cómo enviar tu clave de amodb: api_key en la consulta, un encabezado Bearer o apikey en llamadas OMDb. Formato, almacenamiento, rotación y errores 401. Actualizado: 2026-10-18. Source: https://amodb.dev/es/find-by-external-id/