# API de búsqueda > Los endpoints de búsqueda convierten una consulta de texto en ids. GET /3/search/movie encuentra películas, y las rutas hermanas encuentran series de TV, personas, colecciones, productoras y palabras clave, o todo a la vez con multi. El JSON coincide con TMDB v3, los resultados se paginan de 20 en 20 y la caché perimetral guarda una consulta 10 minutos. ## Endpoint `GET /3/search/movie` ```bash curl "https://api.amodb.dev/3/search/movie?query=inception&year=2010" \ -H "Authorization: Bearer $AMODB_KEY" ``` Respuesta: ```json { "page": 1, "results": [ { "adult": false, "backdrop_path": "/zSBVQIvx4UIHoFf1oDvixHyIQrz.jpg", "genre_ids": [ 28, 878, 80 ], "id": 27205, "original_language": "en", "original_title": "Inception", "overview": "Cobb, a skilled thief who commits corporate espionage by infiltrating the subconscious of his targets is offered a chance to regain his old life as payment for a task considered to be impossible: \"inception\", the implantation of another per...", "popularity": 60.9811, "poster_path": "/xlaY2zyzMfkhk0HSC5VUwzoZPU1.jpg", "release_date": "2010-07-15", "title": "Inception", "video": false, "vote_average": 8.373, "vote_count": 40459 }, { "adult": false, "backdrop_path": "/p8K8Z4yjaslJx5mTsIC5L6LJxQB.jpg", "genre_ids": [ 16, 28, 53 ], "id": 64956, "original_language": "en", "original_title": "Inception: The Cobol Job", "overview": "Cobb, Arthur and Nash are enlisted by Cobol Engineering.", "popularity": 1.9401, "poster_path": "/sNxqwtyHMNQwKWoFYDqcYTui5Ok.jpg", "release_date": "2010-12-07", "title": "Inception: The Cobol Job", "video": false, "vote_average": 7.2, "vote_count": 320 }, { "adult": false, "backdrop_path": null, "genre_ids": [ 10402 ], "id": 973484, "original_language": "en", "original_title": "Inception: Music from the Motion Picture", "overview": "The Special Features Blu-ray disc contains a lossless DTS-HD MA 5.1 surround mix of the Inception soundtrack.", "popularity": 0.4911, "poster_path": "/7uM4DyRVAcgagvhZoWrkrqMPbqV.jpg", "release_date": "2010-12-07", "title": "Inception: Music from the Motion Picture", "video": true, "vote_average": 7, "vote_count": 3 } ], "total_pages": 1, "total_results": 3 } ``` ## Buscar películas `GET /3/search/movie` recibe una consulta de texto y devuelve una lista paginada de películas que coinciden, con la mejor coincidencia primero. Úsalo para convertir lo que escribió un usuario en un id de película, y luego llama a los [detalles de película](https://amodb.dev/es/movies/) con ese id. El ejemplo busca Inception, restringido a 2010, e imprime el id, el título y la fecha de estreno. ```bash curl -sSf --get "https://api.amodb.dev/3/search/movie" \ --data-urlencode "query=inception" \ --data-urlencode "year=2010" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js const params = new URLSearchParams({ query: 'inception', year: '2010', language: 'en-US' }); const res = await fetch(`https://api.amodb.dev/3/search/movie?${params}`, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` }, }); if (!res.ok) throw new Error(`amodb returned ${res.status}`); const { results, total_results } = await res.json(); console.log(`${total_results} matches`); for (const m of results.slice(0, 5)) console.log(m.id, m.title, m.release_date); ``` ```python import os import requests r = requests.get( "https://api.amodb.dev/3/search/movie", params={"query": "inception", "year": 2010, "language": "en-US"}, headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"}, timeout=10, ) r.raise_for_status() data = r.json() print(data["total_results"], "matches") for m in data["results"][:5]: print(m["id"], m["title"], m["release_date"]) ``` ```php 'inception', 'year' => 2010, 'language' => 'en-US', ]); $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"); } $data = json_decode($body, true); foreach (array_slice($data['results'], 0, 5) as $m) { echo $m['id'], ' ', $m['title'], ' ', $m['release_date'], PHP_EOL; } ``` ```go package main import ( "encoding/json" "fmt" "net/http" "net/url" "os" "time" ) type SearchPage struct { TotalResults int `json:"total_results"` Results []struct { ID int `json:"id"` Title string `json:"title"` ReleaseDate string `json:"release_date"` } `json:"results"` } func main() { q := url.Values{"query": {"inception"}, "year": {"2010"}, "language": {"en-US"}} req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/search/movie?"+q.Encode(), 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 p SearchPage if err := json.NewDecoder(res.Body).Decode(&p); err != nil { panic(err) } fmt.Println(p.TotalResults, "matches") for _, m := range p.Results { fmt.Println(m.ID, m.Title, m.ReleaseDate) } } ``` ### Parámetros | Parámetro | En | Obligatorio | Descripción | | ---------------------- | -------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | consulta | sí | Texto que buscar. Codifícalo para URL: los espacios pasan a `%20` o `+`. | | `api_key` | consulta | uno de los dos | Tu clave. Usa esta o el encabezado `Authorization: Bearer`. | | `year` | consulta | no | Año de cuatro dígitos. Conserva las películas con cualquier fecha de estreno en ese año, en cualquier país. | | `primary_release_year` | consulta | no | Año de cuatro dígitos. Coincide solo con la fecha de estreno principal, así que puede devolver menos títulos que `year`. | | `region` | consulta | no | Código de país de 2 letras en mayúsculas, como `US`. Reemplaza `release_date` por la fecha en ese país cuando se conoce. No elimina títulos. | | `include_adult` | consulta | no | Se acepta y se ignora. Nunca se devuelven títulos para adultos. | | `language` | consulta | no | Etiqueta de TMDB como `en-US` o `it-IT`. Se sirven 14 idiomas base, cualquier otro recurre al inglés. Valor por defecto `en-US`. | | `page` | consulta | no | Número de página de 1 a 500. Valor por defecto 1. | ### Campos de la respuesta | Campo | Tipo | Notas | | ------------------------------------------ | ---------------- | ----------------------------------------------------------------------------------------------- | | `page` | entero | La página que pediste. | | `results` | array | Hasta 20 entradas, la mejor coincidencia primero. | | `total_pages`, `total_results` | entero | Tamaño del conjunto de resultados de esta consulta. Limitado a 500 páginas y 10000 resultados. | | `id` | entero | Id de la película para el endpoint de detalles. | | `title`, `original_title` | texto | Título localizado y título original. | | `original_language` | texto | Código de dos letras del idioma en que se hizo la película. | | `overview` | texto | Texto localizado, vacío cuando no existe traducción. | | `release_date` | texto | `YYYY-MM-DD`, vacío para títulos sin fecha. | | `genre_ids` | array de enteros | Ids de género, no nombres. Conviértelos en nombres con [géneros](https://amodb.dev/es/genres/). | | `poster_path`, `backdrop_path` | texto o null | Añádelo a `https://img.amodb.dev/t/p/{size}`. | | `popularity`, `vote_average`, `vote_count` | número | Valores de clasificación y puntuación. | | `adult`, `video` | booleano | `adult` es siempre `false`. `video` es `true` para entradas marcadas como contenido de vídeo. | ### Ejemplo de respuesta ```json { "page": 1, "results": [ { "adult": false, "backdrop_path": "/zSBVQIvx4UIHoFf1oDvixHyIQrz.jpg", "genre_ids": [28, 878, 80], "id": 27205, "original_language": "en", "original_title": "Inception", "overview": "Cobb, a skilled thief who commits corporate espionage by infiltrating the subconscious of his targets is of...", "popularity": 60.9811, "poster_path": "/xlaY2zyzMfkhk0HSC5VUwzoZPU1.jpg", "release_date": "2010-07-15", "title": "Inception", "video": false, "vote_average": 8.373, "vote_count": 40459 }, { "adult": false, "backdrop_path": "/p8K8Z4yjaslJx5mTsIC5L6LJxQB.jpg", "genre_ids": [16, 28, 53], "id": 64956, "original_language": "en", "original_title": "Inception: The Cobol Job", "overview": "Cobb, Arthur and Nash are enlisted by Cobol Engineering.", "popularity": 1.9401, "poster_path": "/sNxqwtyHMNQwKWoFYDqcYTui5Ok.jpg", "release_date": "2010-12-07", "title": "Inception: The Cobol Job", "video": false, "vote_average": 7.2, "vote_count": 320 }, { "adult": false, "backdrop_path": null, "genre_ids": [10402], "id": 973484, "original_language": "en", "original_title": "Inception: Music from the Motion Picture", "overview": "The Special Features Blu-ray disc contains a lossless DTS-HD MA 5.1 surround mix of the Inception soundtrack.", "popularity": 0.4911, "poster_path": "/7uM4DyRVAcgagvhZoWrkrqMPbqV.jpg", "release_date": "2010-12-07", "title": "Inception: Music from the Motion Picture", "video": true, "vote_average": 7, "vote_count": 3 } ], "total_pages": 1, "total_results": 3 } ``` La respuesta incluye las tres coincidencias. Se obtuvo de la API real y solo se acortaron las cadenas largas de `overview`. ## Otros endpoints de búsqueda Todas las rutas de abajo comparten la base `https://api.amodb.dev/3`, necesitan `query` y devuelven el mismo envoltorio con `page`, `results`, `total_pages` y `total_results`. Cada una acepta también `page` de 1 a 500. `include_adult` se acepta en todas y se ignora. | Método y ruta | Encuentra | Parámetros adicionales | Campos de la entrada | | ------------------------ | ------------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------- | | `GET /search/tv` | Series de TV | `first_air_date_year`, `year`, `language` | `name`, `original_name`, `first_air_date`, `origin_country` | | `GET /search/person` | Personas | `language` | `name`, `original_name`, `known_for_department`, `gender`, `profile_path`, `known_for` | | `GET /search/multi` | Películas, series y personas a la vez | `language` | `media_type` más los campos de ese tipo | | `GET /search/collection` | Colecciones de películas | `language` | `name`, `original_name`, `overview`, `poster_path`, `backdrop_path` | | `GET /search/company` | Productoras | ninguno | `name`, `logo_path`, `origin_country` | | `GET /search/keyword` | Palabras clave | ninguno | `id`, `name` | En TV, `first_air_date_year` conserva las series cuya primera emisión es de ese año, mientras que `year` conserva también series anteriores que se emitieron ese año. Una búsqueda de `the` con `year=2010` devuelve The Simpsons, que se emitió por primera vez en 1989, y la misma búsqueda con `first_air_date_year=2010` no lo hace. Si envías ambos, deben coincidir los dos. Las entradas de personas llevan hasta 3 títulos en `known_for`, cada uno con `media_type`. `/search/multi` ignora `year`. Las entidades encontradas aquí continúan en [series de TV](https://amodb.dev/es/tv-series/), [personas](https://amodb.dev/es/people/), [colecciones](https://amodb.dev/es/collections/), [productoras y cadenas de TV](https://amodb.dev/es/companies-networks/) y [palabras clave](https://amodb.dev/es/keywords/). ### Búsqueda multi `media_type` es `movie`, `tv` o `person`, y te dice qué campos esperar. Las entradas de películas llevan `title` y las de TV y de personas llevan `name`. ```js const byType = { movie: [], tv: [], person: [] }; for (const r of results) byType[r.media_type]?.push(r.title || r.name); console.log(byType); ``` ## Errores `/search/tv` y `/search/person` responden a una consulta sin coincidencias con HTTP 200, un array `results` vacío y `total_results` en 0. Por ahora `/search/movie`, `/search/multi`, `/search/keyword`, `/search/company` y `/search/collection` responden al mismo caso con HTTP 500 y `status_code` 11. Trata un 500 en esas rutas como «sin resultados», salvo que se repita en consultas que sabes que coinciden. | HTTP | status_code | Cuándo | | ---- | ----------- | ----------------------------------------------------------------------------------------------------------------------- | | 401 | 7 | La clave falta o es incorrecta. | | 402 | 36 | El periodo del plan ha terminado. | | 405 | 37 | Llamaste a un método de escritura. | | 429 | 25 | Superaste tus solicitudes por minuto. Espera los segundos de `Retry-After`. | | 500 | 11 | Una consulta de película, multi, palabra clave, productora o colección sin coincidencias, o un `page` fuera de 1 a 500. | | 504 | 24 | El backend no respondió a tiempo. Reintenta una vez. | Consulta los [errores](https://amodb.dev/es/errors/) para ver la lista completa y los [límites de solicitudes](https://amodb.dev/es/rate-limits/) para las ventanas. ## Notas prácticas - La caché perimetral guarda una búsqueda 10 minutos y comparte la copia entre claves. Cada llamada sigue contando para tus 20, 40 o 120 solicitudes por minuto, porque el límite se aplica antes de la caché. - Para un cuadro de búsqueda, espera 300 ms después de la última pulsación de tecla y cancela la solicitud en curso. Un cuadro que dispara una solicitud con cada tecla puede agotar un plan de 20 solicitudes por minuto en segundos. - Pasa la consulta a minúsculas y quita los espacios sobrantes antes de usarla como clave de caché de tu lado. - Para buscar un título por id de IMDb, omite la búsqueda y usa la [búsqueda por id externo](https://amodb.dev/es/find-by-external-id/). - Un id de palabra clave de `/search/keyword` alimenta el filtro `with_keywords` de [discover](https://amodb.dev/es/discover/), y un id de productora alimenta `with_companies`. ## Preguntas y respuestas ### ¿Cuántos resultados devuelve una página de búsqueda? Cada página contiene 20 resultados, y el parámetro page va de 1 a 500. Lee total_pages y total_results de la respuesta, y acota las consultas vagas con year o primary_release_year. ### ¿Las búsquedas en caché cuentan para mi límite de solicitudes? Sí. La caché perimetral guarda una búsqueda 10 minutos y comparte esa copia entre claves, pero la comprobación de la clave y el límite de solicitudes se ejecutan antes de consultar la caché, así que cada llamada cuenta una vez. ### ¿Puedo buscar por id de IMDb con estos endpoints? No. Usa GET /3/find/{external_id} con external_source=imdb_id. Devuelve movie_results, tv_results y person_results para ese id, y se describe en la página de buscar por id externo. ### ¿En qué idioma están los resultados? El parámetro language fija los títulos y las sinopsis, por defecto en-US. Las etiquetas fuera de los 14 idiomas base recurren al inglés. Los títulos originales siguen disponibles en original_title y original_name. ## 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. - [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. - [API Discover](https://amodb.dev/es/discover/): API Discover con los mismos filtros que TMDB v3. Lista películas y series por género, reparto, productora, palabra clave, año, nota, duración y plataforma. - [Buscar por id externo](https://amodb.dev/es/find-by-external-id/): Busca una película, serie o persona por id de IMDb, TVDB, Wikidata o Kinopoisk con el endpoint find de TMDB, y lee los ids externos y los datos de Wikidata. - [Límites de solicitudes](https://amodb.dev/es/rate-limits/): amodb limita cada clave por solicitudes por minuto en una ventana deslizante de 60 segundos: 20, 40 o 120 según el plan. Lee los encabezados y gestiona el 429. Actualizado: 2026-10-18. Source: https://amodb.dev/es/search/