Hound Query Language

Components

Components are how you tailor the response payload to contain the types of details you really need.

components are constructed inside a JSON payload and passed as the POST body. components are accepted by the Relate, Explore, and Lookup endpoints.

Overview

Components are individually requestable objects that are specified as part of an HQL request. They dictate which metadata elements are returned for each top-level response object.

How it fits into the rest of the Hound Query Language

As stated at the top of the page, components are accepted by the Lookup, Relate and Explore endpoints. Below are sample layouts of the JSON as it would be sent to those endpoints, as the query parameter params.

Lookup

When used in a Lookup call, only ids is supported. filters, factors, and sort are not supported in conjunction with components for this endpoint. Therefore, this would be laid out like so:

{
  "ids": IDS_ARRAY,
  "components": COMPONENTS_ARRAY
}

Relate

When used in a Relate call, you would utilize factors and possibly filters to get results in the recommended order, and to filter down the results, respectively. ids is not supported by Relate, as the top-level response is determined by the factors and filters you provide. This would be laid out like so:

{
  "factors": FACTORS_ARRAY,
  "filters": FILTERS_OBJECT,
  "components": COMPONENTS_ARRAY
}

Explore

When used in an Explore call, you might also utilize filters and sort to filter and change the order of the results, respectively. ids is not supported by Explore, as the top-level response is determined by the filters you provide. This would be laid out like so:

{
  "filters": FILTERS_OBJECT,
  "sort": SORT_ARRAY,
  "components": COMPONENTS_ARRAY
}

Top-Level Response

In the simplest case, you supply a list of IDs to the Lookup endpoint, and we give you back some data for each ID. Like this:

{
  "ids": [
    "mhmov-28-days-later",
    "mhmov-american-ultra",
    "mhmov-war-dogs",
    "mhmov-taken-3"
  ],
  "components": ["primaryImage"]
}

In the above example, we've asked for primaryImage and the implicit metadata fields for four Movies, via their altIds. For each ID you requested (up to the default pageSize of 10), we return to you some objects, like so:

{
  "content": [
    {
      "object": {
        "mhid": "mhmov5gKm68VTeNUl3bsEaLz1sspdF0XgpLjtgaubecU",
        "name": "28 Days Later",
        "altId": "mhmov-28-days-later",
        "releaseDate": 1009843200,
        "description": "A young man wakes up alone in the hospital and discovers that London is deserted. Now he must join a small group of survivors in order to find safe haven after an incurable virus ravages the United Kingdom.",
        "primaryImage": IMAGE_OBJECT
      },
      "context": {}
    },
    {
      "object": {
        "mhid": "mhmovkXnJ3mUXv8QVNfCosjSlFcZoiy5WwNuGga6pifl",
        "name": "American Ultra",
        "altId": "mhmov-american-ultra",
        "releaseDate": 1420070400,
        "description": "Jessie Eisenberg stars as Mike, a stoner whose life with his girlfriend Phoebe is turned upside down when he discovers that he is really a highly trained lethal sleeper agent.",
        "primaryImage": IMAGE_OBJECT
      },
      "context": {}
    },
    {
      "object": {
        "mhid": "mhmovD7oNNPQkOlVSwXr35QmUugAp8gq5q0AbR77768g",
        "name": "War Dogs",
        "altId": "mhmov-war-dogs",
        "releaseDate": 1451606400,
        "primaryImage": IMAGE_OBJECT
      },
      "context": {}
    },
    {
      "object": {
        "mhid": "mhmov4BCBVBEKBIF6SKDPPf5bvZLOiAkNgRAbeCsOeWW",
        "name": "Taken 3",
        "altId": "mhmov-taken-3",
        "releaseDate": 1420070400,
        "description": "Liam Neeson returns as Bryan Mills, a former spy who now finds himself accused of his ex-wife's murder. He calls upon his certain set of skills to find the people that are responsible for the crime, in hope of bringing them to justice and clearing his name.",
        "primaryImage": IMAGE_OBJECT
      },
      "context": {}
    }
  ],
  "pagingInfo": {
    "next": null,
    "previous": null
  }
}

View the IMAGE_OBJECT.

As you can see, this returns the default metadata fields for each of the four Movies, as well as each one's Primary Image. This array of Object Context Pairs, which include the metadata fields and the Primary Image objects, is considered the top-level response.

Nesting Components

There are a number of components that allow you to request additional nested components. For example, with the keyContributors component, which returns a Contributor object, you can request components such as each Contributor's primaryImage and their contributions:

Nesting requires the use of the object form of components. The object form supports two fields: name and components.

{
  "ids": ["mhmov-28-days-later", "mhmov-american-ultra"],
  "components": [
    {
      "name": "keyContributors",
      "components": ["primaryImage", "contributions"]
    }
  ]
}

Object Form of `component`

Key	Value
name	A String field for the name of the component being requested.
components	An inner Array that further supports either the short-hand String or Object forms of `component`.

From the example above, we get back a structure containing the keyContributor metadata fields, as well as the Primary Image and a list of Contributions for each Contributor returned, for each Movie.

{
  "content": [
    {
      "object": {
        "mhid": "mhmov5gKm68VTeNUl3bsEaLz1sspdF0XgpLjtgaubecU",
        "name": "28 Days Later",
        "altId": "mhmov-28-days-later",
        "releaseDate": 1009843200,
        "description": "A young man wakes up alone in the hospital and discovers that London is deserted. Now he must join a small group of survivors in order to find safe haven after an incurable virus ravages the United Kingdom.",
        "keyContributors": {
          "content": [
            {
              "object": {
                "mhid": "mhricMljA404oRgFIZCTdIafAUwOlLGVO0V69O23rXu2",
                "name": "Danny Boyle",
                "altId": "mhric-danny-boyle",
                "primaryImage": IMAGE_OBJECT,
                "contributions": {
                  "content": [
                    {
                      "object": {
                        "mhid": "mhmovw2WzjDPJ4fjLjIl3igZZPPiStK4zQAl8u19P4Q8",
                        "name": "Trainspotting",
                        "altId": "mhmov-trainspotting",
                        "releaseDate": 820454400,
                        "description": "Based on the novel by Irving Welsh, the film follows the life of Renton and his friends as they try to exist in Edinburgh as heroin addicts struggling to live a traditional life."
                      },
                      "context": {
                        "fixed": {
                          "position": 0,
                          "positions": [0]
                        }
                      }
                    }
                  ]
                }
              },
              "context": {
                "relationships": [
                  {
                    "contribution": "Director"
                  }
                ]
              }
            }
          ],
          "pagingInfo": {
            "next": null,
            "previous": null
          }
        }
      },
      "context": {}
    },
    {
      "object": {
        "mhid": "mhmovkXnJ3mUXv8QVNfCosjSlFcZoiy5WwNuGga6pifl",
        "name": "American Ultra",
        "altId": "mhmov-american-ultra",
        "releaseDate": 1420070400,
        "description": "Jessie Eisenberg stars as Mike, a stoner whose life with his girlfriend Phoebe is turned upside down when he discovers that he is really a highly trained lethal sleeper agent.",
        "keyContributors": {
          "content": [
            {
              "object": {
                "mhid": "mhricCxPTObdFpUILtVuTQWcTBkULK2emUvQJqNqXgET",
                "name": "Nima Nourizadeh",
                "altId": "mhric-nima-nourizadeh",
                "primaryImage": IMAGE_OBJECT,
                "contributions": {
                  "content": [
                    {
                      "object": {
                        "mhid": "mhmov9t8GpxEXsHNOadKNyFnFSS1EppbFqe5J6fRTQ9F",
                        "name": "Project X",
                        "altId": "mhmov-project-x-2012",
                        "releaseDate": 1325376000,
                        "description": "Three average high school boys decide to throw a party to make themselves popular in their school. However, the party gets elevated to iconic status as various elements--namely a drug dealer, the police and the media-- drop in on the festivities."
                      },
                      "context": {
                        "fixed": {
                          "position": 0,
                          "positions": [0]
                        }
                      }
                    }
                  ],
                  "pagingInfo": {
                    "next": null,
                    "previous": null
                  }
                }
              },
              "context": {
                "relationships": [
                  {
                    "contribution": "Director"
                  }
                ]
              }
            },
            {
              "object": {
                "mhid": "mhricEPEZG5aSmoiLdadXdA5zE36pjVt3jkT2wWn9oQx",
                "name": "Jesse Eisenberg",
                "altId": "mhric-jesse-eisenberg",
                "primaryImage": IMAGE_OBJECT,
                "contributions": {
                  "content": [
                    {
                      "object": {
                        "mhid": "mhsssWeDqks338pX9bn4kPx6GGy3f4qPS6ghLWD738y0",
                        "name": "Top Gear",
                        "altId": "mhsss-top-gear-2002",
                        "releaseDate": 1009843200,
                        "description": "Top Gear is a BAFTA and Emmy award winning British television series about motor vehicles, primarily cars. It began in 1977 as a conventional motoring magazine show. Over time, and especially since a relaunch in 2002, it has developed a quirky, humorous style. The show is currently presented by Jeremy Clarkson, Richard Hammond and James May, and has featured three different test drivers known as The Stig (the first dressed in a black racing outfit, and the second and third dressed in a white one)."
                      },
                      "context": {
                        "fixed": {
                          "position": 0,
                          "positions": [0]
                        }
                      }
                    }
                  ]
                }
              },
              "context": {
                "relationships": [
                  {
                    "contribution": "Cast",
                    "role": "Mike Howell"
                  }
                ]
              }
            },
            {
              "object": {
                "mhid": "mhricCQCM6DTEkPc2tuL1OZxVDzJXc7zZWnxvnZKtYvA",
                "name": "Kristen Stewart",
                "altId": "mhric-kristen-stewart",
                "primaryImage": IMAGE_OBJECT,
                "contributions": {
                  "content": [
                    {
                      "object": {
                        "mhid": "mhmovsuhTdVo3EBCSJCHG03GtVpfiZ0BKRNYbJdLdtrv",
                        "name": "Into the Wild",
                        "altId": "mhmov-into-the-wild",
                        "releaseDate": 1167609600,
                        "description": "This film chronicles the real-life adventures of a man named Christopher McCandless who, after graduating from the university, decides to reject all modern-day trappings, abandon his family and society, and travel to the Alaskan wilderness during the 1990s."
                      },
                      "context": {
                        "fixed": {
                          "position": 0,
                          "positions": [0]
                        }
                      }
                    }
                  ]
                }
              },
              "context": {
                "relationships": [
                  {
                    "contribution": "Cast",
                    "role": "Phoebe Larson"
                  }
                ]
              }
            },
            {
              "object": {
                "mhid": "mhricMWNhaa8Oz6BFJR76cHySlTZnBBzRN1HJQvp0A01",
                "name": "Connie Britton",
                "altId": "mhric-connie-britton-2016",
                "primaryImage": IMAGE_OBJECT,
                "contributions": {
                  "content": [
                    {
                      "object": {
                        "mhid": "mhsssnci2afd35Q6cKJ7DL1Zqy9o0uqYpFb1jaFZk5Or",
                        "name": "Family Guy",
                        "altId": "mhsss-family-guy",
                        "releaseDate": 915148800,
                        "description": "Sick, twisted, politically incorrect and Freakin' Sweet animated series featuring the adventures of the dysfunctional Griffin family. Bumbling Peter and long-suffering Lois have three kids. Stewie (a brilliant but sadistic baby bent on killing his mother and taking over the world), Meg (the oldest, and is the most unpopular girl in town) and Chris (the middle kid, he's not very bright but has a passion for movies). The final member of the family is Brian - a talking dog and much more than a pet, he keeps Stewie in check whilst sipping Martinis and sorting through his own life issues."
                      },
                      "context": {
                        "fixed": {
                          "position": 0,
                          "positions": [0]
                        }
                      }
                    }
                  ]
                }
              },
              "context": {
                "relationships": [
                  {
                    "contribution": "Cast",
                    "role": "Victoria Lasseter"
                  }
                ]
              }
            },
            {
              "object": {
                "mhid": "mhrickHvQw2xHzzbA0qF9sgKfeMXZOj6pA80kLlHoXx6",
                "name": "John Leguizamo",
                "altId": "mhric-john-leguizamo",
                "primaryImage": IMAGE_OBJECT,
                "contributions": {
                  "content": [
                    {
                      "object": {
                        "mhid": "mhmov1R7Q0susyaE5w6GR8xZVpoYBHmq5fkea5rIUpgF",
                        "name": "Carlito's Way",
                        "altId": "mhmov-carlitos-way",
                        "releaseDate": 725846400,
                        "description": "Carlito's Way is a 1993 American crime drama film directed by Brian De Palma, based on the novels Carlito's Way and After Hours by Judge Edwin Torres. The film adaptation was scripted by David Koepp. It stars Al Pacino and Sean Penn, with Penelope Ann Miller, Luis Guzmán, John Leguizamo, and Viggo Mortensen in supporting roles. The film's featured song, \"You Are So Beautiful\", was performed by Joe Cocker.\nThe film follows the life of Carlito Brigante after he is released from prison and vows to go straight and retire. Unable to escape his past, he ends up being dragged into the same criminal activities that got him imprisoned in the first place.\nPenn and Miller received Golden Globe nominations for their performances. A prequel entitled Carlito's Way:  Rise to Power, based on Torres's first novel, was filmed and released in 2005."
                      },
                      "context": {
                        "fixed": {
                          "position": 0,
                          "positions": [0]
                        }
                      }
                    }
                  ]
                }
              },
              "context": {
                "relationships": [
                  {
                    "contribution": "Cast",
                    "role": "Rose"
                  }
                ]
              }
            }
          ],
          "pagingInfo": {
            "next": null,
            "previous": null
          }
        }
      },
      "context": {}
    }
  ],
  "pagingInfo": {
    "next": null,
    "previous": null
  }
}

View the IMAGE_OBJECT.

As you can see, the request payloads can grow quite large as you add components and nested components to your request. It is important to see the components structure as a tool for requesting exactly the data you need, as opposed to just getting a lot of data at once. Adding many components is likely to increase your response time.

The Big List of Components

Below, is an exhaustive list of the supported components per type of API Object.

Guarantees and Defaults

By default, at any tier of the components request structure (including an empty components request), there is an implicit default request. This means that even if you don't fully describe what you want, we will give you some fields to work with. The only guaranteed default fields are mhid and altId, though you are likely to get many others per type. See the individual API Objects for more on which default fields can be expected per type.

Default Components

Name	Description
mhid	The MediaHound ID of the object.
altId	The alternate ID of the object, to be used for urls.

Global Components

These are components which are not bound to a particular type of object, and are therefore globally eligible for request (you can always ask for a primaryImage):

Global Components

Name	Description
primaryImage	MediaHound's first choice for an Image object to display.
secondaryImage	MediaHound's second choice for an Image object to display.

Media Components

These are components which correspond to Media objects (Movies, ShowSeries, etc.):

Media Components

Name	Description
MSIs	Any among the possible Mapped Source IDs.
primaryName	MediaHound's first choice for a locale-relevant Name object.
primaryGroup	A Media object representing the parent Media of this Media (a Series' Season for instance).
keyTraits	Essential Trait objects for this Media.
keyContributors	An array of important Contributor objects for this Media.
contributors	An array of Contributor objects representing who has contributed to this Media.
keySuitabilities	An array of Suitability Trait objects for this Media (i.e., MPAA-PG, MPAA-R, etc.).
images	An array of Image objects associated with this Media.
collections	An array of Collection objects which contain this Media.
sources	An array of Source objects where this Media is currently consumable.

Contributor Components

These are components which correspond to Contributor objects:

Contributor Components

Name	Description
primaryName	MediaHound's first choice for a locale-relevant Name object.
images	An array of Image objects associated with this Contributor.
contributions	An array of Media objects which this Contributor has contributed to.

Source Components

These are components which correspond to Source objects:

Source Components

Name	Description
primaryName	MediaHound's first choice for a locale-relevant Name object.
allSubscriptions	See subscriptions in Source object.
allMediums	See subscriptions in Source object.

Trait Components

These are components which correspond to Trait objects:

Trait Components

Name	Description
primaryName	MediaHound's first choice for a locale-relevant Name object.
images	An array of Image objects associated with this Trait.
traitContent	An array of MediaHound objects which are connected to this Trait.

Components

Overview

How it fits into the rest of the Hound Query Language

Lookup

Relate

Explore

Top-Level Response

Nesting Components

Object Form of component

The Big List of Components

Guarantees and Defaults

Default Components

Global Components

Global Components

Media Components

Media Components

Contributor Components

Contributor Components

Source Components

Source Components

Trait Components

Trait Components

Object Form of `component`