Entity Data

An entity is anything with a name in the IMVDb Database (artists, companies, people, etc). You can retreive basic information on an entity as well as information like credits and associated videos.

Getting A Single Entity's Info

The endpoint for getting a single video's data looks like this:

https://imvdb.com/api/v1/entity/{entity-id}

A sample response looks like this:

{
    "id": 634,
    "name": "Michel Gondry",
    "slug": "michel-gondry",
    "url": "http://imvdb.dev/n/michel-gondry",
    "discogs_id": 347688,
    "byline": "Director",
    "distinct_positions": [
        {
            "hits": 32,
            "position_code": "dir",
            "positon_name": "Director"
        }
    ],
    "bio": null,
    "image": null,
    "artist_video_count": 0,
    "featured_video_count": 0
}

You can also retrieve an entity's data with the entity slug, although an entity's slug is not a primary key and may change. You need to incude a parameter to tell the API to look for a slug since a slug may be numerical itself.

https://imvdb.com/api/v1/entity/{entity-slug}?method=slug

Retreiving More Video Data

In addition to basic data, you can retrieve extra data with your entity request with the include parameter:

https://imvdb.com/api/v1/entity/634?include=credits

Multiple categories of data be requested by combining them with commas:

https://imvdb.com/api/v1/entity/634?include=credits,distinctpos

Below you'll find a list of all the possible include values as well as example data. Note that the example data is part of the main entity response that is detailed above.

credits

Retrieves all the credits for an entity, including a basic data return for the video.

"credits": [
{
    "position_name": "Director",
    "position_code": "dir",
    "position_notes": null,
    "video": {
        "id": 284753777914,
        "production_status": "r",
        "song_title": "How Are You Doing?",
        "song_slug": "how-are-you-doing",
        "url": "http://imvdb.dev/video/living-sisters/how-are-you-doing",
        "multiple_versions": false,
        "version_name": null,
        "version_number": 1,
        "is_imvdb_pick": false,
        "aspect_ratio": null,
        "year": 2011,
        "verified_credits": false,
        "artists": [
            {
                "name": "Living Sisters",
                "slug": "living-sisters",
                "url": "http://imvdb.dev/n/living-sisters"
            }
        ],
        "image": {
            "o": "https://s3.amazonaws.com/images.imvdb.com/video/{...}.jpg",
            "l": "https://s3.amazonaws.com/images.imvdb.com/video/{...}.jpg",
            "b": "https://s3.amazonaws.com/images.imvdb.com/video/{...}.jpg",
            "t": "https://s3.amazonaws.com/images.imvdb.com/video/{...}.jpg"
        }
    }
}]

credit_summary

Provides a summary of each position an entity is credited with in the database as well as the number of times the entitiy is credited.

Example Data:

"credit_summary": [{
    "hits": 32,
    "position_code": "dir",
    "positon_name": "Director"
}]

artist_videos

Returns videos that the entity is the primary artist for.

"artist_videos": {
"total_videos": 32,
"videos": [
    {
        "id": 159854750492,
        "production_status": "r",
        "song_title": "Under Attack",
        "song_slug": "under-attack",
        "url": "http://imvdb.dev/video/abba/under-attack",
        "multiple_versions": false,
        "version_name": null,
        "version_number": 1,
        "is_imvdb_pick": false,
        "aspect_ratio": null,
        "year": 1982,
        "verified_credits": false,
        "artists": [
            {
                "name": "Abba",
                "slug": "abba",
                "url": "http://imvdb.dev/n/abba"
            }
        ],
        "image": {
            "o": "https://s3.amazonaws.com/images.imvdb.com/video/{..}.jpg",
            "l": "https://s3.amazonaws.com/images.imvdb.com/video/{..}.jpg",
            "b": "https://s3.amazonaws.com/images.imvdb.com/video/{..}.jpg",
            "t": "https://s3.amazonaws.com/images.imvdb.com/video/{..}.jpg"
        }
    }
}]

featured_videos

Identical to artist_videos, but returns videos that the entity is the featured artist on.