API Objects

Sources

Source objects are representations of non-MediaHound services that we have linked to their corresponding MediaHound objects. Examples of these would be HBO, Netflix, IMDb, and RottenTomatoes.

Recognizing a Source Object

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

Source Types

SourceMHID PrefixDescriptionExamples
SourcemhsrcA third-party provider of content or information about content.IMDB, Netflix, iTunes, Fandango

Default and Optional Fields

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

The default fields are guaranteed and are returned every time a Source 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),
      "connectable": Long (default field),
      "webUrl": String (default field),
      "primaryName": PRIMARY_NAME_OBJECT,
      "primaryImage":  PRIMARY_IMAGE_OBJECT,
      "secondaryImage": SECONDARY_IMAGE_OBJECT,
      "allSubscriptions": ALL_SUBSCRIPTION_ARRAY,
      "allMediums": ALL_MEDIUMS_ARRAY,
      "socialMetrics": SOCIAL_METRICS_OBJECT,
      "userSocial": USER_SOCIAL_OBJECT
    },
    "context": CONTEXT_OBJECT (see below)
  }],
  "pagingInfo": {
    "next": null,
    "previous": null
  }
}

Default Field Summary

PropertyDescription
mhidThe MediaHound ID of the Source.
nameThe name of the Source.
altIdThe alternate ID of the Source, to be used for urls.
connectableIndicates if a User has the ability to connect to this Source and indicate preferences about it.
webUrlThe url that links to the Source's outside site.

Primary Name

All Source 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 Source objects contain a sub-object called primaryImage. You can expect this to be the best visual representation of the Source.

The primaryImage will return an Image object.

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 Source objects contain a sub-object called secondaryImage. You can expect this to be an icon image of the piece of content.

The secondaryImage will return and Image object.

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

All Subscriptions

Some Source objects contain a sub-object called allSubscriptions. This contains information about the various subscriptions that are offered by the Source (i.e., "Stream").

The allSubscriptions object is returned as an array of Object/Context Pairs. The object will be the actual Subscription and the context will be empty. Subscription Objects are not retrievable by themselves and are only viewed in reference to a Source.

The allSubscriptions object is not guaranteed, but is returned anytime the allSubscriptions Component is requested. It may contain only an empty array.

Copy
JSON
"allSubscriptions": [
  "object": {
    "metadata": {
      "mhid": String,
      "name": String,
      "description": String,
      "timePeriod": String,
      "price": Double,
      "currency": String,
      "mediums": [ String ]
    }
  },
  "context": {}
]

Property Summary

PropertyDescription
mhidThe MediaHound ID of the Subscription.
nameThe name of the Subscription.
descriptionThe description of the Subscription.
timePeriodThe time period of the Subscription plan, such as "monthly" or "yearly."
priceThe current price of the Subscription plan.
currencyThe currency that the price is in, usually "USD."
mediumsAn array of strings that indicate the various mediums the Subscription allows Media to be delivered in, such as "stream" or "download."

All Mediums

All Source objects contain a sub-object called allMediums. It is an array of all the possible mediums that are offered by the Source. Examples would be "stream" or "download."

The allMediums object is returned whenever an allMediums Component is requested.

Copy
JSON
"allMediums": [ String ]

Property Summary

PropertyDescription
allMediumsAn array of all the possible mediums that are offered by the Source (i.e., "stream" or "download").

Social Metrics

All Source objects contain a sub-object called socialMetrics. This is an object that will contain all the general social metrics about the Source 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 Source object.
followersThe number of Users that currently follow this Source object.
collectorsThe number of each type of Collection that this Source object is currently in.
mentionersThe number of posts that this Source object is currently mentioned in.

User Social

All Source objects contain a sub-object called userSocial. This is an object that will contain the User specific social metrics about the Source 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 when a userSocial Component is requested.

Copy
JSON
"userSocial": {
  "userConnected": Boolean,
  "userPreference": String
}

Property Summary

PropertyDescription
userConnectedSpecifies whether the currently authenticated User currently has connected to the Source object.
userPreferenceSpecifies the level of preference the currently authenticated User has for the Source object.

Context

If a Media object is available to be consumed by a User from a Source, the context object will simply be the mediums object. However, for Sources such as IMDb, where there is no real way to consume the Media, the context object may contain launchInfo and social objects with some basic properties about the Media on the Source.

When asking for the Sources that a particular Media object is available on, the response is an array of Object/Context Pairs. The object is the actual Source, as described above. The context is a complex nested object that aims to give as much information as possible in a manner that is consistent across all Sources.

Note that everything inside context is not configurable via Components. It is assembled automatically with the most data the API can provide.

Media is consumable on Source:

Copy
JSON
"context": {
  "mediums": MEDIUMS_OBJECT (see next section)
}

Media is not consumable on Source:

Copy
JSON
"context": {
  launchInfo: LAUNCH_INFO_OBJECT (see below)
}

Mediums

The mediums property is an array of Medium objects, each containing information for a specific medium, or manner in which a Source delivers content to a consumer.

Copy
JSON
"mediums": [
  {
    "type": String
    "methods": METHODS_OBJECT (see next section)
  }
]

Property Summary

PropertyDescription
typeThe type of medium. Current values are download, stream, deliver, and pickup.
methodsThe Methods object as described below.

Methods

The methods property is an array of Method objects, each containing information for a specific method, or pricing plan, that the Source allows a consumer to consume the content.

Copy
JSON
"methods": [
  {
    "type": String,
    "formats": FORMAT_OBJECT (see next section)
  }
]

Property Summary

PropertyDescription
typeThe type of method. Current values are rent, purchase, subscription, and adSupported.
formatsThe Formats object as described below.

Formats

The formats property is an array of Format objects, each containing specific pricing information for individual formats, as well as launchInfo for that respective format.

Copy
JSON
"formats": [
  {
    "type": String,
    "price": Double,
    "currency": String,
    "launchInfo": LAUNCH_INFO_OBJECT (see next section)
  }
]

Property Summary

PropertyDescription
typeThe type of the format, such as "480p" or "720p" for video formats.
priceThe price of the content in the format.
currencyThe currency of the price, usually "USD."
launchInfoThe Launch Info object of the specific format, described below.

Launch Info

The smallest and most basic part of the Source Context is the launchInfo object. It contains the Source's ID for the specified Media, as well as direct links to the Media on a Source's site.

The links are not guaranteed to exist, so the fallback should always be to the sourceId.

Copy
JSON
"launchInfo": {
  "sourceId": String,
  "view": {
    "http": String,
    "ios": String,
    "android": String
  },
  "consume": {
    "http": String,
    "ios": String,
    "android": String
  },
  "preview": {
    "http": String,
    "ios": String,
    "android": String
  }
}

Property Summary

PropertyDescription
httpThe web link to go to the Media.
iosThe iOS mobile link to go directly to the content, without having to open an embedded web view.
androidThe Android mobile link to go directly to the content, without having to open an embedded web view.
viewA collection of links to simply view the content.
consumeA collection of links to directly consume the content.
previewA collection of links to only preview the content.
sourceIdA String representation of the ID of the content on the Source's domain. If using the Source's SDK, this could be used instead of the links.