Hound Query Language

Filters

Filters are how you hone in on the results you really care about.

filters are constructed inside a JSON payload and passed as a URL-encoded query parameter called params. filters are accepted by the Relate and Explore endpoints.

Overview

filters function as boolean logic "tests" on potential results, eliminating content that doesn't pass each filter test. A request accepts a Filters Object, which can contain any number of filter tests. Each item in your results must pass all of the filter tests.

Copy
JSON
{
  "filters": {
    FILTER_TYPE (see below): {
      FILTER_BOOLEAN_KEY: FILTER_BOOLEAN_VALUE (see below)
    }
  }
}

Inside of filters, we add a Filter Type, which includes a Filter Boolean Operator key value pair (both of these items will be explained below).

How it fits into the rest of the Hound Query Language

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

Explore

When used in an Explore call, you might also utilize sort and components to change the order of the results, and what metadata you get back, respectively. This would be laid out like so:

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

Relate

When used in a Relate call, you would utilize factors and possibly components to get results in the recommended order, and to control what metadata you get back, respectively. This would be laid out like so:

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

ReturnType

The first thing you probably care about is controlling the "type" of content you're getting back. Let's say you want to see only movies:

Copy
JSON
{
  "filters": {
    "returnType": {
      "$eq": "Movie"
    }
  }
}

As you can see, we add a JSON object called filters. Inside of that, we add a returnType object which has the inner key value pair of "$eq": "Movie". This JSON will give us a Response of ALL movies.

$eq indicates the boolean operation we want to perform (an "equals" comparison), and its value is what each potential Response is compared to.

Return Types

KeysValues
$eq, $inMovie, ShowSeries, Trait, Contributor

We strongly recommend that returnType always be sent in every request. See Boolean Operators for more information.

Traits

The traits filter can augment results by asserting which traits are associated with the results you're getting back. If we wanted to ask for Movies with the trait Comedy, we would write:

Copy
JSON
{
  "filters": {
    "returnType": {
      "$eq": "Movie"
    },
    "traits": {
      "$eq": "mhgnr-comedy"
    }
  }
}

Conversely, if we wanted Movies that explicitly did not have the Comedy trait, we would say:

Copy
JSON
{
  "filters": {
    "returnType": {
      "$eq": "Movie"
    },
    "traits": {
      "$ne": "mhgnr-comedy"
    }
  }
}

traits supports $eq, $ne, $all, $and, $or, $in, and $not Boolean Operators.

TraitsOf

Above, we saw that the traits filter is used to filter results by the presence or absence of particular traits. traitsOf is an inversion of this filter, and is used to filter traits by their connectivity to content, like Movies or ShowSeries. For example, if we wanted to get back the traits that are in both the movie Gladiator, as well as the movie The Notebook, we would say:

Copy
JSON
{
  "filters": {
    "returnType": {
      "$eq": "Trait"
    },
    "traitsOf": {
      "$and": [
        { "$eq": "mhmov-gladiator" },
        { "$eq": "mhmov-the-notebook" }
      ]
    }
  }
}

We have introduced the $and filter here, which says that each inner logical test must evaluate to true in order for the combined test to result to true. This filter returns Traits which are connected to the movie Gladiator AND the movie The Notebook, a.k.a, traits they have in common.

traitsOf supports $eq, $ne, $all, $and, $or, $in, and $not Boolean Operators.

Collections

The collections filter will filter results by testing for the presence in, or absence from, one or more Collections. For example, if we want to simply see the Movies inside a particular Collection, we would say:

Copy
JSON
{
  "filters": {
    "returnType": {
      "$eq": "Movie"
    },
    "collections": {
      "$eq": "mhcollectionexample"
    }
  }
}

collections supports $eq, $ne, $all, $and, $or, $in, and $not Boolean Operators.

Contributors

The contributors filter provides a way to filter results by the contribution of a particular Contributor. For example, to find Movies that Brad Pitt was in, we would say:

Copy
JSON
{
  "filters": {
    "returnType": {
      "$eq": "Movie"
    },
    "contributors": {
      "$eq": "mhric-brad-pitt"
    }
  }
}

contributors supports $eq, $ne, $all, $and, $or, $in, and $not Boolean Operators.

ContributorsOf

The contributorsOf filter inverts contributors, and can be used to filter Contributors by what content they have contributed to. For example, to find Contributors that were in the movie, The Godfather, we would say:

Copy
JSON
{
  "filters": {
    "returnType": {
      "$eq": "Contributor"
    },
    "contributorsOf": {
      "$eq": "mhmov-the-godfather"
    }
  }
}

contributorsOf supports $eq, $ne, $all, $and, $or, $in, and $not Boolean Operators.

Sources

The sources filter can limit results to only those available on particular consumable Sources. For example, to limit Movies to those available on iTunes, we would say:

Copy
JSON
{
  "filters": {
    "returnType": {
      "$eq": "Movie"
    },
    "sources": {
      "$eq": "mhsrc-itunes"
    }
  }
}

sources supports $eq, $ne, $all, $and, $or, $in, and $not Boolean Operators.

SourcesOf

The sourcesOf filter inverts sources, and can be used to filter Sources to those which contain a particular piece of content. For example, to see which sources you can watch The Godfather on, we would say:

Copy
JSON
{
  "filters": {
    "returnType": {
      "$eq": "Source"
    },
    "sourcesOf": {
      "$eq": "mhmov-the-godfather"
    }
  }
}

sourcesOf supports $eq, $ne, $all, $and, $or, $in, and $not Boolean Operators.

Likers

The likers filter limits results to those liked by Users. For example, to limit results to Movies liked by a User with the User MHID of mhusr-joe, we would say:

Copy
JSON
{
  "filters": {
    "returnType": {
      "$eq": "Movie"
    },
    "likers": {
      "$eq": "mhusr-joe"
    }
  }
}

likers supports $eq, $ne, $all, $and, $or, $in, and $not Boolean Operators.

LikersOf

The likersOf filter inverts the likers filter, and can be used to filter Users to only those who have liked a particular piece of Content. For example, to see Users who have liked the movie, The Godfather, we would say:

Copy
JSON
{
  "filters": {
    "returnType": {
      "$eq": "User"
    },
    "likersOf": {
      "$eq": "mhmov-the-godfather"
    }
  }
}

likersOf supports $eq, $ne, $all, $and, $or, $in, and $not Boolean Operators.

Followers

The followers filter limits results to those followed by Users. For example, to limit results to Movies followed by a User with the User MHID of mhusr-joe, we would say:

Copy
JSON
{
  "filters": {
    "returnType": {
      "$eq": "Movie"
    },
    "followers": {
      "$eq": "mhusr-joe"
    }
  }
}

followers supports $eq, $ne, $all, $and, $or, $in, and $not Boolean Operators.

FollowersOf

The likersOf filter inverts the likers filter, and can be used to filter Users to only those who have liked a particular piece of Content. For example, to see Users who have followed the movie, The Godfather, we would say:

Copy
JSON
{
  "filters": {
    "returnType": {
      "$eq": "User"
    },
    "followersOf": {
      "$eq": "mhmov-the-godfather"
    }
  }
}

followersOf supports $eq, $ne, $all, $and, $or, $in, and $not Boolean Operators.

Suitabilities

The suitabilities filter is a way to limit your results to be age appropriate for your audience. Suitabilities are either MPAA, or TV ratings such as MPAA PG-13 or TV-MA.

Suitabilities are in ascending order by approved audience, for comparability. For instance, MPAA G < MPAA PG-13. TV-MA > TV-Y7.

Below is a static list of currently supported Suitabilities:

MPAA Suitabilities

Suitability AltIdSuitability Rating
mhstb-mpaa-approvedMPAA Approved
mhstb-mpaa-gMPAA G
mhstb-mpaa-pgMPAA PG
mhstb-mpaa-pg-13MPAA PG-13
mhstb-mpaa-rMPAA R
mhstb-mpaa-xMPAA X
mhstb-mpaa-nc-17MPAA NC-17
mhstb-mpaa-urMPAA Unrated
mhstb-mpaa-nrNot Rated (pre-dates MPAA)

TV Parental Guidance Suitabilities

Suitability AltIdSuitability Rating
mhstb-tvpg-tv-yTV-Y
mhstb-tvpg-tv-y7TV-Y7
mhstb-tvpg-tv-gTV-G
mhstb-tvpg-tv-pgTV-PG
mhstb-tvpg-tv-14TV-14
mhstb-tvpg-tv-maTV-MA

MPAA and TV ratings should not be combined in a comparison. Some content doesn't have MPAA ratings, while other content does not have TV ratings. Comparing them could render results beyond your intended range.

If a Suitabilities filter is used, content which has no Suitability rating will be automatically excluded from your results since we cannot guarantee it falls within your specified filter range. This prevents us from returning content that may be inappropriate.

For example, let's say we want to specify a range of MPAA Suitabilities appropriate for children. We might want to filter results to those between and including MPAA Approved and MPAA PG:

Copy
JSON
{
  "filters": {
    "returnType": {
      "$eq": "Movie"
    },
    "suitabilities": {
      "$and": [
        { "$gte": "mhstb-mpaa-approved" },
        { "$lte": "mhstb-mpaa-pg" }
      ]
    }
  }
}

This effectively states, "Show me Movies with Suitabilities greater than or equal to Approved, and less than or equal to PG." Results can then be expected to have either Approved, G, or PG ratings. Any content for which we do not have an MPAA rating is automatically excluded.

suitabilities supports all Boolean Operators.

RestrictTo

restrictTo is an ID property filter, which means that it accepts IDs, and treats the filter as an ID property test. To limit your results to some adhoc set (instead of, say, creating a Collection and filtering by its contents), you could create a restrictTo $in filter. Like so:

Copy
JSON
{
  "filters": {
    "restrictTo": {
      "$in": [
        "mhmov-gladiator",
        "mhmov-the-notebook"
      ]
    }
  }
}

The above request says, "Show me results restricted to items that have an AltId of mhmov-gladiator OR an AltId of mhmov-the-notebook." If an item matches either of these cases, it is returned.

restrictTo supports $eq, $ne, $all, $and, $or, $in, and $not Boolean Operators. However, because our content cannot have more than one ID specified, $all requests or $and requests with all $eq values are illogical. You can request them anyway, but you'll get back no results!

Exclude

exclude is a convenience filter to hide Content from your results. To be more specific, it is effectively an implicit NOT around the restrictTo filter. This is important because it's easy to get your boolean logic mixed up, and then you might be confused about why things aren't being excluded from your results. The basic way you filter out a set of content from your results is like so:

Copy
JSON
{
  "filters": {
    "exclude": {
      "$in": [
        "mhmov-gladiator",
        "mhmov-the-notebook"
      ]
    }
  }
}

exclude supports $eq, $ne, $all, $and, $or, $in, and $not Boolean Operators.

Rating

The rating filter is a mechanism for controlling the quality of the content you're seeing. Currently, we support several RottenTomatoes filter types:

Rotten Tomatoes Filter Types

Rating TypeAcceptable Values
RottenTomatoes.criticsScoreA float between 0 and 1
RottenTomatoes.criticsAverageRatingA float between 0 and 10
RottenTomatoes.audienceScoreAn Integer between 0 and 100
RottenTomatoes.audienceAverageRatingA float between 0 and 5

The RottenTomatoes rating type is indicated as an extra field inside the rating filter object. As an example, to filter results to those with a RottenTomatoes Critics Score greater than or equal to 0.8 (80%), we would say:

Copy
JSON
{
  "filters": {
    "returnType": {
      "$eq": "Movie"
    },
    "rating": {
      "$gte": 0.8,
      "type": "RottenTomatoes.criticsScore"
    }
  }
}

rating supports all Boolean Operators.

Year

The year filter is a way to filter Content by the year it was released. This filter accepts Integers for the year values. To find Movies released since 2000, we would say:

Copy
JSON
{
  "filters": {
    "returnType": {
      "$eq": "Movie"
    },
    "year": {
      "$gte": 2000
    }
  }
}

year supports all Boolean Operators.

Boolean Operators

In the examples above, you've seen a few different operators that are supported by the language. Each Filter Type also notes the supported boolean operators.

Below is a full breakdown of all possible operators and how they behave:

Boolean operators are distinguished by their "quot; prefix.

$eq

$eq, or "equal," accepts a single value, and asserts that something is equal to the value on the right hand side (i.e., to assert that a piece of content has an ID equal to mhmov-gladiator):

Copy
JSON
{
  "restrictTo": {
    "$eq": "mhmov-gladiator"
  }
}

$ne

$ne, or "not equal," accepts a single value, and asserts that something is NOT equal to the value on the right hand side (i.e., to assert that a piece of content DOES NOT have an ID equal to mhmov-gladiator):

Copy
JSON
{
  "restrictTo": {
    "$ne": "mhmov-gladiator"
  }
}

$lt

$lt, or "less than," accepts a single value, and asserts that something is less than the value on the right hand side (i.e., to assert that something was released prior to 1999):

Copy
JSON
{
  "year": {
    "$lt": 1999
  }
}

$lte

$lte, or "less than equal," accepts a single value, and asserts that something is less than or equal to the value on the right hand side (i.e., to assert that something was released prior to or in 1999):

Copy
JSON
{
  "year": {
    "$lte": 1999
  }
}

$gt

$gt, or "greater than," accepts a single value, and asserts that something is greater than the value on the right hand side (i.e., to assert that something was released after 1999):

Copy
JSON
{
  "year": {
    "$gt": 1999
  }
}

$gte

$gte, or "greater than equal," accepts a single value, and asserts that something is greater than or equal to the value on the right hand side (i.e., to assert that something was released after or in 1999):

Copy
JSON
{
  "year": {
    "$gte": 1999
  }
}

$and

$and, or "and," accepts an array of objects, and asserts that all inner operators evaluate to true (i.e., to assert that something is available on Google Play and Amazon Instant Video):

Copy
JSON
{
  "sources": {
    "$and": [
      { "$eq": "mhsrc-googleplay" },
      { "$eq": "mhsrc-amazoninstantvideo" }
    ]
  }
}

$all

$all, or "all," accepts an array of Strings. It is a shorthand form of $and, where every comparison is an $eq.

For example, we can rewrite the $and example above to:

Copy
JSON
{
  "sources": {
    "$all": [
      "mhsrc-googleplay",
      "mhsrc-amazoninstantvideo"
    ]
  }
}

$or

$or, or "or," accepts an array of objects, and asserts that at least one of multiple inner operators must evaluate to true (i.e., to assert that something is available on either Google Play or Amazon Instant Video):

Copy
JSON
{
  "sources": {
    "$or": [
      { "$eq": "mhsrc-googleplay" },
      { "$eq": "mhsrc-amazoninstantvideo" }
    ]
  }
}

$in

$in, or "in," accepts an array of Strings. It is a shorthand form of $or, where every comparison is an $eq.

For example, we can rewrite the $or example above to:

Copy
JSON
{
  "sources": {
    "$in": [
      "mhsrc-googleplay",
      "mhsrc-amazoninstantvideo"
    ]
  }
}

$not

$not, or "not," can be wrapped around any other boolean operator. $not will be treated as a boolean NOT, where the contained operation will be inverted, following De Morgan's Law. It's honestly pretty easy to get this confused, so we would advise only using this if you really understand your boolean algebra. As an example:

Copy
JSON
{
  "sources": {
    "$not": {
      "$and": [
        { "$eq": "mhsrc-googleplay" },
        { "$eq": "mhsrc-amazoninstantvideo" }
      ]
    }
  }
}

If the original boolean algebra was ¬(A∧B), then that can be rearranged as (¬A∨¬B). This query is internally reduced to:

Copy
JSON
{
  "sources": {
    "$or": [
      { "$ne": "mhsrc-googleplay" },
      { "$ne": "mhsrc-amazoninstantvideo" }
    ]
  }
}