Filters

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

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.

{
  "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:

{
  "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:

{
  "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:

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

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:

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

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

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

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:

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

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:

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

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:

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

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:

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

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:

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

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.

Below is a static list of currently supported Suitabilities:

MPAA Suitabilities

TV Parental Guidance Suitabilities

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:

{
  "filters": {
    "returnType": {
      "$eq": "Movie"
    },
    "suitabilities": {
      "$and": [{ "$gte": "mhtrt-mpaa-approved" }, { "$lte": "mhtrt-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.

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:

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

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:

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

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

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:

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

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:

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

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:

$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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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:

{
  "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):

{
  "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:

{
  "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:

{
  "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:

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