API Objects

IDs & MSIs

MediaHound IDs & Mapped Source IDs.

ID Overview

At MediaHound, we support three different ID styles in the interest of ultimate flexibility. Below, is a breakdown of each:

MHID

The mhid, or "MediaHound ID," is the core ID for the MediaHound space, and is guaranteed to exist. Though most of our endpoints accept all three styles of IDs, the MHID is guaranteed to work across all of them.

The MHID is a string identifier that both uniquely identifies the object in The Entertainment Graph and identifies the object's type. The MHID prefix is the first 5 characters in the MHID and serves to classify the object.

For example, the movie Saving Private Ryan has an MHID of mhmovt8xqWDBFoCiL92HnfA4uYDV8HzPaig8ucgxJEsP. It's MHID prefix is mhmov, which indicates that this object is a Movie. A list of ID prefixes is available on each specific API Object page.

AltId

An altId, or "alternate ID," is a more readable form of an MediaHound's ID. Like an MHID, it leads with a type-specific prefix such as mhmov, but is then followed by a dash-separated human readable name. Typically, this is just the title or name of the item. For example, Saving Private Ryan has an AltId of mhmov-saving-private-ryan. An altId is acceptable everywhere an mhid is accepted.

Aliases

Aliases are convenient placeholder values that are resolved by the API at query-time. For example, mhals-current-user is resolved by the API using the authentication token passed in. The User mhid is then injected in the alias position and the query continues being processed. It should be noted that this means that you must have an authenticated User token before using this particular alias.

MSIs

MSIs, or "Mapped Source IDs," are special IDs that allow a client to work with our API by using IDs of an external source. You can use them in place of normal MHIDs, and you can request to get them in a response using Components. MSIs are acceptable everywhere an ID is accepted.

Syntax

MSIs are made up of three colon-separated parts:

<Source Name> : <Content Type> : <Source-Specific ID>

MSI Parts

PartDescription
Source NameA title cased, zero whitespace String (i.e., "RottenTomatoes" or "IMDB").
Content TypeMay not be required depending on whether the Source has globally unique IDs, but it doesn't hurt to always include it (i.e., "Movie" or "ShowSeries").
Source-Specific IDA UTF-8 String that should match the common ID of the external Source.

Usage

An MSI can be used anywhere an MHID or AltId would be used, when you wish to work in the external Source's ID space.

You can also request one or more MSIs back as Components in addition to the default MHIDs. Some examples of MSI components include:

  • amazonId
  • youtubeId
  • googlePlayId

We support MSIs for all Sources we currently manage. For a full list of the MSIs available to you, please contact us at bark@mediahound.com.

As an example, if you want the iTunes IDs back in your response, you would add itunesId as a Component in your request:

{
"components": [
"itunesId"
]
}

In your JSON response, you would receive a key of itunesId with a value of the iTunes MSI:

{
"content": [{
"object": {
"mhid": "mhmovPeR81SeVnIPqEFsr36NYUqfqHuXzO9lDuQkq72G",
"name": "Gladiator",
"altId": "mhmov-gladiator",
"itunesId": "iTunes:Movie:397380075"
}
}]
}