Developers

Video Data


What would a music video database be without data on music videos? This guide covers how to retreive data from the API on individual music videos.


Note: Before querying video data, you should familiarize yourself with how IMVDb video data structures and conventions:


Read the Video Data Reference


Getting an Individual Video's Data

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

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

Here's an example response:

{
    "id": 121779770452,
    "production_status": "r",
    "song_title": "Blurred Lines",
    "song_slug": "blurred-lines",
    "url": "http://imvdb.com/video/robin-thicke/blurred-lines",
    "multiple_versions": false,
    "version_name": null,
    "version_number": 1,
    "is_imvdb_pick": false,
    "aspect_ratio": null,
    "year": 2013,
    "verified_credits": false,
    "artists": [
        {
            "name": "Robin Thicke",
            "slug": "robin-thicke",
            "url": "http://imvdb.com/n/robin-thicke",
            "discogs_id": 292681
        }
    ],
    "image": {
        "o": "http://images.imvdb.com/video/...",
        "l": "http://images.imvdb.com/video/...",
        "b": "http://images.imvdb.com/video/...",
        "t": "http://images.imvdb.com/video/..."
    }
}

Retreiving More Video Data

To get more data about a video along with your request, you can use the include parameter. For instance, here's a call where we request a video's credits:

https://imvdb.com/api/v1/video/121779770452?include=credits

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

https://imvdb.com/api/v1/video/121779770452?include=credits,bts,countries

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

sources

Retrieves primary and alternative sources for the video.

Example Data:

"sources": [{
    "source": "youtube",
    "source_data": "zwT6DZCQi9k",
    "is_primary": true
},
{
    "source": "vimeo",
    "source_data": 64611906,
    "is_primary": false
}
]}

credits

Retrieves the credits for a video.

Example Data:

"credits": {
    "total_credits": 8,
    "crew": [
        {
            "position_name": "Director",
            "position_code": "dir",
            "entity_name": "Diane Martel",
            "entity_slug": "diane-martel",
            "entity_id": 31567,
            "position_notes": null,
            "position_id": 31567
        },
        {
            "position_name": "Producer",
            "position_code": "prod",
            "entity_name": "David Robertson",
            "entity_slug": "david-robertson",
            "entity_id": 31568,
            "position_notes": null,
            "position_id": 31568
        }
    ],
    "cast": [
        {
            "entity_name": "Robin Thicke",
            "entity_slug": "robin-thicke",
            "entity_id": 58484,
            "cast_roles": [
                "Himself"
            ],
            "position_id": 58484
        }
]}

featured

Retrieves any featured artists for the video's song. This does not include the main artist on the song.

Example Data:

"featured_artists": [{
    "name": "Justin Vernon",
    "slug": "justin-vernon",
    "url": "https://imvdb.com/n/justin-vernon"
}]

popularity

Retrieves basic popularity data about the total number of shares and number of views. These numbers are from IMVDb's multiple source aggregator.

Example Data:

"popularity": {
    "shares_all_time": 1760,
    "views_all_time": 28668
}

bts

Retrieves any behind the scenes videos that we have listed for the video.

Example Data:

"bts": [{
    "type": "video",
    "source": "youtube",
    "source_data": "lIF_pAgwGKE",
    "title": "Big Boi - \"In The A\" ft. Ludacris, T.I. [Official Behind The Scenes]"
}]

Note: Behind the scenes can be external media like an Instagram picture can be added. Check the external media page in the database reference to get an overview of what type of media is collected.

countries

Retrieves countries of production for the video.

Example Data:

 "countries": [{
    "code": "US",
    "name": "United States"
}]