# IMDB API
> 18 endpoints for live IMDB data — title + name search, detail, cast, known-for, ID/URL helpers.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/imdb-api/..."
```

## Pricing
- **Free** (Free) — 100 calls/Mo, 1 req/s
- **Basic** ($15/Mo) — 25,000 calls/Mo, 10 req/s
- **Pro** ($49/Mo) — 100,000 calls/Mo, 20 req/s
- **Mega** ($149/Mo) — 500,000 calls/Mo, 50 req/s

## Endpoints

### Search

#### `GET /v1/search/all` — Search all

Suche über Titel + Personen + Bilder. Query: query.

**Parameters:**
- `query` (query, required, string) — Search text Example: `matrix`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/imdb-api/v1/search/all?query=matrix"
```

**Response:**
```json
{
    "data": {
        "count": 8,
        "query": "matrix",
        "results": [
            {
                "id": "tt0133093",
                "rank": 282,
                "type": "feature",
                "year": 1999,
                "image": {
                    "url": "https://m.media-amazon.com/images/M/MV5BN2NmN2VhMTQtMDNiOS00NDlhLTliMjgtODE2ZTY0ODQyNDRhXkEyXkFqcGc@._V1_.jpg",
                    "width": 2100,
                    "height": 3156
                },
                "title": "The Matrix",
                "type_id": "movie",
                "name_url": null,
                "title_url": "https://www.imdb.com/title/tt0133093/",
                "cast_or_description": "Keanu Reeves, Laurence Fishburne"
            },
            {
                "id": "tt0234215",
                "rank": 1966,
                "type": "feature",
                "year": 2003,
                "image": {
                    "url": "https://m.media-amazon.com/images/M/MV5BNjAxYjkxNjktYTU0YS00NjFhLWIyMDEtMzEzMTJjMzRkMzQ1XkEyXkFqcGc@._V1_.jpg",
                    "width": 800,
                    "height": 1200
                },
                "title": "The Matrix Reloaded",
                "type_id": "movie",
                "name_url": null,
                "title_url": "https://www.imdb.com/title/tt0234215/",
                "cast_or_description": "Keanu Reeves, Laurence Fishburne"
            },
            {
                "id": "tt10838180",
                "rank":
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/search/titles` — Search titles

Titel-Suche (Filme, Serien, Episoden).

**Parameters:**
- `query` (query, required, string) — Title search text Example: `matrix`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/imdb-api/v1/search/titles?query=matrix"
```

**Response:**
```json
{
    "data": {
        "count": 8,
        "query": "matrix",
        "titles": [
            {
                "id": "tt0133093",
                "rank": 282,
                "type": "feature",
                "year": 1999,
                "image": {
                    "url": "https://m.media-amazon.com/images/M/MV5BN2NmN2VhMTQtMDNiOS00NDlhLTliMjgtODE2ZTY0ODQyNDRhXkEyXkFqcGc@._V1_.jpg",
                    "width": 2100,
                    "height": 3156
                },
                "title": "The Matrix",
                "type_id": "movie",
                "name_url": null,
                "title_url": "https://www.imdb.com/title/tt0133093/",
                "cast_or_description": "Keanu Reeves, Laurence Fishburne"
            },
            {
                "id": "tt0234215",
                "rank": 1966,
                "type": "feature",
                "year": 2003,
                "image": {
                    "url": "https://m.media-amazon.com/images/M/MV5BNjAxYjkxNjktYTU0YS00NjFhLWIyMDEtMzEzMTJjMzRkMzQ1XkEyXkFqcGc@._V1_.jpg",
                    "width": 800,
                    "height": 1200
                },
                "title": "The Matrix Reloaded",
                "type_id": "movie",
                "name_url": null,
                "title_url": "https://www.imdb.com/title/tt0234215/",
                "cast_or_description": "Keanu Reeves, Laurence Fishburne"
            },
            {
                "id": "tt10838180",
                "rank": 
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/search/names` — Search names

Personen-Suche (Schauspieler, Regisseure, etc.).

**Parameters:**
- `query` (query, required, string) — Name search text Example: `jlo`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/imdb-api/v1/search/names?query=jlo"
```

**Response:**
```json
{
    "data": {
        "count": 5,
        "names": [
            {
                "id": "nm0000182",
                "rank": 701,
                "type": null,
                "year": null,
                "image": {
                    "url": "https://m.media-amazon.com/images/M/MV5BMTY0OTY3ODA3OV5BMl5BanBnXkFtZTcwMzMyMzQ1NQ@@._V1_.jpg",
                    "width": 1797,
                    "height": 2048
                },
                "title": "Jennifer Lopez",
                "type_id": null,
                "name_url": "https://www.imdb.com/name/nm0000182/",
                "title_url": null,
                "cast_or_description": "Producer, Hustlers (2019)"
            },
            {
                "id": "nm0001349",
                "rank": 738,
                "type": null,
                "year": null,
                "image": {
                    "url": "https://m.media-amazon.com/images/M/MV5BNjIyNzI0MTAyOV5BMl5BanBnXkFtZTcwMDM3MTUwNw@@._V1_.jpg",
                    "width": 2048,
                    "height": 1363
                },
                "title": "Jennifer Love Hewitt",
                "type_id": null,
                "name_url": "https://www.imdb.com/name/nm0001349/",
                "title_url": null,
                "cast_or_description": "Actress, I Know What You Did Last Summer (1997)"
            },
            {
                "id": "nm0552696",
                "rank": 33151,
                "type": null,
                "year": null,
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/search/top-result` — Top result

Top-Treffer für eine Query (1-best-match).

**Parameters:**
- `query` (query, required, string) — Search text Example: `matrix`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/imdb-api/v1/search/top-result?query=matrix"
```

**Response:**
```json
{
    "data": {
        "query": "matrix",
        "result": {
            "id": "tt0133093",
            "rank": 282,
            "type": "feature",
            "year": 1999,
            "image": {
                "url": "https://m.media-amazon.com/images/M/MV5BN2NmN2VhMTQtMDNiOS00NDlhLTliMjgtODE2ZTY0ODQyNDRhXkEyXkFqcGc@._V1_.jpg",
                "width": 2100,
                "height": 3156
            },
            "title": "The Matrix",
            "type_id": "movie",
            "name_url": null,
            "title_url": "https://www.imdb.com/title/tt0133093/",
            "cast_or_description": "Keanu Reeves, Laurence Fishburne"
        }
    },
    "meta": {
        "timestamp": "2026-05-04T13:59:39.426Z",
        "request_id": "0bc92831-86e8-4456-a941-5bb4d2f8dab4"
    },
    "status": "ok",
    "message": "Top result retrieved successfully",
    "success": true
}
```

#### `GET /v1/search/images` — Search images

Bilder-Suche.

**Parameters:**
- `query` (query, required, string) — Search text Example: `matrix`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/imdb-api/v1/search/images?query=matrix"
```

**Response:**
```json
{
    "data": {
        "count": 7,
        "query": "matrix",
        "images": [
            {
                "id": "tt0133093",
                "image": {
                    "url": "https://m.media-amazon.com/images/M/MV5BN2NmN2VhMTQtMDNiOS00NDlhLTliMjgtODE2ZTY0ODQyNDRhXkEyXkFqcGc@._V1_.jpg",
                    "width": 2100,
                    "height": 3156
                },
                "title": "The Matrix"
            },
            {
                "id": "tt0234215",
                "image": {
                    "url": "https://m.media-amazon.com/images/M/MV5BNjAxYjkxNjktYTU0YS00NjFhLWIyMDEtMzEzMTJjMzRkMzQ1XkEyXkFqcGc@._V1_.jpg",
                    "width": 800,
                    "height": 1200
                },
                "title": "The Matrix Reloaded"
            },
            {
                "id": "tt10838180",
                "image": {
                    "url": "https://m.media-amazon.com/images/M/MV5BMDMyNDIzYzMtZTMyMy00NjUyLWI3Y2MtYzYzOGE1NzQ1MTBiXkEyXkFqcGc@._V1_.jpg",
                    "width": 2764,
                    "height": 4096
                },
                "title": "The Matrix Resurrections"
            },
            {
                "id": "tt0242653",
                "image": {
                    "url": "https://m.media-amazon.com/images/M/MV5BMmNmMTEzODQtNmExMS00OGUxLWFkNTItMTM3NzBlNDk0YWU5XkEyXkFqcGc@._V1_.jpg",
                    "width": 2200,
                    "height": 3251
                },
               
…(truncated, see openapi.json for full schema)
```

### Titles

#### `GET /v1/titles/detail` — Title detail

Detail-Daten zu einem Titel per IMDB-ID (tt…).

**Parameters:**
- `id` (query, required, string) — IMDB title ID Example: `tt0111161`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/imdb-api/v1/titles/detail?id=tt0111161"
```

**Response:**
```json
{
    "data": {
        "id": "tt0111161",
        "rank": 48,
        "type": "feature",
        "year": 1994,
        "image": {
            "url": "https://m.media-amazon.com/images/M/MV5BMDAyY2FhYjctNDc5OS00MDNlLThiMGUtY2UxYWVkNGY2ZjljXkEyXkFqcGc@._V1_.jpg",
            "width": 1200,
            "height": 1800
        },
        "title": "The Shawshank Redemption",
        "type_id": "movie",
        "name_url": null,
        "title_url": "https://www.imdb.com/title/tt0111161/",
        "cast_or_description": "Tim Robbins, Morgan Freeman"
    },
    "meta": {
        "timestamp": "2026-05-04T13:59:39.594Z",
        "request_id": "f5132c1c-23ac-4f47-a1b1-2087d53326c2"
    },
    "status": "ok",
    "message": "Title detail retrieved successfully",
    "success": true
}
```

#### `GET /v1/titles/resolve` — Resolve title

Findet die wahrscheinlichste IMDB-ID zu einem Titel.

**Parameters:**
- `query` (query, required, string) — Title text Example: `shawshank`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/imdb-api/v1/titles/resolve?query=shawshank"
```

**Response:**
```json
{
    "data": {
        "query": "shawshank",
        "title": {
            "id": "tt0111161",
            "rank": 48,
            "type": "feature",
            "year": 1994,
            "image": {
                "url": "https://m.media-amazon.com/images/M/MV5BMDAyY2FhYjctNDc5OS00MDNlLThiMGUtY2UxYWVkNGY2ZjljXkEyXkFqcGc@._V1_.jpg",
                "width": 1200,
                "height": 1800
            },
            "title": "The Shawshank Redemption",
            "type_id": "movie",
            "name_url": null,
            "title_url": "https://www.imdb.com/title/tt0111161/",
            "cast_or_description": "Tim Robbins, Morgan Freeman"
        }
    },
    "meta": {
        "timestamp": "2026-05-04T13:59:39.688Z",
        "request_id": "cde35353-4388-4de8-8bb3-9e67f9326066"
    },
    "status": "ok",
    "message": "Title resolved successfully",
    "success": true
}
```

#### `GET /v1/titles/from-url` — Title from URL

Lädt Titel-Daten aus einer IMDB-Title-URL.

**Parameters:**
- `url` (query, required, string) — IMDB title URL Example: `https://www.imdb.com/title/tt0111161/`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/imdb-api/v1/titles/from-url?url=https%3A%2F%2Fwww.imdb.com%2Ftitle%2Ftt0111161%2F"
```

**Response:**
```json
{
    "data": {
        "id": "tt0111161",
        "rank": 48,
        "type": "feature",
        "year": 1994,
        "image": {
            "url": "https://m.media-amazon.com/images/M/MV5BMDAyY2FhYjctNDc5OS00MDNlLThiMGUtY2UxYWVkNGY2ZjljXkEyXkFqcGc@._V1_.jpg",
            "width": 1200,
            "height": 1800
        },
        "title": "The Shawshank Redemption",
        "type_id": "movie",
        "name_url": null,
        "title_url": "https://www.imdb.com/title/tt0111161/",
        "cast_or_description": "Tim Robbins, Morgan Freeman"
    },
    "meta": {
        "timestamp": "2026-05-04T13:59:39.761Z",
        "request_id": "c4385eb4-b3d3-4899-b2fb-5f48d1003f50"
    },
    "status": "ok",
    "message": "Title retrieved from URL successfully",
    "success": true
}
```

#### `GET /v1/titles/cast-summary` — Cast summary

Top-Cast eines Titels (kompakt).

**Parameters:**
- `id` (query, required, string) — IMDB title ID Example: `tt0111161`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/imdb-api/v1/titles/cast-summary?id=tt0111161"
```

**Response:**
```json
{
    "data": {
        "id": "tt0111161",
        "cast": [
            "Tim Robbins",
            "Morgan Freeman"
        ],
        "count": 2,
        "title": "The Shawshank Redemption"
    },
    "meta": {
        "timestamp": "2026-05-04T13:59:39.832Z",
        "request_id": "c681f55d-7cee-4cba-a24c-f3f67a67570f"
    },
    "status": "ok",
    "message": "Title cast summary retrieved successfully",
    "success": true
}
```

### Names

#### `GET /v1/names/detail` — Name detail

Detail-Daten zu einer Person per IMDB-ID (nm…).

**Parameters:**
- `id` (query, required, string) — IMDB name ID Example: `nm0000182`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/imdb-api/v1/names/detail?id=nm0000182"
```

**Response:**
```json
{
    "data": {
        "id": "nm0000182",
        "rank": 701,
        "type": null,
        "year": null,
        "image": {
            "url": "https://m.media-amazon.com/images/M/MV5BMTY0OTY3ODA3OV5BMl5BanBnXkFtZTcwMzMyMzQ1NQ@@._V1_.jpg",
            "width": 1797,
            "height": 2048
        },
        "title": "Jennifer Lopez",
        "type_id": null,
        "name_url": "https://www.imdb.com/name/nm0000182/",
        "title_url": null,
        "cast_or_description": "Producer, Hustlers (2019)"
    },
    "meta": {
        "timestamp": "2026-05-04T13:59:39.900Z",
        "request_id": "fdcd7388-818f-4e55-9e4c-9eee1e597908"
    },
    "status": "ok",
    "message": "Name detail retrieved successfully",
    "success": true
}
```

#### `GET /v1/names/resolve` — Resolve name

Findet die wahrscheinlichste IMDB-ID zu einer Person.

**Parameters:**
- `query` (query, required, string) — Person name Example: `jlo`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/imdb-api/v1/names/resolve?query=jlo"
```

**Response:**
```json
{
    "data": {
        "name": {
            "id": "nm0000182",
            "rank": 701,
            "type": null,
            "year": null,
            "image": {
                "url": "https://m.media-amazon.com/images/M/MV5BMTY0OTY3ODA3OV5BMl5BanBnXkFtZTcwMzMyMzQ1NQ@@._V1_.jpg",
                "width": 1797,
                "height": 2048
            },
            "title": "Jennifer Lopez",
            "type_id": null,
            "name_url": "https://www.imdb.com/name/nm0000182/",
            "title_url": null,
            "cast_or_description": "Producer, Hustlers (2019)"
        },
        "query": "jlo"
    },
    "meta": {
        "timestamp": "2026-05-04T13:59:40.005Z",
        "request_id": "435138f3-8c1b-421d-b7a3-7fbeddbe5ddc"
    },
    "status": "ok",
    "message": "Name resolved successfully",
    "success": true
}
```

#### `GET /v1/names/from-url` — Name from URL

Lädt Personen-Daten aus einer IMDB-Name-URL.

**Parameters:**
- `url` (query, required, string) — IMDB name URL Example: `https://www.imdb.com/name/nm0000182/`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/imdb-api/v1/names/from-url?url=https%3A%2F%2Fwww.imdb.com%2Fname%2Fnm0000182%2F"
```

**Response:**
```json
{
    "data": {
        "id": "nm0000182",
        "rank": 701,
        "type": null,
        "year": null,
        "image": {
            "url": "https://m.media-amazon.com/images/M/MV5BMTY0OTY3ODA3OV5BMl5BanBnXkFtZTcwMzMyMzQ1NQ@@._V1_.jpg",
            "width": 1797,
            "height": 2048
        },
        "title": "Jennifer Lopez",
        "type_id": null,
        "name_url": "https://www.imdb.com/name/nm0000182/",
        "title_url": null,
        "cast_or_description": "Producer, Hustlers (2019)"
    },
    "meta": {
        "timestamp": "2026-05-04T13:59:40.078Z",
        "request_id": "dabd691e-0388-49bb-bf73-46dd93f432f1"
    },
    "status": "ok",
    "message": "Name retrieved from URL successfully",
    "success": true
}
```

#### `GET /v1/names/known-for` — Known for

Bekannteste Werke einer Person.

**Parameters:**
- `id` (query, required, string) — IMDB name ID Example: `nm0000182`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/imdb-api/v1/names/known-for?id=nm0000182"
```

**Response:**
```json
{
    "data": {
        "id": "nm0000182",
        "name": "Jennifer Lopez",
        "count": 1,
        "known_for": [
            "Hustlers (2019)"
        ],
        "primary_role": "Producer"
    },
    "meta": {
        "timestamp": "2026-05-04T13:59:40.165Z",
        "request_id": "59a51ff9-41fe-45ac-8eb9-b3d519b60fc5"
    },
    "status": "ok",
    "message": "Name known-for summary retrieved successfully",
    "success": true
}
```

### Utils

#### `GET /v1/utils/title-id-from-url` — Title ID from URL

Extrahiert die tt-ID aus einer IMDB-Title-URL.

**Parameters:**
- `url` (query, required, string) — IMDB title URL Example: `https://www.imdb.com/title/tt0111161/`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/imdb-api/v1/utils/title-id-from-url?url=https%3A%2F%2Fwww.imdb.com%2Ftitle%2Ftt0111161%2F"
```

**Response:**
```json
{
    "data": {
        "title_id": "tt0111161"
    },
    "meta": {
        "timestamp": "2026-05-04T13:59:40.244Z",
        "request_id": "b35b0aea-1caf-4bc7-bfc0-aaf918f39e68"
    },
    "status": "ok",
    "message": "Title ID retrieved successfully",
    "success": true
}
```

#### `GET /v1/utils/name-id-from-url` — Name ID from URL

Extrahiert die nm-ID aus einer IMDB-Name-URL.

**Parameters:**
- `url` (query, required, string) — IMDB name URL Example: `https://www.imdb.com/name/nm0000182/`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/imdb-api/v1/utils/name-id-from-url?url=https%3A%2F%2Fwww.imdb.com%2Fname%2Fnm0000182%2F"
```

**Response:**
```json
{
    "data": {
        "name_id": "nm0000182"
    },
    "meta": {
        "timestamp": "2026-05-04T13:59:40.322Z",
        "request_id": "4abe996d-2c3a-4859-b2f8-d22f4aaece29"
    },
    "status": "ok",
    "message": "Name ID retrieved successfully",
    "success": true
}
```

#### `GET /v1/utils/title-url-from-id` — Title URL from ID

Baut die IMDB-URL zu einer Title-ID.

**Parameters:**
- `id` (query, required, string) — IMDB title ID Example: `tt0111161`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/imdb-api/v1/utils/title-url-from-id?id=tt0111161"
```

**Response:**
```json
{
    "data": {
        "title_url": "https://www.imdb.com/title/tt0111161/"
    },
    "meta": {
        "timestamp": "2026-05-04T13:59:40.399Z",
        "request_id": "52827578-32f3-4b39-a095-a02cd808a0de"
    },
    "status": "ok",
    "message": "Title URL retrieved successfully",
    "success": true
}
```

#### `GET /v1/utils/name-url-from-id` — Name URL from ID

Baut die IMDB-URL zu einer Name-ID.

**Parameters:**
- `id` (query, required, string) — IMDB name ID Example: `nm0000182`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/imdb-api/v1/utils/name-url-from-id?id=nm0000182"
```

**Response:**
```json
{
    "data": {
        "name_url": "https://www.imdb.com/name/nm0000182/"
    },
    "meta": {
        "timestamp": "2026-05-04T13:59:40.450Z",
        "request_id": "f70a7ffd-093f-46c4-a060-eb992d80278e"
    },
    "status": "ok",
    "message": "Name URL retrieved successfully",
    "success": true
}
```

#### `GET /v1/utils/id-type` — ID type

Klassifiziert eine IMDB-ID (title oder name).

**Parameters:**
- `id` (query, required, string) — IMDB ID Example: `tt0111161`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/imdb-api/v1/utils/id-type?id=tt0111161"
```

**Response:**
```json
{
    "data": {
        "id": "tt0111161",
        "entity_type": "title"
    },
    "meta": {
        "timestamp": "2026-05-04T13:59:40.501Z",
        "request_id": "40cb3ed2-cb9b-48e0-ad18-84c5291e0f77"
    },
    "status": "ok",
    "message": "ID type retrieved successfully",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/imdb-api
OpenAPI spec: https://www.oanor.com/api/imdb-api/openapi.json