API Objects

Media

Media objects are representations of all types of entertainment. They are designed to be compartmentalized and flexible in order to accurately represent multiple types of entertainment.

Recognizing a Media Object

All MediaHound Object Types can be inferred from the first five characters of their MHID or AltID. Here is a list of all Media types in The Entertainment Graph and their corresponding prefix.

Video Types

MediaMHID PrefixDescription
MoviemhmovA feature-length motion picture.
ShowEpisodemhsepA single installment of video content within a sequence of serialized content.
ShowSeasonmhssnA Season belonging to a Show Series.
ShowSeriesmhsssA Show Series (a.k.a., TV Show) representing the entire series.
MusicVideomhmsvA video recording accompanying a song or a song performance.
SpecialmhspcA single installment of unserialized video content.
TrailermhtrlA short promotional video intended to preview the content.

Mixed Types

MediaMHID PrefixDescription
MHGraphGroupmhggpAn unordered list of MHObjects.

Default and Optional Fields

All Media objects are returned with a default set of fields. These fields contain information and properties that relate directly to the essence of the Media object itself.

The default fields are guaranteed and are returned every time a Media object is returned. Everything else may be included by passing in the relevant Component.

Copy
JSON
{
  "content": [{
    "object": {
      "mhid": String (default field),
      "name": String (default field),
      "altId": String (default field),
      "releaseDate": Long (default field),
      "description": String (default field),
      "primaryName": PRIMARY_NAME_OBJECT,
      "primaryImage": PRIMARY_IMAGE_OBJECT,
      "secondaryImage": SECONDARY_IMAGE_OBJECT,
      "images": IMAGES_ARRAY,
      "keyContributors": KEY_CONTRIBUTORS_ARRAY,
      "contributors": CONTRIBUTORS_ARRAY,
      "keySuitabilities": KEY_SUITABILITIES_ARRAY,
      "primaryGroup": PRIMARY_GROUP_OBJECT,
      "keyTraits": KEY_TRAITS_ARRAY,
      "graphGenres" : GRAPH_GENRES_ARRAY,
      "collections": COLLECTIONS_ARRAY,
      "sources": SOURCES_ARRAY,
      "followers": FOLLOWERS_ARRAY,
      "likers": LIKERS_ARRAY,
      "socialMetrics": SOCIAL_METRICS_OBJECT,
      "userSocial": USER_SOCIAL_OBJECT
    },
    "context":{}  
  }],
  "pagingInfo": {
    "next": null,
    "previous": null
  }
}

Default Field Summary

PropertyDescription
mhidThe MediaHound ID of the Media.
nameThe name of the Media.
altIdThe alternate ID of the Media, to be used for urls.
releaseDateThe release date of the Media in Unix time.
descriptionThe description of the Media. For things such as Movies, this would be a synopsis.

Primary Name

All Media objects contain a Name sub-object called primaryName. This contains the primary locale-relevant Name.

The primaryName object is returned whenever a primaryName Component is requested.

Primary Image

All Media objects contain an Image sub-object called primaryImage. You can expect this to be the best visual representation of the piece of content. For example, a movie's primaryImage is likely to be a poster, whereas a book's primaryImage is often its cover. Media images typically have consistent aspect ratios within each media type. Most movies have a 2:3 poster image. Most show series have a 16:9 banner image. However, aspect ratios are not guaranteed, and applications should handle images of all aspect ratios.

The primaryImage object is returned whenever a primaryImage Component is requested. The response object is guaranteed, but may only contain a default image.

Secondary Image

All Media objects contain an Image sub-object called secondaryImage.

The secondaryImage object is returned whenever a secondaryImage Component is requested. The response object is guaranteed, but may only contain a default image.

Images

All Media objects contain a sub-object array called images. This array contains unsorted Images from or about the content.

The images array is returned whenever an images Component is requested. The response array is guaranteed, but may be empty.

Key Contributors

All Media objects contain a sub-object array called keyContributors. This contains Contributors that have been determined to be significant for the Media object. For example, for a Movie, this may be people such as the Director and a few key Cast Members. For a Book, this may be the Author. This array will contain no more than 10 Contributors.

The keyContributors array is returned whenever the keyContributors Component is requested. The response array is guaranteed, but may be empty.

Contributors

All Media objects contain a sub-object array called contributors. This contains all Contributors that have contributed to the content.

The contributors array is returned whenever the contributors Component is requested. The response array is guaranteed, but may be empty.

Key Suitabilities

Some Media objects contain a sub-object called keySuitabilities. This contains Trait objects that specify the suitability rating of the Media object. For example, for a Movie, this may the MPAA rating.

The keySuitabilities array is returned whenever the keySuitabilities Component is requested. The response array is guaranteed, but may be empty.

Primary Group

Some Media objects contain a sub-object called primaryGroup. It refers to the "parent" Media object of the requested Media object. For example, for a ShowEpisode, this would be its ShowSeason. For a Track, as is can appear on multiple Albums, this would be the primary, or original, Album that it appeared on.

The primaryGroup object is returned whenever the primaryGroup Component is requested and the object has a Primary Group.

Key Traits

All Media objects contain a sub-object array called keyTraits. This array contains Trait objects which are considered to be "key", or essential traits for a piece of Content.

The keyTraits array is returned whenever the keyTraits Component is requested. The response array is guaranteed, but may be empty.

Graph Genres

All Media objects contain a sub-object array called graphGenres. This array contains Trait objects. GraphGenres are interesting and unique combinations of different Traits which can offer a fresh view of our Media. As an example: "Vengeance + Betrayal + Against the Odds" which combines three traits from the relevant piece of Media.

The graphGenres array is returned whenever the graphGenres Component is requested. The response array is guaranteed, but may be empty.

Collections

All Media objects contain a sub-object array called collections. This is a list of Collection objects which represents the Collections which contain this Media.

The collections array is returned whenever a collections Component is requested. The response array is guaranteed, but may be empty.

Sources

Some Media objects contain a sub-object array called sources. This array contains sources which the media is currently available on, and which your client has permissions for. For questions about which sources your client key has permissions to, please contact bark@mediahound.com.

The sources array is returned whenever the sources Component is requested. The response array is guaranteed, but may be empty.

Followers

All Media objects contain a sub-object array called followers. This array contains User objects representing Users currently following this Media.

The followers array is returned whenever a followers Component is requested. The response array is guaranteed, but may be empty.

Likers

All Media objects contain a sub-object array called likers. This array contains User objects representing Users who have currently liked this Media.

The likers array is returned whenever a likers Component is requested. The response array is guaranteed, but may be empty.

Social Metrics

All Media objects contain a sub-object called socialMetrics. This is an object that will contain all the general social metrics about the Media object.

The socialMetrics object is guaranteed and will be returned anytime the socialMetrics Component is requested. Additionally, the socialMetrics Component is considered a primitive Component and therefore, is not in an Object/Context Pair.

Copy
JSON
{
  "socialMetrics": {
    "likers": { "all": Integer },
    "followers": { "all": Integer },
    "collectors": {
      "custom": Integer,
      "shoppingCart": Integer,
      "playQueue": Integer,
      "mixList": Integer,
      "interestedList": Integer,
      "consumedList": Integer,
      "wishList": Integer,
      "hiddenList": Integer
    },
    "mentioners": { "all": Integer }
  }
}

Property Summary

PropertyDescription
likersThe number of Users that currently like this Media object.
followersThe number of Users that currently follow this Media object.
collectorsThe number of each type of Collection that this Media object is currently in.
mentionersThe number of posts that this Media object is currently mentioned in.

User Social

All Media objects contain a sub-object called userSocial. This is an object that will contain the User specific social metrics about the Media object.

The userSocial object is only guaranteed when a User has been authenticated with either Code Grant, Implicit Grant, or Password Grant, and will be returned anytime a userSocial Component is requested. Additionally, the userSocial Component is considered a primitive Component and therefore, is not in an Object/Context Pair.

Copy
JSON
{
  "userSocial": {
    "userLikes": Boolean,
    "userFollows": Boolean,
    "userDislikes": Boolean,
    "userDefaultCollections": [
      {
        "object": COLLECTION_OBJECT,
        "context": {}
      }
    ]
  }
}

Property Summary

PropertyDescription
userLikesSpecifies whether the currently authenticated User currently likes the Media object.
userFollowsSpecifies whether the currently authenticated User currently follows the Media object.
userDislikesSpecifies whether the currently authenticated User currently dislikes the Media object.
userDefaultCollectionsAn array of Object/Context Pairs where the object is any of the User's Default Collections that currently contain the Media object, and context is currently empty.