Implementation Guide - v3

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

  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, your_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 id element in each returned item.

    your_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 -> your_id mapping.

    last_updated The Unix timestamp the item was last changed. You will want to store the value in the top level updated 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.

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

    https://api.commonsense.org/api/v3/reviews?mediaType=REQUESTED_MEDIATYPE

    This returns all existing reviews for the given media 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 since 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/api/v3/reviews?mediaType=REQUESTED_MEDIATYPE&since=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.

  • mediaType - this item element 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.
  • releaseDates - this 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 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.