Getting Started with the IMDb API

The IMDb API delivers content via AWS Data Exchange. This article has everything you need to request access and start querying the IMDb API.

Requesting an IMDb API trial

Free trials for the IMDb API are requested via IMDb's AWS Marketplace:

1. Sign up for an AWS account
2. Go to AWS Data Exchange and go to ‘Browse Catalog’. Search for IMDb and select ‘API’ under ‘Data available through’. This will show you the products below:

3. Select the product you wish to subscribe to. Here you can find more information about the product. Click ‘Continue to subscribe’.

4. From here you can complete a subscription request for the product. You should review the product offer and subscription terms. Then you can complete a subscription request using the available form and click ‘Send subscription request to provider’.

5. Your subscription request will be processed. You can find your request under ‘Subscriptions requests’. Once approved the status will be updated here, you will also receive an email notification.

6. Once your request has been approved you can find your subscription details under ‘Subscriptions’. You are now ready to access the API. Please see the “Getting Started with the IMDb API” documentation.

7. To access the API you will need an endpoint, data-set-id, revision-id and asset-id for your product. These are unique for each product and can be found in the AWS DataExchange console under ‘Entitled data’. From here select the product you wish to access, and go to the most recent revision, then click on the API asset under this revision. Here you should see an ‘Asset Overview’ section. This will give details of the endpoint, data-set-id, revision-id and asset-id you will need. All three data-set use the same endpoint: https://atlas.us-east-1.datax.aws.a2z.com/prod/v1 .

Creating an Access Key

1. Sign into you AWS account and in the navigation bar on the upper right, choose your account name or number and then choose My Security Credentials.
2. Expand the "Access keys (access key ID and secret access key)" section.
3. To create an access key, choose "Create New Access Key". If you already have two access keys, this button is disabled; you must delete an access key before you can create a new one. 
4. When prompted, choose either "Show Access Key" or "Download Key File". This is your only opportunity to save your secret access key. After you've saved your secret access key in a secure location, chose "Close".

Accessing the IMDb API

Querying the IMDb API

{
  title(id: "tt0120338") {
    runtime {
      seconds
    }
  }
}

Example in TypeScript

• Create a project with the following command.

$ npm init

• Install required packages.

$ npm install --save aws4
$ npm install --save-dev @types/node

• Make a request with this sample code.

import { sign } from "aws4";
import { readFileSync } from "fs";
import { request } from "https";

const asyncRequest = async (
  options: any
): Promise<{
  statusCode?: number;
  body: string;
}> => {
  return new Promise((resolve, reject) => {
    const req = request(options, function (res) {
      let data = "";
      res.on("data", (chunk) => {
        data += chunk;
      });
      res.on("end", () => {
        resolve({ statusCode: res.statusCode, body: data });
      });
    });
    req.on("error", (err) => {
      reject(err);
    });
    if (options.body) req.write(options.body);
    req.end();
  });
};

(async () => {
   // replace this with your actual accessKeyId from AWS credentials here
  const accessKeyId = "ABCDEFGHIJK12345";

  // replace this with your actual secretAccessKey from AWS credentials here
  const secretAccessKey = "Abcdefg/1234+hiJKLmnopqrstuvwxYz";
  
  const service = "dataexchange";

  const region = "us-east-1";

  // query we saved earlier
  const titanicRuntimeQuery = readFileSync("./titanicRuntimeQuery.graphql", "utf-8");

  const body = JSON.stringify({ query: titanicRuntimeQuery });

  // change to any desired ISO 639-1 country or language code
  const headers = {
     "Content-Type": "application/json",
    "x-amzn-dataexchange-asset-id": "your-asset-id",
    "x-amzn-dataexchange-revision-id": "your-revision-id",
    "x-amzn-dataexchange-data-set-id": "your-data-set-id",
   };

  const host = "atlas.us-east-1.datax.aws.a2z.com";
  const method = "POST";
  const path = "/prod/v1";

  // sign the request
  const options = sign({
      body,
       headers,
       host,
      method,
      path,
      service,
      region,
     },
    { 
      accessKeyId, 
      secretAccessKey
     }
  );
  
  // make the request
  const response = await asyncRequest(
    options
  );
  
  // print the response body and status to console
  console.log(response.statusCode);
  console.log(response.body.trim());
})();

• Evaluate the response

{
  "data": {
    "title": {
      "runtime": {
        "seconds": 11640
      }
    }
  },
  "extensions": {
    "disclaimer": "Use of the IMDb data provided by this API is governed by the AWS Data Subscription Agreement and IMDb Content License Agreement."
  }
}

Example in Java

• Follow this guide to configure Maven to use aws-java-sdk.

• Add this BOM to pom.xml, with the latest available version.

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.amazonaws</groupId>
      <artifactId>aws-java-sdk-bom</artifactId>
      <version>1.11.1000</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

• Specify individual module from the SDK in pom.xml.

<dependencies>
  <dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-java-sdk-core</artifactId>
  </dependency>
</dependencies>

• Add the following maven-compiler-plugin configuration in pom.xml.

<build>
    <plugins>
        <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-jar-plugin</artifactId>
        <version>3.1.0</version>
        <configuration>
            <archive>
            <manifest>
                <addClasspath>true</addClasspath>
                <classpathPrefix>dependency/</classpathPrefix>
                <mainClass>org.example.basicapp.AccessingImdbApiExample</mainClass>
            </manifest>
            </archive>
        </configuration>
        </plugin>
    </plugins>
</build>

• Make a request with this sample code.

import com.amazonaws.AmazonServiceException;
import com.amazonaws.ClientConfiguration;
import com.amazonaws.DefaultRequest;
import com.amazonaws.Request;
import com.amazonaws.auth.AWS4Signer;
import com.amazonaws.auth.BasicAWSCredentials;
import com.amazonaws.http.AmazonHttpClient;
import com.amazonaws.http.ExecutionContext;
import com.amazonaws.http.HttpMethodName;
import com.amazonaws.http.HttpResponse;
import com.amazonaws.http.HttpResponseHandler;

import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.net.URI;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Paths;

public final class AccessingImdbApiExample {

    private static final String ENDPOINT = "https://atlas.us-east-1.datax.aws.a2z.com";
    private static final String REGION = "us-east-1";
    private static final String PATH = "prod/v1";

    // replace this with your actual ACCESS_KEY_ID from AWS credentials here
    private static final String ACCESS_KEY_ID = "ABCDEFGHIJK12345";

    // replace this with your actual SECRET_ACCESS_KEY from AWS credentials here
    private static final String SECRET_ACCESS_KEY = "Abcdefg/1234+hiJKLmnopqrstuvwxYz";

    public static void main(String[] args) throws IOException {

        // Query we saved earlier
        String titanicRuntimeQuery = new String(Files.readAllBytes(Paths.get("src/titanicRuntimeQuery.graphql")), StandardCharsets.UTF_8);
        String titanicRuntimeQueryString = "{\"query\":\"" + titanicRuntimeQuery.replace("\"", "\\\"").replaceAll("\\s+","") + "\"}";
        
        // Construct a request.
        Request<?> request = new DefaultRequest<Void>("dataexchange");
        request.setEndpoint(URI.create(ENDPOINT));
        request.setResourcePath(PATH);
        request.setHttpMethod(HttpMethodName.POST);
        request.addHeader("Content-Type", "application/json");
        request.addHeader("x-amzn-dataexchange-asset-id", "your-asset-id");
        request.addHeader("x-amzn-dataexchange-revision-id", "your-revision-id");
        request.addHeader("x-amzn-dataexchange-data-set-id", "your-data-set-id");
        request.setContent(new ByteArrayInputStream(titanicRuntimeQueryString.getBytes(StandardCharsets.UTF_8)));

        // Create an AWSv4 signer
        AWS4Signer signer = new AWS4Signer();
        signer.setRegionName(REGION);
        signer.setServiceName("dataexchange");

        // Sign the request
        signer.sign(request, new BasicAWSCredentials(ACCESS_KEY_ID, SECRET_ACCESS_KEY));

        // Make the request
        ClientConfiguration clientConfiguration = new ClientConfiguration().withMaxConnections(10);
        AmazonHttpClient client = new AmazonHttpClient(clientConfiguration);
        AmazonHttpClient.RequestExecutionBuilder builder = client.requestExecutionBuilder()
            .request(request)
            .executionContext(new ExecutionContext(true))
            .errorResponseHandler(new HttpResponseHandler<AmazonServiceException>() {
                @Override
                public AmazonServiceException handle(HttpResponse httpResponse) {
                    AmazonServiceException ase = new AmazonServiceException("Amazon Service Exception.");
                    ase.setStatusCode(httpResponse.getStatusCode());
                    ase.setErrorCode(httpResponse.getStatusText());
                    return ase;
                }

                @Override
                public boolean needsConnectionLeftOpen() {
                    return false;
                }
            });

        // Get the response
        HttpResponse response = builder
            .execute(new HttpResponseHandler<String>() {
                @Override
                public String handle(HttpResponse httpResponse) {
                    System.out.println("Response body = " + inputStreamToString(httpResponse.getContent()));
                    return null;
                }

                @Override
                public boolean needsConnectionLeftOpen() {
                    return false;
                }
            })
            .getHttpResponse();
        System.out.println("Response status code = " + response.getStatusCode());
    }

    private static String inputStreamToString(InputStream inputStream) throws IOException {
        ByteArrayOutputStream result = new ByteArrayOutputStream();
        byte[] buffer = new byte[1024];
        for (int length; (length = inputStream.read(buffer)) != -1; ) {
            result.write(buffer, 0, length);
        }
        return result.toString("UTF-8");
    }

}

• Run the following commands

mvn install clean
mvn package
mvn dependency:copy-dependencies
java -jar target/myapp-1.0.0.jar

• Evaluate the response

{
  "data": {
    "title": {
      "runtime": {
        "seconds": 11640
      }
    }
  },
  "extensions": {
    "disclaimer": "Use of the IMDb data provided by this API is governed by the AWS Data Subscription Agreement and IMDb Content License Agreement."
  }
}