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.

{
"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,
},
"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.

"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.

"allMediums": [ String ]

Property Summary

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

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 a launchInfo object 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:

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

Media is not consumable on Source:

"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.

"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.

"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.

"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.

"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.