REST API

POST /graph/relate

MediaHound's Recommendation Engine.

POST https://api.mediahound.net/graph/relate

Overview

The Relate endpoint is the entry point to MediaHound's core recommendation and personalization system. Let's break down the steps this system takes for a better understanding of how it forms your recommendations:

We start with Factors to tell the system what we want the recommendations to be based upon. A factor can be a User, Movie or Contributor ID, or all of them combined.
The engine then looks at the combination of Factors provided to determine the best content results.
We can then layer in Filters to tweak the top level results we want.
Finally, we can add additional data about the top-level response by using Components.

HQL JSON Parameters

Property	Description
factors	Required Array. See Factors.
filters	Optional Object. See Filters.
components	Optional Array. See Components.

Example One

Let's say you want recommendations based on two movies, The Gladiator and The Notebook. You could say:

To view this example in action, see datenightmovies.com.

Request

{
  "factors": [
    {
      "id": "mhmov-gladiator"
    },
    {
      "id": "mhmov-the-notebook"
    }
  ],
  "filters": {
    "returnType": {
      "$eq": "Movie"
    }
  }
}

We have combined two Factors of The Notebook and Gladiator and specified via the returnType filter that we want only Movies back (as opposed to ShowSeries, Contributors, etc.).

Response

{
  "content": [
    {
      "object": {
        "mhid": "mhmovsIVyLpEaqomfwVeP89zg1yDIq0ghJzzTbWQ3KdH",
        "name": "Titanic",
        "altId": "mhmov-titanic-1997",
        "releaseDate": 852076800,
        "description": "An elderly woman recounts her perilous journey on the Titanic, and the tragedy that resulted from the infamously sunken vessel. Though she is engaged to a pompous socialite, Rose falls in love with poor stowaway Jack, who opens her eyes to the beauty of life as death surrounds them both."
      },
      "context": {}
    },
    {
      "object": {
        "mhid": "mhmovrdRNaU0J07yE4n87CFzoYjBR6FbQN6jXxxu4D01",
        "name": "Troy",
        "altId": "mhmov-troy",
        "releaseDate": 1072915200,
        "description": "Through a series of scandalous political affairs, the island of Troy is attacked by Greek forces, leaving the fate of battle in the hands of Troy leader Hector and famed Greek warrior Achilles. Loosely adapted from Homer's historical epic The Iliad."
      },
      "context": {}
    },
    {
      "object": {
        "mhid": "mhmovso84LHeiGqUdjr7bNFpFSlaFOhttjhbFRhYQ7ZC",
        "name": "West Side Story",
        "altId": "mhmov-west-side-story",
        "releaseDate": -283996800,
        "description": "Amidst a racial gang war in New York, between the Polish Jets and the Puerto Rican Sharks, a love affair blossoms between Tony and Maria. Though forbidden by all around them, this modern Romeo & Juliet will do anything to maintain their love."
      },
      "context": {}
    },
    {
      "object": {
        "mhid": "mhmovSFETSU8Yo9rSFVWCYjtywo83R4CRjgrjofIogfl",
        "name": "The Last of the Mohicans",
        "altId": "mhmov-the-last-of-the-mohicans-1992",
        "releaseDate": 694224000,
        "description": "A romance between an Indian and the daughter of a British officer threatens the status quo as French and British troops wage war in colonial America."
      },
      "context": {}
    },
    {
      "object": {
        "mhid": "mhmovP4p95l26WI6cyys8mhuKAibvNDyb9O23BGRjtFw",
        "name": "Gone with the Wind",
        "altId": "mhmov-gone-with-the-wind",
        "releaseDate": -978307200,
        "description": "During the American Civil War, a white southern plantation owner’s spirited daughter Scarlett O’Hara weaves in and out of several romantic tangles while experiencing a changing atmosphere in the south due to the war. The epic story is told in two parts, with the first part narrating Scarlett’s travails as she negotiates life and love during the war, while the second part sees her trying to rebuild her family’s once affluent life afterwards."
      },
      "context": {}
    },
    {
      "object": {
        "mhid": "mhmovbiMMh9873Szs3dgH4mYH4KRSwnKARK361ZBrcWh",
        "name": "Atonement",
        "altId": "mhmov-atonement",
        "releaseDate": 1167609600,
        "description": "A 13-year-old aspiring writer accuses her older sister’s lover of a crime he did not commit, thereby altering the course of all their lives."
      },
      "context": {}
    },
    {
      "object": {
        "mhid": "mhmovk1jVUGo4q7fWcuogLReKKyJHZXgcaMgxKpCJCeI",
        "name": "The English Patient",
        "altId": "mhmov-the-english-patient",
        "releaseDate": 820454400,
        "description": "Beginning in the 1930's, the love affair between a young nurse and a badly-burned pilot are told in flashbacks, building to their eventual first encounter."
      },
      "context": {}
    },
    {
      "object": {
        "mhid": "mhmov6le0K3UdUQO6GTYFJDRG00EnyYsCkv7pPJz7O4I",
        "name": "The Godfather",
        "altId": "mhmov-the-godfather",
        "releaseDate": 63072000,
        "description": "A reluctant son is forced to take over the family business from his ailing father in this classic story of organized crime and family values."
      },
      "context": {}
    },
    {
      "object": {
        "mhid": "mhmovdgQiXWJ7JKaeuqSqW5tsdGQnPPid7MGlHuIxNOi",
        "name": "Doctor Zhivago",
        "altId": "mhmov-doctor-zhivago",
        "releaseDate": -157766400,
        "description": "An epic love story set during the Russian Revolution, this film is about a young doctor and his lover who become entangled in a web of passion and lies amidst the fiery political climate of the time."
      },
      "context": {}
    },
    {
      "object": {
        "mhid": "mhmov8pwUYpJ71tbFW3Yn7QTcSlv4qVCq7HPlGuNOYHu",
        "name": "Anna Karenina",
        "altId": "mhmov-anna-karenina-2012",
        "releaseDate": 1325376000,
        "description": "Anna Karenina, a 19th-century Russian aristocrat, can’t help but enter into a scandalous affair with the dashing Count Alexei Vronsky, no matter how it might affect her life."
      },
      "context": {}
    }
  ],
  "pagingInfo": {
    "next": {
      "endpoint": "/relate",
      "method": "POST",
      "body": {
        "factors": [
          {
            "id": "mhmov-gladiator"
          },
          {
            "id": "mhmov-the-notebook"
          }
        ],
        "filters": {
          "returnType": {
            "$eq": "Movie"
          }
        }
        "page": 1
      }
    }
  }
}

Example Two

Example one takes two Movies as Factors. In example two, we'll combine a Movie with a User and inject some weighting. We're going to ask the question: "Show me movies based on this User with a little bit of influence from the Movie RoboCop":

Request

{
  "factors": [
    {
      "id": "mhmov-robocop",
      "weight": 0.5
    },
    {
      "id": "mhusr-exampleuser"
    }
  ],
  "filters": {
    "returnType": {
      "$eq": "Movie"
    }
  }
}

For more on weight, see Factors.

We have weighted RoboCop at half the value of the User "exampleuser" in order to express that the primary driver for this recommendation is the User's taste profile, but we would like to blend that with a little bit of RoboCop's traits.

Response

{
  "content": [
    {
      "object": {
        "mhid": "mhmov6le0K3UdUQO6GTYFJDRG00EnyYsCkv7pPJz7O4I",
        "name": "The Godfather",
        "altId": "mhmov-the-godfather",
        "releaseDate": 63072000,
        "description": "A reluctant son is forced to take over the family business from his ailing father in this classic story of organized crime and family values."
      }
    },
    {
      "object": {
        "mhid": "mhmovOjxSFsYgjcvugVU3tBzSolEbnrij5dkqyc1xh6S",
        "name": "The Dark Knight",
        "altId": "mhmov-the-dark-knight",
        "releaseDate": 1199145600,
        "description": "In the second installment of Christopher Nolan’s Batman trilogy, a brutal and intelligent villain appears in Gotham, leaving chaos and violence in his wake. Batman is forced to toil with his own ideals as he battles his most iconic rival."
      }
    },
    {
      "object": {
        "mhid": "mhmovjxFAKu6B9mx6l3HudC4WMI7fR0hNyCtg6viOsuq",
        "name": "L.A. Confidential",
        "altId": "mhmov-la-confidential",
        "releaseDate": 852076800,
        "description": "Based in 1950s Los Angeles, the police force is filled with corruption giving three different detectives the power to invoke their own brands of justice."
      }
    },
    {
      "object": {
        "mhid": "mhmovim3eHJsv1x2UG1L7WhlvkGyxSLOtR5qgkin5lA5",
        "name": "The Bourne Supremacy",
        "altId": "mhmov-the-bourne-supremacy",
        "releaseDate": 1072915200,
        "description": "An assassination attempt on Jason Bourne’s life thrusts him back into action in order to get to solve the mystery of who is trying to kill him."
      }
    },
    {
      "object": {
        "mhid": "mhmovWIFXoRIgtWTpYkTiumawryPhhGOpQZs7wdcsE5S",
        "name": "Live Free or Die Hard",
        "altId": "mhmov-live-free-or-die-hard",
        "releaseDate": 1167609600,
        "description": "John McClane, the surly detective, is back to help the FBI stop an American terrorist who is threatening national security. This time he’s paired up with young hacker, who unknowingly helped plan the attack."
      }
    },
    {
      "object": {
        "mhid": "mhmovSpp8vJhO2j3HE69HnOXeMbhWdW9HbS3TRztElW0",
        "name": "The Dark Knight Rises",
        "altId": "mhmov-the-dark-knight-rises",
        "releaseDate": 1325376000,
        "description": "This story finds Bruce Wayne eight years after the events of The Dark Knight, now a recluse as he grieves the loss of his girlfriend. When Gotham finds itself taken hostage by a new evil force, Batman must return for the sake of his city."
      }
    },
    {
      "object": {
        "mhid": "mhmovRAPQCwbm0BUajSPhzWlij1u4QyjF3ZeXqJ943M1",
        "name": "The Untouchables",
        "altId": "mhmov-the-untouchables",
        "releaseDate": 536457600,
        "description": "Real life lawman Eliot Ness is looking to put crime boss Al Capone behind bars. In order to do so, he assembles an all star crew of veteran cops, smart bookies, and sharpshooting rookies who share his untainted view on justice."
      }
    },
    {
      "object": {
        "mhid": "mhmovsIVyLpEaqomfwVeP89zg1yDIq0ghJzzTbWQ3KdH",
        "name": "Titanic",
        "altId": "mhmov-titanic-1997",
        "releaseDate": 852076800,
        "description": "An elderly woman recounts her perilous journey on the Titanic, and the tragedy that resulted from the infamously sunken vessel. Though she is engaged to a pompous socialite, Rose falls in love with poor stowaway Jack, who opens her eyes to the beauty of life as death surrounds them both."
      }
    },
    {
      "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."
      }
    },
    {
      "object": {
        "mhid": "mhmov0y5TSX7DBNkK3JjgVxzjyI4MrFOguMShJto5Lmm",
        "name": "Batman Begins",
        "altId": "mhmov-batman-begins",
        "releaseDate": 1104537600,
        "description": "Bruce Wayne abandons the city of Gotham after his parents’ killer walks free. During his travels, Wayne comes across a man who teaches him a particular set of skills that he proceeds to use in an attempt to rid Gotham of crime."
      }
    }
  ],
  "pagingInfo": {
    "next": {
      "endpoint": "/relate",
      "method": "POST",
      "body": {
        "factors": [
          {
            "id": "mhmov-robocop",
            "weight": 0.5
          },
          {
            "id": "mhusr-exampleuser"
          }
        ],
        "filters": {
          "returnType": {
            "$eq": "Movie"
          }
        },
        "page": 1
      }
    }
  }
}