Integration

This section describes two methods available for maintaining Popyoular data on the server side.

List of Updated Asset Data

This list is a variant of the asset list described earlier. It contains all assets in one or more key spaces that have been ingested by Popyoular. It supports inclusion of Popyoular data and is well suited for both full and incremental exports.

The list is filtered to only contain assets with updated data. It is sorted in descending order by the last time popyoular data was updated.

Updates of Popyoular data only make sense within a collection of publications and within a key space. Examples

  • A dutch review was added to a movie in the dutch movie catalogue (key space)
  • A german review was added to a movie in the german movie catalogue (key space)

The fact that a german review was added to a movie in the dutch catalogue might not be relevant.

Hence, when requesting the list of updated assets it is necessary specify both collection and key space:

http://api.popyoular.se/movies/assets/$account_id/updated?updates-for=reviews@$collection@$key_space

Status: 200 OK
{
  "_links": {
    "_self": {
      "href": "http://api.popyoular.se/movies/assets/$account_id/$key_space"
    },
    "_next": {
      "href": "http://api.popyoular.se/movies/assets/$account_id/$key_space?before=1c8d3329-440d-4ca8-9d0c-4a755d14146d"
    }
  },
  "update-id":"1c8d3329-440d-4ca8-9d0c-4a755d14146d",
  "_embedded": {
    "assets": [
      {
        "links": {
          "_self": {
            "href": "http://api.popyoular.se/movies/assets/$customer_id/$key_space/$asset_id"
          }
        },
        "titles": [
          "Locke",
          "No Turning Back"
        ],
        "year": "2013",
        "key-space": "$key_space",
        "asset-id": "$asset_id",
        "status": "completed",
        "created": "2015-01-12T18:00:18.365",
        "updated": "2015-01-12T18:00:18.365",
        "_embedded": {
          "reviews@$collection" : [
            {
              "_links": {
                "_self": {
                  "href": "http://api.popyoular.se/movies/reviews/http%3A%2F%2Fwww.usatoday.com%2Fstory%2Flife%2Fmovies%2F2014%2F05%2F01%2Flocke-movie-review%2F7953919%2F"
                },
                "review-quotes": {
                  "href": "http://api.popyoular.se/movies/reviews/http%3A%2F%2Fwww.usatoday.com%2Fstory%2Flife%2Fmovies%2F2014%2F05%2F01%2Flocke-movie-review%2F7953919%2F/quotes"
                },
                "review-quotes": {
                  "href": "http://api.popyoular.se/movies/publications/usatoday.com"
                },
                "review-graphics":{
                  "href":"http://api.popyoular.se/movies/reviews/http%3A%2F%2Fwww.usatoday.com%2Fstory%2Flife%2Fmovies%2F2014%2F05%2F01%2Flocke-movie-review%2F7953919%2F/graphics"
                },
                "publication-graphics": {
                  "href": "http://api.popyoular.se/movies/publications/usatoday.com/graphics"
                }
              },
              "score": {
                "value":4.0,
                "normalized":10.0,
                "formatted":"3.5/4"
              },
              "link": "http://www.usatoday.com/story/life/movies/2014/05/01/locke-movie-review/7953919/",
              "publication-name": "USA Today",
              "publication-date": "2013-05-01"
            },
            {
              "_links": {
                "_self": {
                  "href": "http://api.popyoular.se/movies/reviews/http%3A%2F%2Fwww.rogerebert.com%2Freviews%2Flocke-2014"
                },
                "quotes": {
                  "href": "http://api.popyoular.se/movies/reviews/http%3A%2F%2Fwww.rogerebert.com%2Freviews%2Flocke-2014/quotes"
                },
                "publication": {
                  "href": "http://api.popyoular.se/movies/publications/rogerebert.com"
                }
              },
              "score" : {
                "value":3.5,
                "normalized":8.75,
                "formatted":"3.5/4"
              },
              "link": "http://www.rogerebert.com/reviews/locke-2014",
              "publication-name": "Roger Ebert",
              "publication-date": "2013-04-25",
            }
          ]
        }
      },
      ...
      ...
      ...
    ]
  }
}

It is possible to specify more than one collection/key space pair and get multiple update streams in a single list. This makes it a versatile tool when you have multiple catalogues of movies for which you want to maintain Popyoular data.

The following table contains examples of a few different useful combinations.

parameter description  
updates-for=reviews@shared.swedish@my_swedish_catalogue Updates of swedish reviews for movies in my swedish catalogue  
updates-for=reviews@shared.swedish@my_swedish_catalogue,reviews@shared.dutch@my_dutch_catalogue Updates of swedish reviews for movies in my swedish catalogue and updates of dutch reviews for movies in my dutch catalogue  
updates-for=reviews@shared.english@my_svod,reviews@shared.english@my_tvod Updates of english reviews for both my TVOD and SVOD catalogues  
updates-for=reviews@shared.english@all,reviews@shared.swedish@all Updates of both swedish and english reviews to a single key space  

Including award updates

Inclusion of awards works in a way similar to inclusion of reviews but instead of specifying a collection, the category of the award is specified. Examples:

updates-for=awards@SE@my_swedish_catalogue - Updates of swedish awards for movies in my swedish catalogue. updates-for=awards@international@my_swedish_catalogue - Updates of internationally applicable awards for movies in my swedish catalogue.

They can be combined in the same way as the review inclusion.

Including of popyoular data

Basic review information is included automatically (e.g. reviews@shared.swedish@my_swedish_catalogue implicitly implies embed=reviews@shared.swedish). To include more detailed information such as quotes, add an embed parameter as described in the Popyoular Data section

Pagination

Follow the link in the object _next to get to the next (earlier in time) page of updates. To get all updates repeat this until the _next is missing from the response.

Usage notes

To maintain popyoular data locally start by consuming all updates in the list and then periodically poll the API for updates. There are two ways to poll the API

  • Using the parameter since. This will give you all updates after the given time. The value of since can be either the Epoch time (milliseconds since midnight, 1 January 1970) or an ISO8601 date (e.g. 2015-01-12T18:00:18.365).
  • Using the parameter after. Each update contains an update-id. Using this as the value of the parameter after will give you all updates after the update with that update-id. To do incremental exports, keep track of update-id of the last applied update between invocations.

If the updates-for or embed parameters are changed, you have to restart the synchronization by doing a full export.

Event Feed

This feed contains fine grained update information. While the previous method should be effective for synchronizing Popyoular data as-is, this feed might be more suited when maintaining a relational view of the Popyoular data.

http://api.popyoular.se/movies/assets/$account_id/events?updates-for=reviews@$collection@$key_space,awards@$country@$key_space

Status: 200 OK
{
  "_links": {
    "_self": {
      "href": "http://api.popyoular.se/movies/assets/$account_id/events?updates-for=reviews@$collection@$key_space,awards@$country@$key_space"
    },
    "_next": {
      "href": "http://api.popyoular.se/movies/assets/$account_id/events?updates-for=reviews@$collection@$key_space,awards@$country@$key_space&after=d8d25374-c991-11e4-8731-1681e6b88ec1"
    }
  },
  "_embedded": {
    "events": [
      {
        "_links":{
          "_self":{
            "href":"http://api.popyoular.se/movies/assets/$account_id/events/4a0ac78e-c991-11e4-8731-1681e6b88ec1"
          }
        },
        "date": "2015-01-12T18:00:18.365",
        "event-id": "4a0ac78e-c991-11e4-8731-1681e6b88ec1",
        "event-type": "asset-added",
        "payload": {
          "titles": [
            "Locke",
            "No Turning Back"
          ],
          "year": "2013",
          "key-space": "$key_space",
          "asset-id": "$asset_id",
          "status": "submitted",
          "created": "2015-01-12T18:00:18.365",
          "updated": "2015-01-12T18:00:18.365"
        }
      },
      {
        "_links":{
          "_self":{
            "href":"http://api.popyoular.se/movies/assets/$account_id/events/d8d25374-c991-11e4-8731-1681e6b88ec1"
          }
        },
        "date": "2015-01-13T11:03:22.762",
        "event-id": "d8d25374-c991-11e4-8731-1681e6b88ec1",
        "event-type": "review-added",
        "payload": {
          "key-space": "$key_space",
          "asset-id": "$asset_id",
          "graphics": {
            "url": "http://static.popyoular-img.com/review-graphics/usatoday.com/score-3.5-4.png",
            "width": 50,
            "height": 14
          },
          "score": {
            "value": 4.0,
            "normalized": 10.0,
            "formatted": "3.5/4"
          },
          "id": "http://www.usatoday.com/story/life/movies/2014/05/01/locke-movie-review/7953919/",
          "link": "http://www.usatoday.com/story/life/movies/2014/05/01/locke-movie-review/7953919/",
          "publication-name": "USA Today",
          "publication-date": "2013-05-01",
          "publication-graphics": {
            "_links": {
              "_self": {
                "href": "http://api.popyoular.se/publications/usatoday.com/graphics"
              }
            },
            "medium-logo": {
              "width": 64,
              "height": 64,
              "link": "http://static3.popyoular-img.com/source-usatoday.com-64x64.png"
            },
            "small-logo": {
              "width": 16,
              "height": 16,
              "link": "http://static1.popyoular-img.com/source-usatoday.com-favicon.png"
            },
            "large-logo": {
              "width": 170,
              "height": 67,
              "link": "http://static1.popyoular-img.com/source-usatoday.com-large.png"
            }
          }
        }
      }
    ]
  }
}

It is a stream of events and the event types are

Event Description
asset-added Asset was added to Popyoular
asset-removed Asset was removed from Popyoular
review-added Review was added to asset
review-removed Review was removed from asset
award-added Award was added to asset
award-removed Award was removed from asset
quote-added Quote was added to review
quote-removed Quote was removed from review
aggregated-data-created Aggregated data created for asset
aggregated-data-removed Aggregated date removed from asset
aggregated-data-updated Aggregated data was updated (e.g. score and number of reviews)

Events are guaranteed to appear in a consistent order, e.g. a review-added for an asset will always be preceded by an asset-added. Also, asset-removed will always be preceded by remove-events for the data associated with the asset.

Be sure to handle unknown event types gracefully - more types might be added in the future.

This feed expects an updates-for and interprets it in exactly the same way as the feed described in the previous section. However, it does not support inclusion. The data is contained in the events.

Pagination

Use the _links._next._href URL to get the next page. When there are no more events the _links._next will not be included in the response.

Usage notes

The events are ordered by the time the event happened, ascending. To maintain a view of the data locally consume all the events in the list then periodically poll the API for new events. Keep track of the id (event-id of the last event consumed) and use it for the value of the parameter after for the next invocation. This will return events which happened after the one last consumed. Time based polling is not supported for the event feed.

asset-added

Corresponds to the event when the asset was submitted to Popyoular for ingestion.

{
   "date":"2015-01-12T18:00:18.365",
   "event-id":"4a0ac78e-c991-11e4-8731-1681e6b88ec1",
   "event-type":"asset-added"
   "payload":{
     "titles": [
       "Locke",
       "No Turning Back"
     ],
     "year":"2013",
     "key-space":"$key_space",
     "asset-id":$asset_id,
     "status": "submitted",
     "created":"2015-01-12T18:00:18.365",
     "updated":"2015-01-12T18:00:18.365"
   }
}

asset-removed

Corresponds to the event when the asset was deleted.

{
   "date":"2015-01-13T11:03:22.762",
   "event-id":"d8d25374-c991-11e4-8731-1681e6b88ec1",
   "event-type":"asset-removed",
   "payload":{
     "key-space":"$key_space",
     "asset-id":$asset_id"
   }
}

review-added

{
  "date": "2015-01-13T11:03:22.762",
  "event-id": "d8d25374-c991-11e4-8731-1681e6b88ec1",
  "event-type": "review-added",
  "payload": {
    "key-space": "$key_space",
    "asset-id": "$asset_id",
    "graphics": {
      "url": "http://static.popyoular-img.com/review-graphics/usatoday.com/score-3.5-4.png",
      "width": 50,
      "height": 14
    },
    "score": {
      "value": 4.0,
      "normalized": 10.0,
      "formatted": "3.5/4"
    },
    "id": "http://www.usatoday.com/story/life/movies/2014/05/01/locke-movie-review/7953919/",
    "link": "http://www.usatoday.com/story/life/movies/2014/05/01/locke-movie-review/7953919/",
    "publication-name": "USA Today",
    "publication-date": "2013-05-01",
    "publication-graphics": {
      "_links": {
        "_self": {
          "href": "http://api.popyoular.se/publications/rogerebert.com/graphics"
        }
      },
      "medium-logo": {
        "width": 64,
        "height": 64,
        "link": "http://static3.popyoular-img.com/source-rogerebert.com-64x64.png"
      },
      "small-logo": {
        "width": 16,
        "height": 16,
        "link": "http://static1.popyoular-img.com/source-rogerebert.com-favicon.png"
      },
      "large-logo": {
        "width": 170,
        "height": 67,
        "link": "http://static1.popyoular-img.com/source-rogerebert.com-large.png"
      }
    }
  }
}

review-removed

{
  "date": "2015-01-13T11:03:22.762",
  "event-id": "d8d25374-c991-11e4-8731-1681e6b88ec1",
  "event-type": "review-removed",
  "payload": {
    "key-space": "$key_space",
    "asset-id": "$asset_id",
    "id":"http://www.usatoday.com/story/life/movies/2014/05/01/locke-movie-review/7953919/"
  }
}

award-added

{
  "date": "2015-01-13T11:03:22.762",
  "event-id": "d8d25374-c991-11e4-8731-1681e6b88ec1",
  "event-type": "award-added",
  "payload": {
    "movie-award-id":"8e09b1e0-cb5b-11e4-8830-0800200c9a66",
    "key-space": "$key_space",
    "asset-id": "$asset_id",
    "award-category":"international",
    "award-id": "cannes",
    "name": "Cannes Lions",
    "year": "2011",
    "nominations": 0,
    "wins": 1,
    "image": {
      "width": 145,
      "height": 70,
      "link": "http://static3.popyoular-img.com/award-images/award-cannes-145x70.png"
    },
    "winner-description": "Winner of Best actor",
    "nominee-description": "",
    "short-description": "Cannes Festival Winner",
    "award-details": [
      {
        "name": "Best actor",
        "category": "best-actor",
        "year": "2011",
        "type": "winner"
      }
    ]
  }
}

award-removed

{
  "date": "2015-01-13T11:03:22.762",
  "movie-award-id":"8e09b1e0-cb5b-11e4-8830-0800200c9a66",
  "event-id": "d8d25374-c991-11e4-8731-1681e6b88ec1",
  "event-type": "award-added",
  "payload": {
    "key-space": "$key_space",
    "asset-id": "$asset_id",
}

AWS SQS

The event feed may be published to a shared queue in AWS SQS

One benefit of using SQS is that there’s no need to keep track of the latest event consumed.

To have the events delivered to SQS, issue a PUT to

http://api.popyoular.se/movies/assets/$account_id/events/sqs?updates-for=reviews@$collection@$key_space,awards@$country@$key_space&aws_account_number=$aws_account_number

Status: 201 Created
{
  "_links":{
    "_self":{
      "href":"http://api.popyoular.se/movies/feeds/events/$customer_id/sqs?events-for=$key_space@$collection&aws_account_number=$aws_account_number"
    },
    {
      "queue-url":"http://sqs.us-east-1.amazonaws.com/123456789012/df98aa13-e7af-4738-8dff-87818aeaf68c"
    }

  }
}

The PUT will return the same queue as long as the parameters aren’t modified. If the parameters are modifier a new queue will be returned.

Delete the SQS queue by issuing a DELETE to the queue resource:

http://api.popyoular.se/movies/feeds/events/$customer_id/sqs?events-for=$key_space@$collection

Custom

If you need the integration to be done in another way we’ll make our best to meet your needs.