Core Concepts

Getting Started

A high-level walkthrough of The Entertainment Graph®.

Welcome to The Entertainment Graph, built by MediaHound.

We bring together all movies, books, games, music, and TV as well as the people and concepts that connect that content. The result is an incredibly meaningful web of context and discovery that can power a great variety of products and experiences.

You will find a high-level diagram of some of the relationships and objects in The Entertainment Graph below. For more details on the company behind The Entertainment Graph, visit MediaHound.com.

Movie Relationships

Try MediaHound

Check out try.mediahound.com if you'd like to explore what our API can do in an intuitive playground before you start building an app.

This Guide

To get started, let's:

  • Create an Application.
  • Get a Client SDK (optional).
  • Authenticate that Application with MediaHound.
  • Start exploring The Entertainment Graph using the MediaHound API.

Creating an App

Let's start by creating an app. Head over to My Apps. From there, you will need to either create a new MediaHound user account or login with your existing one. Once logged in, you can click the Create an App button. Fill out all the details for your application, upload a square image as your app icon, and click Create.

Your app will be created and you will be provided a Client ID and Client Secret. You will need these later when you start making MediaHound API calls.

With the free tier, your user account can create 1 app. By upgrading to a paid tier, you can create multiple apps.

Get a Client SDK

If you are creating a JavaScript Node app/server, or a JavaScript web app, we have Client SDKs that will make interacting with the MediaHound API a breeze. If you are developing for a different platform or don't want to use an SDK, you can directly interact with the REST API.

Authentication

Before you can start using The Entertainment Graph, you need to authenticate. There are multiple types of authentication, which are covered in detail in the Authentication Guide. We will discuss the options briefly now.

Client Credentials OAuth

If the app you are building has no concept of User accounts, then you can use the Client Credentials OAuth grant. You will use your Client ID and Client Secret to authenticate. This is perfect for data visualizations, simple games, or apps that do not have a login.

Copy
bash
curl -X POST -vu YOUR_CLIENT_ID:YOUR_CLIENT_SECRET https://api.mediahound.com/1.3/security/oauth/token -H "Accept: application/json" -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

User OAuth

Does your app have Users? Do you want to generate personalized recommendations? You'll need to use one of the User authentication flows (See Authentication for more information). For these apps, you will authenticate with your Client ID and Client Secret along with the User's credentials. You won't have to ask for a User's username and password, though. You will just need to open a browser window to a specific URL. The User will login, and after they do, you'll receive permission to make API calls on their behalf.

Search for a Movie

Now we can get to the fun stuff. The Entertainment Graph is filled with content of all different types: movies, TV shows, music, etc. We provide Universal Search across all of this content. To keep our results simple for this example, let's use the MediaHound API to search for one movie:

Request

Copy
bash
curl https://api.mediahound.com/1.3/search/all/Gladiator?types=Movie

Discover what else you can do with Search.

Response

We searched for the string, "Gladiator," and filtered the results to movies. Gladiator (2000) is returned as we would expect:

Copy
JSON
{
  "content": [
    {
      "object": {
        "mhid": "mhmovPeR81SeVnIPqEFsr36NYUqfqHuXzO9lDuQkq72G",
        "name": "Gladiator",
        "altId": "mhmov-gladiator",
        "releaseDate": 946684800,
        "description": "A disgraced Roman general, played by Russell Crowe, is forced to fight in the iconic Coliseum as a gladiator for the entertainment of the people, and the man responsible for his downfall.",
        "primaryImage": {
          "object": {
            "mhid": "mhimgGttJE3CaxHXF7rD5aiCOj5hXrHgNMLcutexcBpU",
            "name": "Gladiator 2000",
            "isDefault": false,
            "original": {
              "url": "https://images.mediahound.com/media/mhimgGttJE3CaxHXF7rD5aiCOj5hXrHgNMLcutexcBpU.jpg",
              "height": 1500,
              "width": 1000
            },
            "thumbnail": {
              "url": "https://images.mediahound.com/media/mhimgWZoLyvf3bv432dhEM4oE4OgcE2u0Yxc4Ow0nB2b.jpg",
              "height": 135,
              "width": 90
            },
            "small": {
              "url": "https://images.mediahound.com/media/mhimg0cqGrgTH3ocaK82fK9Sdnj5UEo2UJ537sXy7RUf.jpg",
              "height": 270,
              "width": 180
            },
            "medium": {
              "url": "https://images.mediahound.com/media/mhimgMQ5RVnfPadqmojTjpHgROSPq1xtsVcV6iCVzSpJ.jpg",
              "height": 540,
              "width": 360
            },
            "large": {
              "url": "https://images.mediahound.com/media/mhimgPsgfqjlk5WGNTMPVyFj90DHtbWiqDAyqHzjAv6R.jpg",
              "height": 1080,
              "width": 720
            }
          },
          "context": {

          }
        },
        "primaryName": {
          "object": {
            "name": "Gladiator"
          },
          "context": null
        },
        "keyContributors": {
          "content": [
            {
              "object": {
                "mhid": "mhricdHv2eCnYem0LZ5rNMCgBOesPtPAxPbwhNd9Pvub",
                "name": "Ridley Scott",
                "altId": "mhric-ridley-scott"
              },
              "context": {
                "sorting": {
                  "importance": 1
                },
                "relationships": [
                  {
                    "contribution": "Director"
                  },
                  {
                    "contribution": "Producer"
                  }
                ]
              }
            },
            {
              "object": {
                "mhid": "mhricPM4FE1LAJ4HoahHtcEXfXISghonBm1xqdwbQfyJ",
                "name": "Russell Crowe",
                "altId": "mhric-russell-crowe"
              },
              "context": {
                "sorting": {
                  "importance": 2
                },
                "relationships": [
                  {
                    "contribution": "Cast",
                    "role": "Maximus"
                  }
                ]
              }
            },
            {
              "object": {
                "mhid": "mhricy1v4gGapcEcyCd1YWfMQea7VhdQFj0KHrnlEV6N",
                "name": "Joaquin Phoenix",
                "altId": "mhric-joaquin-phoenix"
              },
              "context": {
                "sorting": {
                  "importance": 3
                },
                "relationships": [
                  {
                    "contribution": "Cast",
                    "role": "Commodus"
                  }
                ]
              }
            },
            {
              "object": {
                "mhid": "mhric0ehJSnDfAkPbUiIbdL9eR6YwKFlvuaoUDtS7qo8",
                "name": "Connie Nielsen",
                "altId": "mhric-connie-nielsen"
              },
              "context": {
                "sorting": {
                  "importance": 4
                },
                "relationships": [
                  {
                    "contribution": "Cast",
                    "role": "Lucilla"
                  }
                ]
              }
            },
            {
              "object": {
                "mhid": "mhricx7OJojMdAP5Shne5Hbu57bweBIlcPq26FvVYUQC",
                "name": "Oliver Reed",
                "altId": "mhric-oliver-reed"
              },
              "context": {
                "sorting": {
                  "importance": 5
                },
                "relationships": [
                  {
                    "contribution": "Cast",
                    "role": "Proximo"
                  }
                ]
              }
            }
          ],
          "pagingInfo": {
            "next": null,
            "previous": null
          }
        }
      },
      "context": {

      }
    }
  ],
  "pagingInfo": {
    "next": "https://api.mediahound.com/1.3/search/all/gladiator?types=Movie&pageSize=1&page=1",
    "previous": null
  }
}

You'll notice that this API request returned a paged response. This is true of most of the MediaHound API. Because of the size of The Entertainment Graph, we can't return everything to you at once. Instead, we chunk it up into pages and let you request more data one page at a time.

All That Data

Looking at the above Search response example, you'll notice just how much data we have to offer. All Media has metadata — details like name, release date, etc.

Media, importantly, has connections to other objects in The Entertainment Graph. Movies have a list of people who helped create the movie. We call these people Contributors. Contributors can cross different Content types. For example, Will Smith stars in movies and TV shows, but also creates music.

Explore Away!

We just explored the basics of The Entertainment Graph. This developer portal contains documentation about everything we have to offer, but since it's hard to know where to start, we thought we'd lay out a few REST endpoints that you might find interesting:

Endpoints of Interest

EndpointWhat is it for?
SearchSearch across all entertainment Content using plain text.
LookupGet precise metadata for IDs you already have.
ExploreBrowse The Entertainment Graph using Filters.
RelateFind similar or personalized content.
SilosGenerate multiple carousels of engaging and personalized Content at once.