API Objects

Contributors

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

Recognizing a Contributor Object

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

Contributor Types

ContributorMHID PrefixDescriptionExamples
RealIndividualContributormhricA real person who contributes to pieces of content.George Clooney, Prince, J.K. Rowling, Viola Davis
RealGroupContributormhrgcA real group entity that contributes to pieces of content.Paramount Pictures, The Beatles, Adult Swim
FictionalIndividualContributormhficAn imaginary individual that appears in pieces of content.Batman, Katniss Everdeen, Ziggy Stardust, Hannibal Lector
FictionalGroupContributormhfgcAn imaginary group entity that appears in pieces of content.The Avengers, The Empire, Knights Templar, G.I. Joe, Jesse and the Rippers

Default and Optional Fields

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

The default fields are guaranteed and are returned every time a Contributor 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),
      "primaryName": PRIMARY_NAME_OBJECT,
      "primaryImage": PRIMARY_IMAGE_OBJECT,
      "secondaryImage": SECONDARY_IMAGE_OBJECT,
      "images": IMAGES_ARRAY,
      "contributions": CONTRIBUTIONS_ARRAY,
      "collections": COLLECTIONS_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 object.
nameThe name of the object.
altIdThe alternate ID of the object, to be used for urls.

Primary Name

All Contributor 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 Contributor objects contain an Image sub-object called primaryImage. You can expect this to be the best visual representation of the Contributor. Contributor images typically have consistent aspect ratios. 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 Contributor objects contain an Image sub-object called secondaryImage. You can expect this to be a background image of the Contributor.

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 Contributor objects may contain a list of Image sub-objects called images. This list will contain all images associated with the given Contributor.

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

Contributions

All Contributor objects contain a sub-object array called contributions. This is a list of Media objects representing the things this Contributor has contributed to.

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

Collections

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

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

Followers

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

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

Likers

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

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

Social Metrics

All Contributor objects contain a sub-object called socialMetrics. This is an object that will contain all the general social metrics about the Contributor 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 Contributor object.
followersThe number of Users that currently follow this Contributor object.
collectorsThis object contains different types of Collections and integers representing how many times this Contributor appears in each type.
mentionersThe number of posts that this Contributor object is currently mentioned in.

User Social

All Contributor objects contain a sub-object called userSocial. This is an object that will contain the User specific social metrics about the Contributor 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 Contributor object.
userFollowsSpecifies whether the currently authenticated User currently follows the Contributor object.
userDislikesSpecifies whether the currently authenticated User currently dislikes the Contributor object.
userDefaultCollectionsAn array of Object/Context Pairs where the object is any of the User's default Collections that currently contain the Contributor object.

Contributor Context

When asking for all the Contributors that have contributed to a piece of Media, the response is an array of Object/Context Pairs. The object is the actual Contributor, as described above. The context is an object that contains information about how the specific Contributor relates to the Media object.

Copy
JSON
"context": {
  "sorting": {
    "importance": Integer
  },
  "relationships": [
    {
      "contribution": String,
      "role": String
    }
  ]
}

Property Summary

PropertyDescription
relationshipsAn array of all the type of relationships the Contributor has to the Media. This can contain multiple objects. For example, if an Actor appeared as multiple characters in a Movie, then there would be a new relationship object for each character.
contributionThe type of contribution the Contributor had towards the Media. Common examples are "Director" and "Cast."
roleIf the contribution was of type "Cast", then this would be the name of the character.