Recherche par identifiant externe

Trouver un titre par identifiant externe

GET /3/find/{external_id} prend un identifiant d'un autre système et renvoie les fiches correspondantes. Le chemin contient l'identifiant, et le paramètre de requête external_source indique de quel système il vient. amodb accepte douze sources, dont sept donnent des fiches : imdb_id, tvdb_id, wikidata_id, kinopoisk_id, facebook_id, twitter_id et instagram_id.

L'exemple associe l'identifiant IMDb tt0137523 à un identifiant TMDB.

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

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');

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
$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;

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)
}

Paramètres

• external_idcheminobligatoire
  L'identifiant dans l'autre système, par exemple tt0137523.
• external_sourcerequêteobligatoire
  L'une des valeurs imdb_id, tvdb_id, wikidata_id, kinopoisk_id, facebook_id, twitter_id, instagram_id. Cinq autres sont acceptées et ne renvoient rien : freebase_mid, freebase_id, tvrage_id, tiktok_id, youtube_id.
• languagerequête
  L'une des 14 langues comme en ou ru-RU. Les autres valeurs se replient sur en.
• api_keyrequêtel'un des deux
  Votre clé. Utilisez-la ou l'en-tête Authorization: Bearer.

Un external_source absent, ou qui ne figure pas dans la liste, répond 400 avec status_code 22. La valeur doit être en minuscules.

Champs de la réponse

Exemple de réponse

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

Le résumé est coupé.

Quelle source trouve quoi

Un même nom de compte peut correspondre à plusieurs titres. Par exemple, instagram_id=breakingbad renvoie la série et le film El Camino : lisez donc tous les tableaux.

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

Identifiants externes d'un titre connu

Le sens inverse est un ensemble de points de terminaison external_ids. Ils renvoient les identifiants qu'utilisent d'autres systèmes pour une fiche que vous avez déjà.

Un identifiant qu'un titre n'a pas revient à null. kinopoisk_id est une chaîne et n'est présent pour un film ou une série que si amodb le connaît. Une vraie réponse pour /3/movie/550/external_ids :

{
  "id": 550,
  "imdb_id": "tt0137523",
  "wikidata_id": "Q190050",
  "facebook_id": "FightClub",
  "instagram_id": null,
  "twitter_id": null,
  "kinopoisk_id": "361"
}

Une vraie réponse pour /3/tv/1396/external_ids :

{
  "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"
}

Les points de terminaison external_ids des saisons et des épisodes existent, mais tous leurs identifiants valent null aujourd'hui : laissez-les de côté.

Faits Wikidata

GET /3/movie/{movie_id}/wikidata et GET /3/tv/{tv_id}/wikidata renvoient l'identifiant Wikidata d'un titre et des faits à son sujet : argent, voisins dans une série, pages Wikipédia, récompenses et lieux. Chaque clé est toujours présente. Un fait inconnu vaut null pour une valeur unique et [] pour une liste.

Voici la réponse pour Fight Club (film 550), réduite à une taille lisible :

{
  "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'objet sitelinks a 14 entrées et awards en a 5. Les deux sont réduits ici.

Un lien a wikidata_id, label et, quand l'élément est un titre du catalogue, tmdb_id et media_type. Pour The Matrix Reloaded (film 604), les voisins sont des liens vers les films 603 et 605 :

{
  "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"
  }
}

Chaque label vient dans la language de la requête et se replie sur l'anglais. Avec language=ru, l'auteur ci-dessus s'écrit Чак Паланик.

Erreurs

Les erreurs utilisent le corps TMDB, par exemple {"success": false, "status_code": 7, "status_message": "Invalid API key: You must be granted a valid key."}.

Un identifiant externe inconnu sur find n'est pas une erreur : attendez-vous à cinq tableaux vides. Les points de terminaison external_ids ne répondent pas non plus 404 pour un identifiant inconnu. Ils répondent 200 avec tous les identifiants à null. Voir erreurs et authentification.

Remarques pratiques

• Enregistrez l'identifiant TMDB la première fois que vous résolvez un identifiant externe. Les appels suivants sautent alors find et vont directement au chemin de détails, ce qui économise une requête par titre.
• Vérifiez toujours que le tableau voulu contient un élément. find peut renvoyer plusieurs tableaux à la fois pour un même identifiant.
• Les détails et les identifiants externes sont mis en cache 6 heures en périphérie. Une recherche répétée dans ce délai renvoie la réponse stockée.
• wikidata_id fonctionne dans les deux sens : passez-le à find pour obtenir un titre, ou lisez-le dans external_ids pour faire un lien sortant.
• Pour reprendre les recherches IMDb de style OMDb, voir le point de terminaison OMDb. Pour les notes après avoir résolu un titre, voir notes.