# Ricerca per ID esterno > GET /3/find/{external_id} trasforma un ID IMDb, TVDB, Wikidata, Kinopoisk, Facebook, Twitter o Instagram in risultati in stile TMDB, e gli endpoint external_ids fanno il percorso inverso. Un endpoint Wikidata aggiunge budget, incassi, premi e titoli collegati per un film o una serie. Tutto usa la tua normale chiave. ## Endpoint `GET /3/find/{external_id}` ```bash curl "https://api.amodb.dev/3/find/tt0137523?external_source=imdb_id" \ -H "Authorization: Bearer $AMODB_KEY" ``` Risposta: ```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": [] } ``` ## Trovare un titolo per ID esterno `GET /3/find/{external_id}` prende un ID di un altro sistema e restituisce i record corrispondenti. Il percorso contiene l'ID, e il parametro di query `external_source` dice da quale sistema proviene. amodb accetta dodici fonti e sette di esse portano a dei record: `imdb_id`, `tvdb_id`, `wikidata_id`, `kinopoisk_id`, `facebook_id`, `twitter_id` e `instagram_id`. L'esempio associa l'ID IMDb `tt0137523` a un 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 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) } ``` ### Parametri | Parametro | In | Obbligatorio | Descrizione | | ----------------- | -------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `external_id` | percorso | sì | L'ID nell'altro sistema, per esempio `tt0137523`. | | `external_source` | query | sì | Uno tra `imdb_id`, `tvdb_id`, `wikidata_id`, `kinopoisk_id`, `facebook_id`, `twitter_id`, `instagram_id`. Altri cinque sono accettati e non restituiscono nulla: `freebase_mid`, `freebase_id`, `tvrage_id`, `tiktok_id`, `youtube_id`. | | `language` | query | no | Una delle 14 lingue come `en` o `ru-RU`. Gli altri valori ripiegano su `en`. | | `api_key` | query | uno dei due | La tua chiave. Usa questa o l'header `Authorization: Bearer`. | Un `external_source` mancante, o non presente nell'elenco, risponde 400 con `status_code` 22. Il valore deve essere in minuscolo. ### Campi della risposta | Campo | Tipo | Note | | -------------------- | ----- | ----------------------------------------------------------------------------------------------------------- | | `movie_results` | array | Record di film con gli stessi campi di un risultato di ricerca, più `media_type` impostato su `movie`. | | `person_results` | array | Persone corrispondenti all'ID. Ognuna ha `known_for` come array vuoto e `media_type` impostato su `person`. | | `tv_results` | array | Record di serie TV con `media_type` impostato su `tv`. | | `tv_episode_results` | array | Sempre vuoto. | | `tv_season_results` | array | Sempre vuoto. | ### Risposta di esempio ```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 trama è tagliata. ### Quale fonte trova cosa | `external_source` | Aspetto dell'ID | Esempio | Array di risultati abituale | | ------------------------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------ | | `imdb_id` | `tt` più cifre per i titoli, `nm` più cifre per le persone | `tt0137523`, `nm0000093` (Brad Pitt) | `movie_results`, `tv_results` o `person_results` | | `tvdb_id` | Numero | `81189` (Breaking Bad) | `tv_results` | | `wikidata_id` | `Q` più cifre | `Q190050` (Fight Club), `Q1079` (Breaking Bad), `Q35332` (Brad Pitt) | `movie_results`, `tv_results` o `person_results` | | `kinopoisk_id` | Numero | `361` (Fight Club), `404900` (Breaking Bad) | `movie_results` o `tv_results` | | `facebook_id`, `twitter_id`, `instagram_id` | Nome dell'account | `FightClub` | Dipende dall'account | Lo stesso nome di account può corrispondere a più di un titolo. Per esempio `instagram_id=breakingbad` restituisce la serie e il film El Camino, quindi leggi tutti gli array. ```bash curl -sf "https://api.amodb.dev/3/find/361?external_source=kinopoisk_id" \ -H "Authorization: Bearer $AMODB_KEY" ``` ## ID esterni di un titolo noto La direzione opposta è un insieme di endpoint `external_ids`. Restituiscono gli ID che altri sistemi usano per un record che hai già. | Metodo e percorso | Restituisce | Parametri | | -------------------------------------- | ------------------------------------------------------------------------------------------------ | ----------- | | `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` | Gli stessi più `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 che un titolo non ha torna come `null`. `kinopoisk_id` è una stringa ed è presente per un film o una serie solo se amodb lo conosce. Una risposta reale per `/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 risposta reale per `/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" } ``` Gli endpoint `external_ids` di stagioni ed episodi esistono, ma oggi tutti i loro ID sono `null`, quindi lasciali perdere. ## Dati Wikidata `GET /3/movie/{movie_id}/wikidata` e `GET /3/tv/{tv_id}/wikidata` restituiscono l'ID Wikidata di un titolo e dati su di esso: denaro, titoli vicini in una serie, pagine Wikipedia, premi e luoghi. Ogni chiave è sempre presente. Un dato non noto vale `null` per un valore singolo e `[]` per una lista. | Metodo e percorso | Restituisce | Parametri | | -------------------------------- | -------------------------------------------------- | ----------------------------------- | | `GET /movie/{movie_id}/wikidata` | ID Wikidata e dati | `movie_id`, `language` | | `GET /tv/{tv_id}/wikidata` | ID Wikidata e dati | `tv_id`, `language` | | `append_to_response=wikidata` | Lo stesso blocco sotto `wikidata`, con il suo `id` | Aggiunto a una chiamata di dettagli | Questa è la risposta per Fight Club (film 550), tagliata a una dimensione leggibile: ```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": [] } ``` L'oggetto `sitelinks` ha 14 voci e `awards` ne ha 5. Entrambi sono tagliati qui. | Campo | Tipo | Note | | ------------------------------------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `id` | intero | ID TMDB del titolo. Resta presente con `append_to_response`. | | `wikidata_id` | stringa o null | Elemento Wikidata come `Q190050`. | | `budget` | oggetto o null | `value` è un intero arrotondato e `currency` è un codice ISO o `null`. | | `box_office` | oggetto o null | Come `budget`, più `worldwide` impostato su `true` o `false`. | | `follows`, `followed_by` | oggetto o null | Il titolo precedente e il successivo in una serie di film, come collegamento. | | `sitelinks` | oggetto | Associa un codice di lingua al titolo della pagina Wikipedia. Le chiavi sono le 14 lingue servite. `{}` quando non ce n'è nessuna. | | `awards`, `nominations` | array | Collegamenti con un `year` facoltativo. | | `based_on` | array | Opere di origine con `wikidata_id`, `label` e un oggetto `author` o `null`. | | `filming_locations`, `narrative_locations`, `original_broadcasters` | array | Collegamenti. Breaking Bad ha AMC in `original_broadcasters`. | Un collegamento ha `wikidata_id`, `label` e, quando l'elemento è un titolo del catalogo, `tmdb_id` e `media_type`. Per The Matrix Reloaded (film 604) i titoli vicini sono collegamenti ai film 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" } } ``` Ogni `label` arriva nella `language` della richiesta e ripiega sull'inglese. Con `language=ru` l'autore qui sopra si legge `Чак Паланик`. ## Errori Gli errori usano il corpo TMDB, per esempio `{"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` manca, non è in minuscolo o non è nell'elenco. | | 401 | 7 | La chiave manca o è sbagliata. | | 402 | 36 | Il periodo del piano è terminato. | | 404 | 34 | L'ID del titolo in un percorso `wikidata` non esiste. | | 429 | 25 | Oltre le tue richieste al minuto. Attendi i secondi di `Retry-After`. | Un ID esterno sconosciuto su `find` non è un errore: aspettati cinque array vuoti. Nemmeno gli endpoint `external_ids` rispondono 404 per un ID sconosciuto. Rispondono 200 con tutti gli ID a `null`. Vedi [errori](https://amodb.dev/it/errors/) e [autenticazione](https://amodb.dev/it/authentication/). ## Note pratiche - Salva l'ID TMDB la prima volta che risolvi un ID esterno. Le chiamate successive saltano allora `find` e vanno dritte al percorso dei dettagli, risparmiando una richiesta per titolo. - Controlla sempre che l'array che ti serve contenga un elemento. `find` può restituire più array insieme per un solo ID. - Dettagli e ID esterni restano in cache sull'edge per 6 ore. Una ricerca ripetuta in quel tempo restituisce la risposta salvata. - `wikidata_id` funziona nei due sensi: passalo a `find` per ottenere un titolo, oppure leggilo da `external_ids` per collegarti all'esterno. - Per portare le ricerche IMDb in stile OMDb, vedi l'[endpoint OMDb](https://amodb.dev/it/omdb-endpoint/). Per i punteggi dopo aver risolto un titolo, vedi [valutazioni](https://amodb.dev/it/ratings/). ## Domande e risposte ### Quali fonti esterne accetta find? Per external_source sono accettati dodici valori. Sette di essi restituiscono risultati: imdb_id, tvdb_id, wikidata_id, kinopoisk_id, facebook_id, twitter_id e instagram_id. Gli altri cinque restituiscono array vuoti. Il valore è obbligatorio, in minuscolo ed esatto, per esempio external_source=imdb_id. ### Perché find restituisce cinque array? Un ID può indicare un film, una persona, una serie, un episodio o una stagione, quindi la risposta ha un array per ogni tipo. In amodb solo movie_results, person_results e tv_results contengono elementi. tv_episode_results e tv_season_results sono sempre vuoti. ### Cosa succede quando l'ID è sconosciuto? Ottieni lo stato 200 con tutti e cinque gli array vuoti, come in TMDB. Controlla che almeno un array contenga un elemento prima di leggerlo. Un external_source mancante o sconosciuto è diverso: risponde 400 con status_code 22. ### Come ottengo un ID Kinopoisk per un titolo che ho già? Chiama l'endpoint external_ids del film o della serie. Restituisce kinopoisk_id come stringa, per esempio 361 per Fight Club, oppure null quando amodb non lo conosce. Passa quella stringa a find con external_source=kinopoisk_id per tornare indietro. ### Posso aggiungere wikidata a una chiamata di dettagli? Sì. Aggiungi append_to_response=wikidata a una richiesta di dettagli di film o serie TV e il blocco Wikidata arriva sotto la chiave wikidata, nella stessa richiesta e senza chiamate in più. ## Pagine correlate - [API dei dettagli del film](https://amodb.dev/it/movies/): API dettagli film con gli stessi percorsi e JSON di TMDB v3. Ottieni un film per ID, aggiungi crediti, valutazioni e mood con append_to_response, in 14 lingue. - [API delle serie TV](https://amodb.dev/it/tv-series/): API serie TV con gli stessi percorsi e JSON di TMDB v3. Ottieni una serie per ID con stagioni, emittenti e prossimo episodio, più classificazioni e piattaforme. - [Valutazioni di film e serie TV](https://amodb.dev/it/ratings/): API valutazioni film: punteggi IMDb, Kinopoisk, Metacritic, Rotten Tomatoes e TMDB di un titolo in una chiamata, con null per le fonti non note. - [API dei dettagli della persona](https://amodb.dev/it/people/): API dettagli persona con gli stessi percorsi e JSON di TMDB v3. Ottieni attore o troupe per ID, con biografia, filmografia, ID esterni e lista dei popolari. - [Endpoint compatibile OMDb](https://amodb.dev/it/omdb-endpoint/): Endpoint compatibile OMDb su api.amodb.dev/omdb/. Cerca con i o t, ricerca con s, leggi l'array Ratings e tieni il tuo client cambiando solo l'URL di base. - [Autenticazione](https://amodb.dev/it/authentication/): Come inviare la chiave amodb: api_key nella query, un header Authorization Bearer o apikey per le chiamate OMDb. Formato, conservazione, rotazione, errori 401. Aggiornato: 2026-10-18. Source: https://amodb.dev/it/find-by-external-id/