Companies and networks

The company and network endpoints return the name, origin country and logo path of a studio or a TV network by id, at GET /3/company/{company_id} and GET /3/network/{network_id}. Paths and JSON match TMDB v3. Pass the ids to with_companies and with_networks in discover to list their titles.

Updated View as Markdown

Get company details

GET /3/company/{company_id} returns one production company: name, origin country and logo path. It also carries description, headquarters, homepage and parent_company, but amodb leaves them empty. The id is the TMDB company id, so ids you stored earlier keep working.

The sample below reads the first production company of movie 550 and then loads that company.

bashjspyphpgo
COMPANY_ID=$(curl -sf "https://api.amodb.dev/3/movie/550" \
  -H "Authorization: Bearer $AMODB_KEY" | jq '.production_companies[0].id')
curl -sf "https://api.amodb.dev/3/company/$COMPANY_ID" \
  -H "Authorization: Bearer $AMODB_KEY"
const base = 'https://api.amodb.dev/3';
const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` };

async function get(path) {
  const res = await fetch(base + path, { headers });
  if (!res.ok) throw new Error(`amodb returned ${res.status} for ${path}`);
  return res.json();
}

const movie = await get('/movie/550');
const company = await get(`/company/${movie.production_companies[0].id}`);
console.log(company.name, company.origin_country, company.logo_path);
import os
import requests

BASE = "https://api.amodb.dev/3"
HEADERS = {"Authorization": f"Bearer {os.environ['AMODB_KEY']}"}


def get(path):
    r = requests.get(BASE + path, headers=HEADERS, timeout=10)
    r.raise_for_status()
    return r.json()


movie = get("/movie/550")
company = get(f"/company/{movie['production_companies'][0]['id']}")
print(company["name"], company["origin_country"], company["logo_path"])
<?php
function amodb_get(string $path): array {
    $ch = curl_init('https://api.amodb.dev/3' . $path);
    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 for $path");
    }
    return json_decode($body, true);
}

$movie = amodb_get('/movie/550');
$company = amodb_get('/company/' . $movie['production_companies'][0]['id']);
echo $company['name'], ' ', $company['origin_country'], PHP_EOL;
package main

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

var client = &http.Client{Timeout: 10 * time.Second}

func get(path string, out any) error {
	req, err := http.NewRequest("GET", "https://api.amodb.dev/3"+path, nil)
	if err != nil {
		return err
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("AMODB_KEY"))
	res, err := client.Do(req)
	if err != nil {
		return err
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		return fmt.Errorf("amodb returned %s for %s", res.Status, path)
	}
	return json.NewDecoder(res.Body).Decode(out)
}

func main() {
	var movie struct {
		Companies []struct {
			ID int `json:"id"`
		} `json:"production_companies"`
	}
	if err := get("/movie/550", &movie); err != nil || len(movie.Companies) == 0 {
		panic("movie has no production companies")
	}
	var company struct {
		Name          string `json:"name"`
		OriginCountry string `json:"origin_country"`
	}
	if err := get(fmt.Sprintf("/company/%d", movie.Companies[0].ID), &company); err != nil {
		panic(err)
	}
	fmt.Println(company.Name, company.OriginCountry)
}

Parameters

  • company_idpathrequired
    Numeric company id, for example 25.
  • api_keyqueryone of two
    Your key. Use this or the Authorization: Bearer header.

Response fields

FieldTypeNotes
descriptionstringAlways an empty string.
headquartersstringCity or region. Empty for most companies.
homepagestringWebsite address. Empty for most companies.
idintegerCompany id.
logo_pathstring or nullAppend to https://img.amodb.dev/t/p/{size}.
namestringCompany name.
origin_countrystringISO 3166-1 code such as US. Can be empty.
parent_companynullAlways null. amodb does not fill the parent.

Example response

JSON
{
  "description": "",
  "headquarters": "",
  "homepage": "",
  "id": 25,
  "logo_path": "/nM2MfoMqzJQRiSynsDabOtFKetD.png",
  "name": "20th Century Fox",
  "origin_country": "US",
  "parent_company": null
}

The same shape comes back for every company id, for example /3/company/1 for Lucasfilm.

Get network details

GET /3/network/{network_id} returns a TV network: name, origin country, logo path, headquarters and homepage. It has no description and no parent_company. Read a network id from the networks array of a series. The series /3/tv/1399 lists HBO with id 49.

JSON
{
  "headquarters": "",
  "homepage": "",
  "id": 49,
  "logo_path": "/tuomPhY2UtuPTqqFnKMVHvSb724.png",
  "name": "HBO",
  "origin_country": "US"
}
FieldTypeNotes
headquartersstringEmpty for most networks.
homepagestringEmpty for most networks.
idintegerNetwork id.
logo_pathstring or nullLogo file path.
namestringNetwork name.
origin_countrystringISO 3166-1 code. An empty string for global streaming services such as Netflix.

Endpoints in this group

Every path shares the base https://api.amodb.dev/3 and the same auth as other endpoints.

Method and pathReturnsParameters
GET /company/{company_id}Company recordcompany_id
GET /network/{network_id}Network recordnetwork_id
GET /search/companyPaged list of companies with id, name, logo_path, origin_countryquery, page

amodb does not offer alternative_names or images paths for companies and networks. The logo is the logo_path in the record itself.

Logos

Build the logo address as https://img.amodb.dev/t/p/w185 plus logo_path. GET /3/configuration lists the logo sizes: w92, w154, w185, w300, w500 and original. The images page has the full size table. Logo files are mostly PNG, and image files need no key. A company without a logo has logo_path set to null.

Filter discover by company or network

Company and network ids are most useful as filters. Discover turns an id into a list of titles.

FilterWorks onMeaning
with_companies/discover/movie and /discover/tvTitles made by these companies.
with_networks/discover/tvSeries aired by these networks. Movie discover ignores it.

Separate several ids with a comma to require all of them, or with a pipe character (encoded as %7C) to accept any of them. The call below lists movies for one company, sorted by popularity. The second call lists the series that HBO aired.

curl
curl -sf "https://api.amodb.dev/3/discover/movie?with_companies=$COMPANY_ID&sort_by=popularity.desc&page=1" \
  -H "Authorization: Bearer $AMODB_KEY"

curl -sf "https://api.amodb.dev/3/discover/tv?with_networks=49&sort_by=popularity.desc" \
  -H "Authorization: Bearer $AMODB_KEY"

Discover results are cached at the edge for 30 minutes and arrive 20 per page. The full filter list is on the discover page.

Find a company by name

GET /3/search/company?query=lucasfilm returns a paged list. Each row has id, logo_path, name and origin_country. The rows are not ranked by exact match: the studio called Lucasfilm Ltd. has id 1 and is the third row, after two similar names. Compare name and origin_country before you take an id. The query rules are on the search page. There is no network search path.

Errors

A company or network that does not exist returns the TMDB error body with status_code 34. Other failures use the same body.

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

See errors for the whole list and rate limits for the headers.

Practical notes

  • Store the company id next to the name. Names change, ids do not.
  • Check logo_path for null before you render it. Do not rely on homepage, headquarters or description, because they are empty.
  • Company and network details are cached for 6 hours at the edge. Logo files on img.amodb.dev are cached for 30 days.
  • A network is a TV concept. To get its series, use with_networks on /discover/tv, not on movie discover.
  • To find a company by name, use the company search above, then pick the right row by name and origin_country.