Implementation Guide

Populating your local data storage

Common Sense Media currently requires that all API users pull data on a regular basis and store it locally to serve content; we do not support on-demand requests yet.

Reviews

IMPORTANT NOTE

We are transitioning over our unique identifiers to using UUIDs from IDs.  Please store both UUIDs and IDs to future-proof your data.

Partners who use Rovi/TMS should be aware that these services currently store the nid ("id" element in output). We will be contacting Rovi/TMS to store both fields.  Please continue to reference the nid but store both.  You will be able to transition over to using the "uuid" once Rovi/TMS has those mappings.  Partners who do not use these services should use the "uuid" right away.

  1. Create your local storage data table

    A sample table structure for holding the API data:

    mysql> CREATE TABLE csm_data (csm_uuid VARCHAR(100) NOT NULL, csm_id VARCHAR(100) NOT NULL, our_id VARCHAR(100) NOT NULL, last_updated INT NOT NULL, data TEXT NOT NULL);

csm_uuid

The universal unique ID assigned to each item by Common Sense Media. It is identified by the top level.

uuid

element in each returned item.

csm_id

The unique ID assigned to each item by Common Sense Media. It is identified by the top level.

id

element in each returned item.

our_id

The unique ID that you use internally for the same item. This allows you to pick the correct item to display in your own interface. Many API users also use a title matching service (see documentation) to supply the csm_uuid -> our_id mapping.

last_updated

The Unix timestamp the item was last changed. You will want to store the value in the top level.

changed

element in each return item, not your local timestamp for comparison in subsequent API calls (see step 3).

data

The blob of data for the given item. Based on your application's needs, you may choose to alter the raw data from the API before storing it in the table, or you may choose to store the raw data and alter it as needed. The former is useful when you have a single way that you display the data; the latter will give you more flexibility if you choose to display the data in several permutations.

  1. You may also want to parse out other data points from the API as separate columns for ease of querying based on your application's needs.

  2. Populate the table with all the existing Common Sense Media items

    https://api.commonsense.org/v2/review/browse?channel=REQUESTED_CHANNEL

    This returns all existing reviews for the given channel (see documentation).

    Your script should then loop through all the items and insert one row per item into your local storage data table, adding in your relevant unique ID for each item from whatever source you used to do the matching.

  3. Write a script to regularly retrieve new items

    The Common Sense Media API supports retrieving only items that are new or changed since a given timestamp using the

    delta

    query string parameter. You will want to use this because it reduces the size of the data packet returned by the API call significantly and allows you to minimize your local data processing to only items that need it. New content and changes to existing content are available in the API regularly, however there is no need to pull changes any more frequently than once an hour.

    You will first want to find the timestamp of the most recently updated item:

    SELECT MAX(last_updated) FROM csm_data;

    Then, use that timestamp in an API call to retrieve all items updated since then:

    https://api.commonsense.org/v2/reviews/browse?channel=REQUESTED_CHANNEL&delta=TIMESTAMP

    Your script should then loop through all the returned items and either update an existing row or insert a new row. See MySQL's syntax for doing so. You can also emulate it by first querying for a row in your local storage data table with the same csm_uuid value as the current result item. If it exists, update that row. If not, insert a new row.

Title Matching

The most often-asked question new API users have is how to tell which title in the Common Sense Media catalog matches their title. This is especially complicated in the case of movies where there may be more than one item with the same title both in your and Common Sense Media's catalog.

Examples:

Two movies with the same name:

A book and its movie and game spinoffs:

Even if there's only one item with the same name in Common Sense Media's catalog, variants on spelling may cause a straight title match to fail. For example, Amazon lists the title as Harry Potter and the Half-Blood Prince (Book 6).

Common Sense Media offers some data points that may help you match your catalog to ours.

  • Channel - this required parameter will help you differentiate between items of the same name but different media, as in the second example.
  • References - this element in each item's product data contains 3rd party IDs for the item. Types of IDs include ISBN (books), UPC (movies, games, etc), iTunes and Google Marketplace IDs (apps), and so on. These references are not to be considered comprehensive but may still be of use.
  • Release date - the 'releases' element in each item's product can be used to differentiate between multiple titles with the same name.

Some of our users prefer to use a title matching service such as Rovi or TMS. Although each implementation is different, the general approach is that--for a fee--the service will ingest your catalog and ours and do all the legwork of title matching, returning you a map of your ID to our IDs for each title that has a match. You will still need to pull our data using the API and store it locally for displaying to your own users.

 

Lists, Videos, and Blog Articles

  1. Create your local storage data table

    A sample table structure for holding the API data:

    mysql> CREATE TABLE csm_data (csm_uuid VARCHAR(100) NOT NULL, our_id VARCHAR(100) NOT NULL, last_updated INT NOT NULL, data TEXT NOT NULL);

csm_uuid

The unique ID assigned to each item by Common Sense Media. It is identified by the top level.

uuid

element in each returned item.

our_id

The unique ID that you use internally for the same item. This allows you to pick the correct item to display in your own interface. Many API users also use a title matching service (see documentation) to supply the csm_uuid -> our_id mapping.

last_updated

The Unix timestamp the item was last changed. You will want to store the value in the top level.

changed

element in each return item, not your local timestamp for comparison in subsequent API calls (see step 3).

data

The blob of data for the given item. Based on your application's needs, you may choose to alter the raw data from the API before storing it in the table, or you may choose to store the raw data and alter it as needed. The former is useful when you have a single way that you display the data; the latter will give you more flexibility if you choose to display the data in several permutations.

  1. You may also want to parse out other data points from the API as separate columns for ease of querying based on your application's needs.

  2. Populate the table with all the existing Common Sense Media items

    https://api.commonsense.org/v2/video/browse?type=REQUESTED_TYPE

    This returns all existing video reviews for the given type (see documentation).

    Your script should then loop through all the items and insert one row per item into your local storage data table, adding in your relevant unique ID for each item from whatever source you used to do the matching.

  3. Write a script to regularly retrieve new items

    The Common Sense Media API supports retrieving only items that are new or changed since a given timestamp using the

    delta

    query string parameter. You will want to use this because it reduces the size of the data packet returned by the API call significantly and allows you to minimize your local data processing to only items that need it. New content and changes to existing content are available in the API regularly, however there is no need to pull changes any more frequently than once an hour.

    You will first want to find the timestamp of the most recently updated item:

    SELECT MAX(last_updated) FROM csm_data;

    Then, use that timestamp in an API call to retrieve all items updated since then:

    https://api.commonsense.org/v2/video/browse?type=REQUESTED_TYPE&delta=TIMESTAMP

    Your script should then loop through all the returned items and either update an existing row or insert a new row. See MySQL's syntax for doing so. You can also emulate it by first querying for a row in your local storage data table with the same csm_uuid value as the current result item. If it exists, update that row. If not, insert a new row.