Popyoular Data

Asset Resource

The asset resource serves as the base for retrieving Popyoular data. The most basic request is

GET http://api.popyoular.se/movies/assets/{account-id}/$key_space/$asset_id

Status: 200 Ok
{
  "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": "pending"
}

The response contains the information given when the asset was submitted. Also included is the matching status of the asset. It can be either pending or completed. Pending means that the system hasn’t digested it yet. In most cases an asset will be in the pending state for only a few seconds, but sometimes, the system decides that the asset has to be handled manually. In this case the asset can remain in the pending state for days.

There is no need to keep track of which assets are pending. Start using them right away. The only thing which will happen when using a pending asset is that requests for Popyoular data will come back empty.

Requesting Popyoular Data

Popyoular data can be included in the asset resource at different levels of detail. The parameter embed controls what is included. The following table summarizes what can be included. There are more detailed explanations of each possible value in the coming sections.

embed parameter value What’s included
reviews@$collection Reviews from the given collection (e.g. german-english for German and English reviews)
review-quotes Quotes for each review
review-graphics Graphics for each review (stars, dice and so forth)
review-publication Publication metadata for each review (publication name and URL)
publication-graphics Publication graphics (logotypes and so forth)
awards@$country Award wins/nominations
awards-descriptions@$locale Localized natural language descriptions of wins/nominations (e.g. ‘Winner of Best Picture and Best Actress in a Leading Role’)

Multiple inclusions are separated by ,, e.g. embed=asset.reviews@$collection,review-quotes includes reviews and quotes.

As can be seen in the following section, the _links-object of each resource representation indicates what can be included.

Publications

List of publications from which Popyoular has reviews

GET http://api.popyoular.se/movies/publications

Status: 200 Ok
{
  "_links":{
    "_self":{
      "href":"http://api.popyoular.se/movies/publications"
    }
  },
  "_embedded": {
  
   "publications:[{
      "_links":{
        "_self":{
          "href":"http://api.popyoular.se/movies/publications/theguardian.co.uk"
        },
        "graphics":{
          "href":"https//api.popyoular.se/movies/publications/theguardian.co.uk/graphics"
        }
      }
      "id":"theguardian.co.uk"
      "name":"The Guardian",
      "url":"http://www.theguardian.com",
  },
  {
      "_links":{
        "_self":{
          "href":"http://api.popyoular.se/movies/publications/svd.se"
        },
        "graphics":{
          "href":"https//api.popyoular.se/movies/publications/svd.se/graphics"
        }
      }
      "id":"svd.se"
      "name":"Svenska Dagbladet",
      "url":"http://www.svd.se",
  }
  ...
  ...
  ...
  ...
  ]}
}

Collections

Publications are grouped into collections. A collection is typically a group of publications in a given language, or a couple of languages, e.g. Swedish and English.

This resource contains all collections

http://api.popyoular.se/movies/shared-collections

Status: 200 Ok
{
  "_links": {
    "_self": {
      "href": "http://api.popyoular.se/movies/shared-collections"
    }
  },
  "_embedded": [
    {
      "_links": {
        "_self": {
          "href": "http://api.popyoular.se/movies/shared-collections/all"
        },
        "publications": {
          "href": "http://api.popyoular.se/movies/shared-collections/all/publications"
        }
      },
      "id": "all"
    },
    {
      "_links": {
        "_self": {
          "href": "http://api.popyoular.se/movies/shared-collections/swedish-english"
        },
        "publications": {
          "href": "http://api.popyoular.se/movies/shared-collections/swedish-english/publications"
        }
      },
      "id": "swedish-english"
    },
    ...
    ...
    ...
    ...
  ]
}

Reviews

To include reviews, specify from which collection of publications, for example the collection with swedish and english reviews:

`embed=asset.reviews@shared.swedish-english`

GET http://api.popyoular.se/movies/assets/customer-1/default/123?embed=reviews@shared.swedish-english

Status: 200 Ok
{
  "_links": {
    "_self": {
      "href": "http://api.popyoular.se/movies/assets/customer-1/default/123?embed=asset.reviews@shared.swedish-english"
    }
  },
  "titles": [
    "Locke",
    "No Turning Back"
  ],
  "year": "2013",
  "key-space": "default",
  "asset-id": "123",
  "status": "completed",
  "_embedded": {
    "reviews@shared.swedish-english": [
      {
        "_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-publication": {
            "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",
      },
      ...
      ...
      ...
    ]
  }
}

Not all reviews have a score. In these cases score.value and score.normalize will be null and score.formatted will be the empty string.

There are also reviews without publication date. publication-date will be null for these reviews.

Quotes

Many of the reviews have hand picked quotes. To include these, add review-quotes to the embed parameter

http://api.popyoular.se/movies/assets/customer-1/default/123?embed=reviews@shared.swedish-english,review-quotes

Status: 200 Ok
{
  "_links": {
    "_self": {
      "href": "http://api.popyoular.se/movies/assets/customer-1/default/123?embed=asset.reviews@shared.swedish-english"
    }
  },
  "titles": [
    "Locke",
    "No Turning Back"
  ],
  "year": "2013",
  "key-space": "default",
  "asset-id": "123",
  "status": "completed",
  "_embedded": {
    "reviews@shared.swedish-english": [
      {
        "_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-publication": {
            "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"
          }
        },
        "_embedded": {
          "quotes": [
            {
              "_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/quotes/90a7ef20-c8b8-11e4-8830-0800200c9a66"
                }
              },
              "text": "...a magnificent drama that resounds with powerful, universal themes."
            }
          ]
        },
        "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"
          }
        },
        "_embedded": {
          "quotes": [
              "_links": {
                "_self": {
                  "href": "http://api.popyoular.se/movies/reviews/http%3A%2F%2Fwww.rogerebert.com%2Freviews%2Flocke-2014/quotes/90a7ef20-c8b8-11e4-8830-0800200c9a66"
                }
              },
            {
              "text": "The self-imposed minimalism of the conceit challenges Knight to make a compelling cinematic work."
            }
          ]
        },
        "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",
      },
      ...
      ...
      ...
    ]
  }
}

Review Graphics

Include score graphics for each review such as stars, dice or whatever it is the publication uses by adding review-graphics to embed:

This adds the following to the object _embedded:

{
  "review-graphics": {
     "_links": {
       "_self": {
         "href":"http://api.popyoular.se/publications/rogerebert.com/review-graphics/3.5%2f4"
       }
     },
     "url":"http://api.popyoular.se/review-graphics/rogerebert.com/score-3.5-4.png",
     "width":50,
     "height":14
  }
}

Publication Logotypes

Include publication logos and icons by adding publication.graphics to the embed parameter

This adds the following to the object _embedded:

{
  "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"
    }
  }
}

Awards

It is possible to include awards that a movie has received or has been nominated for. Awards are categorized into two groups

  • International: Major awards that are widely known in many countries.
  • Local: Awards mostly relevant in one country.

Include local awards by adding awards@$country to embed, where country is the ISO 3166-1 code. Include international awards by adding @awards@international to embed.

Example of included award data:

{
  "awards@international": {
    "_self":{
      "href":"http://api.popyoular.se/movies/popyoular/movies/1878/awards/international"
    },
    "awards":[
      {
        "_links": {
          "_self":{
            "_href":"http://api.popyoular.se/movies/awards/1878/awards/international/oscars"
          }
        },
        "award-id": "oscars",
        "name": "Academy Awards",
        "year": "2011",
        "nominations": 5,
        "wins": 5,
        "image": {
          "width": 170,
          "height": 70,
          "link": "http://static3.popyoular-img.com/award-images/award-oscars-170x70.png"
        },
        "winner-description": "Winner of Best Original Score, Best Costume Design, Best Actor in a Leading Role, Best Director and Best Picture",
        "nominee-description": "Nominated for Best Cinematography, Best Original Screenplay, Best Art Direction, Best Film Editing and Best Actress in a Supporting Role",
        "short-description": "Academy Award Winning",
        "award-details": [
          {
            "name": "Best Cinematography",
            "category": "best-cinematography",
            "year": "2011",
            "type": "nominee"
          },
          {
            "name": "Best Original Screenplay",
            "category": "best-original-screenplay",
            "year": "2011",
            "type": "nominee"
          },
          {
            "name": "Best Original Score",
            "category": "best-original-score",
            "year": "2011",
            "type": "winner"
          },
          {
            "name": "Best Art Direction",
            "category": "best-art-direction",
            "year": "2011",
            "type": "nominee"
          },
          {
            "name": "Best Costume Design",
            "category": "best-costume-design",
            "year": "2011",
            "type": "winner"
          },
          {
            "name": "Best Film Editing",
            "category": "best-film-editing",
            "year": "2011",
            "type": "nominee"
          },
          {
            "name": "Best Acress in a Supporting Role",
            "category": "best-actress-supporting-role",
            "year": "2011",
            "type": "nominee"
          },
          {
            "name": "Best Actor in a Leading Role",
            "category": "best-actor-leading-role",
            "year": "2011",
            "type": "winner"
          },
          {
            "name": "Best Director",
            "category": "best-director",
            "year": "2011",
            "type": "winner"
          },
          {
            "name": "Best Picture",
            "category": "best-picture",
            "year": "2011",
            "type": "winner"
          }
        ]
      },
      {
        "award-id": "golden-globes",
        "name": "Golden Globe",
        "year": "2012",
        "nominations": 2,
        "wins": 2,
        "image": {
          "width": 120,
          "height": 70,
          "link": "http://static2.popyoular-img.com/award-images/award-golden-globes-120x70.png"
        },
        "winner-description": "Winner of Best Actor – Musical or Comedy and Best Motion Picture – Musical or Comedy",
        "nominee-description": "Nominated for Best Director and Best Supporting Actress",
        "short-description": "Golden Globe Winner",
        "award-details": [
          {
            "name": "Best Actor – Musical or Comedy",
            "category": "best-actor-motion-picture-musical-or-comedy",
            "year": "2012",
            "type": "winner"
          },
          {
            "name": "Best Director",
            "category": "best-director",
            "year": "2012",
            "type": "nominee"
          },
          {
            "name": "Best Motion Picture – Musical or Comedy",
            "category": "best-motion-picture-musical-or-comedy",
            "year": "2012",
            "type": "winner"
          },
          {
            "name": "Best Supporting Actress",
            "category": "best-supporting-actress-motion-picture",
            "year": "2012",
            "type": "nominee"
          }
        ]
      },
      {
        "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-id": "bafta",
        "name": "BAFTA",
        "year": "2012",
        "nominations": 1,
        "wins": 3,
        "image": {
          "width": 170,
          "height": 70,
          "link": "http://static3.popyoular-img.com/award-images/award-bafta-170x70.png"
        },
        "winner-description": "Winner of Best Film, Best Actor in a Leading Role and Best Direction",
        "nominee-description": "Nominated for Best Actress in a Leading Role",
        "short-description": "Bafta Winner",
        "award-details": [
          {
            "name": "Best Film",
            "category": "best-film",
            "year": "2012",
            "type": "winner"
          },
          {
            "name": "Best Actress in a Leading Role",
            "category": "best-actress-leading-role",
            "year": "2012",
            "type": "nominee"
          },
          {
            "name": "Best Actor in a Leading Role",
            "category": "best-actor-leading-role",
            "year": "2012",
            "type": "winner"
          },
          {
            "name": "Best Direction",
            "category": "best-direction",
            "year": "2012",
            "type": "winner"
          }
        ]
      }
  ]
}

Awards/Natural language description and translations

TBD