REST API

Explore Endpoint

REST API documentation for the Explore endpoint.

Explore MediaHound Data.

Copy
http
https://api.mediahound.com/1.3/graph/explore?params=PARAMS_JSON

Overview

Explore begins with everything in The Entertainment Graph and you specify Filters to tailor your results. For instance, you might ask, "Show me Movies starring Brad Pitt available on iTunes." Or, "Show me ShowSeries with the Trait Comedy and exclude things in a specific Collection."

We can then add Components to request additional data about each top-level item.

Parameters

PropertyDescription
paramsRequired. An HQL JSON object (see next table).
access_tokenOptional String (see Authentication).

HQL JSON Object

PropertyDescription
filtersRequired object. See Filters.
sortOptional Array. See Sort.
componentsOptional Array. See Components.
pageSizeOptional Integer. See the Paging Info Object.

Example One

Let's walk through the first question asked in the intro: "Show me Movies starring Brad Pitt available on iTunes."

This question is composed of three filter parts:

  • returnType
  • contributors
  • sources

Request

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

In the request, we specify a returnType filter to control the type of Object returned at the top-level. We use a contributors filter to specify that the Content must have Brad Pitt as a Contributor, and a sources filter to specify that it must be available on iTunes.

For more information about Filters and their boolean operators, view the Filters page.

Response

Copy
JSON
{
  "content": [
    {
      "object": {
        "mhid": "mhmovRaNrkroAH6DSGD2I715DiU7JfZzCpLjTUSy94oo",
        "name": "Se7en",
        "altId": "mhmov-se7en",
        "releaseDate": 788918400,
        "description": "A veteran detective and a young cop, played by Morgan Freeman and Brad Pitt, team up to find a cryptic serial killer who is basing each of his murders on the 7 deadly sins."
      },
      "context": {}
    },
    {
      "object": {
        "mhid": "mhmovPRnNOM2w0sValiAbiBeXvEfnATBky4sFiywWVkK",
        "name": "The Departed",
        "altId": "mhmov-the-departed",
        "releaseDate": 1136073600,
        "description": "An young Boston boy is groomed by the mob to infiltrate the police force. At the same time, a policeman is assigned to go undercover to infiltrate the organized crime scene and the two are pitted against each other in a dangerous game of deceit and violence."
      },
      "context": {}
    },
    {
      "object": {
        "mhid": "mhmovrS0pTpvgJa7zLLDYxQxEBsTRGfQPC8rmG7Shn2q",
        "name": "Inglourious Basterds",
        "altId": "mhmov-inglourious-basterds",
        "releaseDate": 1230768000,
        "description": "Quentin Tarantino directs this film set during World War II about two different plans to kill high ranking Nazi party members."
      },
      "context": {}
    },
    {
      "object": {
        "mhid": "mhmov614MS2sSxCi1ZlWpC9y9tjkhpknTN8vZET9YiRr",
        "name": "Snatch",
        "altId": "mhmov-snatch",
        "releaseDate": 946684800,
        "description": "Several characters encounter tensions within London’s dark criminal scene. Director Guy Ritchie weaves in two tales that depict this umbrella story arc, with the first revolving around a stolen diamond, and the second involving bare-knuckle boxing match."
      },
      "context": {}
    },
    {
      "object": {
        "mhid": "mhmovT0v550ui4wnNgzHclSflD14Mwd33KlSXpFkz5SZ",
        "name": "12 Monkeys",
        "altId": "mhmov-twelve-monkeys",
        "releaseDate": 788918400,
        "description": "This sci-fi dystopian story involves a man from 2027 who gets sent back in time to trace the beginnings of a 1996 virus that wiped out almost all of humanity. However, he lands in 1990 where he is placed in an asylum, meeting several key people that are actually connected to the destruction that was about to unfold in six years’ time."
      },
      "context": {}
    },
    {
      "object": {
        "mhid": "mhmovJ0L1bDfARuwOn6PGkz0t9zzCIJHcF20zTjf23mq",
        "name": "12 Years a Slave",
        "altId": "mhmov-12-years-a-slave",
        "releaseDate": 1356998400,
        "description": "Based on the real life biography of Solomon Northup, a free man who is captured and forced into slavery."
      },
      "context": {}
    },
    {
      "object": {
        "mhid": "mhmovYbGC7o81phHeGVAw60WHD77fKO1812ncL26XyLR",
        "name": "The Curious Case of Benjamin Button",
        "altId": "mhmov-the-curious-case-of-benjamin-button",
        "releaseDate": 1199145600,
        "description": "The story of Benjamin Button, a man who suffers from an illness that makes him age backwards."
      },
      "context": {}
    },
    {
      "object": {
        "mhid": "mhmovYf3CfR2bvpIPS4fSe1rqISBclSjbdn1wtBXN0ct",
        "name": "Kick-Ass",
        "altId": "mhmov-kick-ass",
        "releaseDate": 1262304000,
        "description": "An everyday high school student decides to become a superhero, despite having no powers or experience. Before long he joins up with a duo of skilled vigilantes and draws the ire of a major crime boss."
      },
      "context": {}
    },
    {
      "object": {
        "mhid": "mhmovvS1XrZBuxorr7PM3EBwtQLoG9zCv8a2qgjIp4Sv",
        "name": "Moneyball",
        "altId": "mhmov-moneyball",
        "releaseDate": 1293840000,
        "description": "Billy Beane, the general manager of Oakland A, takes the world of baseball by storm when he maneuvers around his excruciatingly limited budget by utilizing computer-generated analysis when building his team."
      },
      "context": {}
    },
    {
      "object": {
        "mhid": "mhmovL7OoArMiwJqwbCZd8v8PxSwaB73jral69t2o0dA",
        "name": "Interview with the Vampire: The Vampire Chronicles",
        "altId": "mhmov-interview-with-the-vampire-the-vampire-chronicles",
        "releaseDate": 757382400,
        "description": "The disillusioned vampire immortal Louis who gets interviewed by a modern-day journalist to whom he tells his sad and morbid tales involving his vampire creator Lestat and their centuries of love-hate existence."
      },
      "context": {}
    }
  ],
  "pagingInfo": {
    "next": "https://dev-api.mediahound.com/1.3/graph/explore/?&params=%7B%22filters%22%3A%7B%22returnType%22%3A%7B%22%24eq%22%3A%22Movie%22%7D%2C%22contributors%22%3A%7B%22%24eq%22%3A%22mhricyGERyNVHKy7BNMIZzXBX9dLOWzT4cWdcC6LPUHp%22%7D%2C%22sources%22%3A%7B%22%24eq%22%3A%22mhsrcRcTZuZn9N3OXfGnEDR8TkfzXG9BT6OIUAqQAXqg%22%7D%7D%2C%22page%22%3A1%7D",
    "previous": null
  }
}

Example Two

Now let's try the second question asked in the intro: "Show me ShowSeries with the Trait Comedy and exclude things in a specific Collection."

This question is composed of three filter parts:

  • returnType
  • traits
  • collections

We'll also add a sort definition to return the items from newest to oldest, and a components array to see a picture for each response item:

Request

Copy
JSON
{
  "filters": {
    "returnType": {
      "$eq": "ShowSeries"
    },
    "traits": {
      "$eq": "mhgnr-comedy"
    },
    "collections": {
      "$ne": "mhcoli0LMqBbiC83aJbusSL4yfBD4RLHo1DzBqE0KeYR"
    }
  },
  "sort": [
    {
      "type": "property",
      "property": "releaseDate",
      "order": "descending"
    }
  ],
  "components": [
    "primaryImage"
  ]
}

Response

Copy
JSON
{
  "content": [
    {
      "object": {
        "mhid": "mhsssROvLRCC2jL0fNYfqca5DY6yr4iWfdwi1Tb9TyeN",
        "name": "Crashing",
        "altId": "mhsss-crashing",
        "releaseDate": 1487462400,
        "primaryImage": {
          "object": {
            "mhid": "mhimgseriesdefaultoriginal",
            "name": "Default Primary Image for Show Series",
            "isDefault": true,
            "original": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultoriginal.jpg",
              "height": 720,
              "width": 1280
            },
            "thumbnail": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultthumbnail.jpg",
              "height": 90,
              "width": 160
            },
            "small": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultsmall.jpg",
              "height": 180,
              "width": 320
            },
            "medium": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultmedium.jpg",
              "height": 360,
              "width": 640
            },
            "large": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultlarge.jpg",
              "height": 720,
              "width": 1280
            }
          },
          "context": {}
        }
      },
      "context": {}
    },
    {
      "object": {
        "mhid": "mhsss0nheAZoDf6DUQ7GG5UlxEa7oBkqnNnRPCWnrSnH",
        "name": "One Day at a Time",
        "altId": "mhsss-one-day-at-a-time-2017",
        "releaseDate": 1483228800,
        "primaryImage": {
          "object": {
            "mhid": "mhimgseriesdefaultoriginal",
            "name": "Default Primary Image for Show Series",
            "isDefault": true,
            "original": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultoriginal.jpg",
              "height": 720,
              "width": 1280
            },
            "thumbnail": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultthumbnail.jpg",
              "height": 90,
              "width": 160
            },
            "small": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultsmall.jpg",
              "height": 180,
              "width": 320
            },
            "medium": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultmedium.jpg",
              "height": 360,
              "width": 640
            },
            "large": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultlarge.jpg",
              "height": 720,
              "width": 1280
            }
          },
          "context": {}
        }
      },
      "context": {}
    },
    {
      "object": {
        "mhid": "mhsssExd7bJjIReNST5Lym4sage09KcLJ0OksCzRHLbV",
        "name": "Strong Woman Do Bong-soon",
        "altId": "mhsss-strong-woman-do-bong-soon",
        "releaseDate": 1483228800,
        "primaryImage": {
          "object": {
            "mhid": "mhimgseriesdefaultoriginal",
            "name": "Default Primary Image for Show Series",
            "isDefault": true,
            "original": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultoriginal.jpg",
              "height": 720,
              "width": 1280
            },
            "thumbnail": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultthumbnail.jpg",
              "height": 90,
              "width": 160
            },
            "small": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultsmall.jpg",
              "height": 180,
              "width": 320
            },
            "medium": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultmedium.jpg",
              "height": 360,
              "width": 640
            },
            "large": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultlarge.jpg",
              "height": 720,
              "width": 1280
            }
          },
          "context": {}
        }
      },
      "context": {}
    },
    {
      "object": {
        "mhid": "mhsssLFycaK3fsg749T8nY1D55K5IPjvATFr4RL0je3f",
        "name": "The President Show",
        "altId": "mhsss-the-president-show",
        "releaseDate": 1483228800,
        "primaryImage": {
          "object": {
            "mhid": "mhimgseriesdefaultoriginal",
            "name": "Default Primary Image for Show Series",
            "isDefault": true,
            "original": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultoriginal.jpg",
              "height": 720,
              "width": 1280
            },
            "thumbnail": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultthumbnail.jpg",
              "height": 90,
              "width": 160
            },
            "small": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultsmall.jpg",
              "height": 180,
              "width": 320
            },
            "medium": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultmedium.jpg",
              "height": 360,
              "width": 640
            },
            "large": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultlarge.jpg",
              "height": 720,
              "width": 1280
            }
          },
          "context": {}
        }
      },
      "context": {}
    },
    {
      "object": {
        "mhid": "mhsssqAB3yIXgmt02nCf1toE3BC8thIlxjc9d0cdjDs3",
        "name": "The Jim Jefferies Show",
        "altId": "mhsss-the-jim-jefferies-show",
        "releaseDate": 1483228800,
        "primaryImage": {
          "object": {
            "mhid": "mhimgseriesdefaultoriginal",
            "name": "Default Primary Image for Show Series",
            "isDefault": true,
            "original": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultoriginal.jpg",
              "height": 720,
              "width": 1280
            },
            "thumbnail": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultthumbnail.jpg",
              "height": 90,
              "width": 160
            },
            "small": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultsmall.jpg",
              "height": 180,
              "width": 320
            },
            "medium": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultmedium.jpg",
              "height": 360,
              "width": 640
            },
            "large": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultlarge.jpg",
              "height": 720,
              "width": 1280
            }
          },
          "context": {}
        }
      },
      "context": {}
    },
    {
      "object": {
        "mhid": "mhssssCH2BaA7YtgxM035XXfFcQLoZEqmBuP0Lo14tYS",
        "name": "Powerless",
        "altId": "mhsss-powerless",
        "releaseDate": 1483228800,
        "primaryImage": {
          "object": {
            "mhid": "mhimgseriesdefaultoriginal",
            "name": "Default Primary Image for Show Series",
            "isDefault": true,
            "original": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultoriginal.jpg",
              "height": 720,
              "width": 1280
            },
            "thumbnail": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultthumbnail.jpg",
              "height": 90,
              "width": 160
            },
            "small": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultsmall.jpg",
              "height": 180,
              "width": 320
            },
            "medium": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultmedium.jpg",
              "height": 360,
              "width": 640
            },
            "large": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultlarge.jpg",
              "height": 720,
              "width": 1280
            }
          },
          "context": {}
        }
      },
      "context": {}
    },
    {
      "object": {
        "mhid": "mhsssy0zN2tHab9MkvaxIWYzQaQSs12w61KpdHkCEqZL",
        "name": "Making History",
        "altId": "mhsss-making-history",
        "releaseDate": 1483228800,
        "primaryImage": {
          "object": {
            "mhid": "mhimgseriesdefaultoriginal",
            "name": "Default Primary Image for Show Series",
            "isDefault": true,
            "original": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultoriginal.jpg",
              "height": 720,
              "width": 1280
            },
            "thumbnail": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultthumbnail.jpg",
              "height": 90,
              "width": 160
            },
            "small": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultsmall.jpg",
              "height": 180,
              "width": 320
            },
            "medium": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultmedium.jpg",
              "height": 360,
              "width": 640
            },
            "large": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultlarge.jpg",
              "height": 720,
              "width": 1280
            }
          },
          "context": {}
        }
      },
      "context": {}
    },
    {
      "object": {
        "mhid": "mhsss1xOOePqvmszcSvtvdibxuPwvPGNR0fncXlw9ksy",
        "name": "The Mick",
        "altId": "mhsss-the-mick",
        "releaseDate": 1477440000,
        "primaryImage": {
          "object": {
            "mhid": "mhimgseriesdefaultoriginal",
            "name": "Default Primary Image for Show Series",
            "isDefault": true,
            "original": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultoriginal.jpg",
              "height": 720,
              "width": 1280
            },
            "thumbnail": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultthumbnail.jpg",
              "height": 90,
              "width": 160
            },
            "small": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultsmall.jpg",
              "height": 180,
              "width": 320
            },
            "medium": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultmedium.jpg",
              "height": 360,
              "width": 640
            },
            "large": {
              "url": "https://images.mediahound.com/default/mhimgseriesdefaultlarge.jpg",
              "height": 720,
              "width": 1280
            }
          },
          "context": {}
        }
      },
      "context": {}
    },
    {
      "object": {
        "mhid": "mhsssnEuTCayqV1Al1UvyKEQShdrHYvLG4Fquwqw4bDy",
        "name": "Insecure",
        "altId": "mhsss-insecure",
        "releaseDate": 1475971200,
        "primaryImage": {
          "object": {
            "mhid": "mhimglov5yZWQubzrnNLMBDENImdA9x3Ulk4b46zkQJP",
            "name": "Insecure 2016",
            "isDefault": false,
            "original": {
              "url": "https://images.mediahound.com/media/mhimglov5yZWQubzrnNLMBDENImdA9x3Ulk4b46zkQJP.jpg",
              "height": 1000,
              "width": 675
            },
            "thumbnail": {
              "url": "https://images.mediahound.com/media/mhimg414DzaoZG3JO11vyKyldyJtSIUJf1tpHJdrZQMr.jpg",
              "height": 133,
              "width": 90
            },
            "small": {
              "url": "https://images.mediahound.com/media/mhimgXXW5PRm9eqVOwfJhGYI3KLt5TkjM8BuRDs9wze2.jpg",
              "height": 266,
              "width": 180
            },
            "medium": {
              "url": "https://images.mediahound.com/media/mhimgIzyuEYMNPkrk5W0lmPhgevUuuNftHwdwudOquEg.jpg",
              "height": 533,
              "width": 360
            },
            "large": {
              "url": "https://images.mediahound.com/media/mhimglov5yZWQubzrnNLMBDENImdA9x3Ulk4b46zkQJP.jpg",
              "height": 1000,
              "width": 675
            }
          },
          "context": {}
        }
      },
      "context": {}
    },
    {
      "object": {
        "mhid": "mhssszCkHS9DulTgXWGz91OeSneSgGi8D9RBZOjZaOnW",
        "name": "Divorce",
        "altId": "mhsss-divorce-2016",
        "releaseDate": 1475971200,
        "primaryImage": {
          "object": {
            "mhid": "mhimgTEHHPggFOR9C19yBl5McFDr2HvHBFpPQT2fz0F6",
            "name": "Divorce 2016",
            "isDefault": false,
            "original": {
              "url": "https://images.mediahound.com/media/mhimgTEHHPggFOR9C19yBl5McFDr2HvHBFpPQT2fz0F6.jpg",
              "height": 1000,
              "width": 675
            },
            "thumbnail": {
              "url": "https://images.mediahound.com/media/mhimguHjjmQyYmhsgquHtD0MmHzgtcJoVRb5aFOzdJr9.jpg",
              "height": 133,
              "width": 90
            },
            "small": {
              "url": "https://images.mediahound.com/media/mhimgkQBfZ9SGPthttzCwHmzY8va48F1GknwAhdbUlLq.jpg",
              "height": 266,
              "width": 180
            },
            "medium": {
              "url": "https://images.mediahound.com/media/mhimgjsEUnWQ9Jyl5q9O97dFUtB1GJx2WfY3RfIIVqJ4.jpg",
              "height": 533,
              "width": 360
            },
            "large": {
              "url": "https://images.mediahound.com/media/mhimgTEHHPggFOR9C19yBl5McFDr2HvHBFpPQT2fz0F6.jpg",
              "height": 1000,
              "width": 675
            }
          },
          "context": {}
        }
      },
      "context": {}
    }
  ],
  "pagingInfo": {
    "next": "https://api.mediahound.com/1.3/graph/explore/?&params=%7B%22filters%22%3A%7B%22returnType%22%3A%7B%22%24eq%22%3A%22ShowSeries%22%7D%2C%22traits%22%3A%7B%22%24eq%22%3A%22mhgnryd5T2aZK1qvgvQNCuPJ3rOa7k6qQwhhqNWjv9qi%22%7D%2C%22collections%22%3A%7B%22%24ne%22%3A%22mhcoli0LMqBbiC83aJbusSL4yfBD4RLHo1DzBqE0KeYR%22%7D%7D%2C%22sort%22%3A%5B%7B%22type%22%3A%22property%22%2C%22property%22%3A%22metadata.releaseDate%22%2C%22order%22%3A%22descending%22%7D%5D%2C%22page%22%3A1%2C%22components%22%3A%5B%7B%22name%22%3A%22primaryImage%22%2C%22components%22%3A%5B%7B%22name%22%3A%22metadata%22%2C%22components%22%3A%5B%5D%7D%5D%7D%2C%7B%22name%22%3A%22metadata%22%2C%22components%22%3A%5B%5D%7D%5D%7D",
    "previous": null
  }
}