Person details API

The person endpoint returns one actor, director or crew member by id at GET /3/person/{person_id}. The JSON matches TMDB v3: biography, birthday, place of birth, profile image and department. Companion endpoints return movie, TV and combined credits, external ids, profile images and the popular list.

Get person details

GET /3/person/{person_id} returns the core record for one person: name, biography, birthday, place of birth, department, profile image and IMDb id. The id is the numeric TMDB person id, so Tom Hanks stays 31 and Leonardo DiCaprio stays 6193. People who work in front of and behind the camera share one id space.

The example reads Tom Hanks and appends his combined credits, then prints the name, birthday, main department and how many acting credits he has.

curl -sSf "https://api.amodb.dev/3/person/31?language=en-US&append_to_response=combined_credits" \
  -H "Authorization: Bearer $AMODB_KEY"
const url = 'https://api.amodb.dev/3/person/31?language=en-US&append_to_response=combined_credits';
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } });
if (!res.ok) throw new Error(`amodb returned ${res.status}`);
const person = await res.json();
console.log(person.name, person.birthday, person.known_for_department, person.combined_credits.cast.length);
import os
import requests

r = requests.get(
    "https://api.amodb.dev/3/person/31",
    params={"language": "en-US", "append_to_response": "combined_credits"},
    headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
    timeout=10,
)
r.raise_for_status()
person = r.json()
print(person["name"], person["birthday"], person["known_for_department"], len(person["combined_credits"]["cast"]))
<?php
$url = 'https://api.amodb.dev/3/person/31?language=en-US&append_to_response=combined_credits';
$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");
}
$person = json_decode($body, true);
echo $person['name'], ' ', $person['birthday'], ' ', count($person['combined_credits']['cast']), PHP_EOL;
package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"os"
	"time"
)

type Person struct {
	Name         string `json:"name"`
	Birthday     string `json:"birthday"`
	Department   string `json:"known_for_department"`
	PlaceOfBirth string `json:"place_of_birth"`
}

func main() {
	req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/person/31?language=en-US", 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 Person
	if err := json.NewDecoder(res.Body).Decode(&p); err != nil {
		panic(err)
	}
	fmt.Println(p.Name, p.Birthday, p.Department, p.PlaceOfBirth)
}

Parameters

ParameterInRequiredDescription
person_idpathyesNumeric person id, for example 31.
api_keyqueryone of twoYour key. Use this or the Authorization: Bearer header.
languagequerynoTMDB tag such as en-US or ru-RU. The biography is returned in that language when a translation exists.
append_to_responsequerynoComma separated list: movie_credits, tv_credits, combined_credits, external_ids, images. Unknown names are ignored.

Response fields

FieldTypeNotes
idintegerPerson id.
namestringDisplay name, in the requested language when a translation exists.
also_known_asarrayAlternative names and spellings.
biographystringLocalized text, empty when no translation exists.
birthday, deathdaystring or nullYYYY-MM-DD. deathday is null for living people.
place_of_birthstring or nullFree text.
genderinteger0 not specified, 1 female, 2 male, 3 non-binary.
known_for_departmentstringMain job, for example Acting or Directing.
imdb_idstring or nullIMDb person id such as nm0000158.
homepagestring or nullOfficial site.
profile_pathstring or nullAppend to https://img.amodb.dev/t/p/{size}. See images.
popularitynumberRelative score used by the popular list.
adultbooleanAlways false. Adult people are never served.

Example response

GET /3/person/31?language=en-US, with the biography shortened:

JSON
{
  "adult": false,
  "also_known_as": [
    "Thomas Jeffrey Hanks"
  ],
  "biography": "Thomas Jeffrey Hanks (born July 9, 1956) is an American actor and filmmaker. Known for both his comedic and dramatic roles, Hanks is one of the most popular...",
  "birthday": "1956-07-09",
  "deathday": null,
  "gender": 2,
  "homepage": null,
  "id": 31,
  "imdb_id": "nm0000158",
  "known_for_department": "Acting",
  "name": "Tom Hanks",
  "place_of_birth": "Concord, California, USA",
  "popularity": 12.98,
  "profile_path": "/oFvZoKI6lvU03n4YoNGAll9rkas.jpg"
}

Filmography endpoints

Three endpoints list what a person worked on. All take language and return the keys id, cast and crew. When you append them with append_to_response, the id key is left out.

Method and pathReturnsExtra parameters
GET /person/{person_id}/movie_creditsMovies, with character and order in cast and department and job in crewnone
GET /person/{person_id}/tv_creditsShows, with character in cast and department and job in crewnone
GET /person/{person_id}/combined_creditsMovies and shows together, each with media_type set to movie or tvnone

Movie entries carry title and release_date. TV entries carry name and first_air_date, and TV cast entries also hold an episode_count key that is 0 in current data. Entries also carry credit_id, genre_ids, poster_path, vote_average and the other list fields. The snippet below sorts combined credits by date and prints the five newest.

JavaScript
const credits = person.combined_credits;
const date = (c) => c.release_date || c.first_air_date || '';
const latest = credits.cast.filter((c) => date(c)).sort((a, b) => date(b).localeCompare(date(a))).slice(0, 5);
for (const c of latest) console.log(date(c), c.media_type, c.title || c.name, 'as', c.character);

Lists and images

Method and pathReturnsExtra parameters
GET /person/popularPaged list of popular people with known_for titleslanguage, page
GET /person/{person_id}/imagesProfile photos in a profiles arraynone
GET /person/{person_id}/external_idsimdb_id, wikidata_id, facebook_id, instagram_id, tiktok_id, twitter_id, youtube_idnone

Popular entries hold id, name, original_name, known_for_department, gender, profile_path, popularity and a known_for array. Pages run from 1 to 500. Profile photos are covered on images, and external ids are on find by external id.

amodb does not offer person translations, the newest person record, tagged images or changes. Ask for the biography in the language you need with the language parameter instead.

Errors

HTTPstatus_codeWhen
4017The key is missing or wrong.
40236The plan period has ended.
40434No person with that id, an adult person, or a path that is not offered.
40537You called a write method.
42925Over your requests per minute. Wait for the Retry-After seconds.

The full list is on errors, and the windows per plan are on rate limits.

Practical notes

  • Person details and credit lists are cached for 6 hours. The popular list is cached for 30 minutes and pages run from 1 to 500.
  • Add combined_credits through append_to_response instead of making a second call. Both ways return the same data.
  • In movie_credits, each cast entry has an order value, the person's billing position in that movie. TV entries have no order, so sort them by first_air_date.
  • Use known_for_department to decide which list to show first: cast for actors, crew for directors and writers.
  • Look up a person by name on search, then use the id here.