Images

One of the most frequently asked questions of the API team is how to get cover images. This document describes how to locate the URL of a cover image or author photo.

Image URLs

The "icon" rel

The Internet Assigned Numbers Authority (IANA) defines the set of valid link relations. One of those, icon, is what we've chosen to use to represent the image associated with a title, work or author.

Every object returned by the API has a _links element that is an array of link objects. Each of those link objects has a rel element. The object with the rel of icon contains the URL of the cover image or author photo in its href element.

Note that these image URLs are constructed by applying the object's ID to a template and do not depend on the existence of an actual file on the image server's file system.

Cover image example

/domains/PRH.US/titles/9781101946343

        "_links": [
          ...
          {
            "rel": "icon",
            "href": "https:\/\/images.randomhouse.com\/cover\/9781101946343",
            "method": "GET",
            "parameters": null
          },
          ...
        ],

Author photo example

/domains/PRH.US/authors/8240

        "_links": [
          ...
          {
            "rel": "icon",
            "href": "https:\/\/images.randomhouse.com\/author\/8240",
            "method": "GET",
            "parameters": null
          },
          ...
        ],

Work example

Works are themselves a collection of Titles (see Works and ISBNs) and thus don't have their own cover images. However when you access a work record with a domain specified (see Domains), we can use the frontlistiest rules (see Frontlistiest) to identify a representative ISBN.

/domains/PRH.US/works/258951

        "_links": [
          ...
          {
            "rel": "icon",
            "href": "https:\/\/images.randomhouse.com\/cover\/9781101946343",
            "method": "GET",
            "parameters": null
          }
        ],

Other images

Promo images

Sometimes Titles have promotional images other than their cover image that are available on the Penguin Random House web servers. These are served by the /promoimages subresource.

/domains/PRH.US/titles/9780307269768/promoimages

    "promoImages": [
      {
        "promoImageId": 3159,
        "category": "5",
        "contributor": null,
        "copyright": null,
        "imageName": "9780307269768_1393.gif",
        "videoLink": null,
        "photoCredit": null,
        "photoDate": null,
        "photoCaption": null,
        "_links": [
          
        ],
        "_embeds": null
      },
      {
        "promoImageId": 3160,
        "category": "5",
        "contributor": null,
        "copyright": null,
        "imageName": "9780307269768_1394.gif",
        "videoLink": null,
        "photoCredit": null,
        "photoDate": null,
        "photoCaption": null,
        "_links": [
          
        ],
        "_embeds": null
      },
      {
        "promoImageId": 3158,
        "category": "5",
        "contributor": null,
        "copyright": null,
        "imageName": "9780307269768_1392.gif",
        "videoLink": null,
        "photoCredit": null,
        "photoDate": null,
        "photoCaption": null,
        "_links": [
          
        ],
        "_embeds": null
      }
    ],

TK: how to construct URLs for these images

Other media types

There are some media types (such as video) that we don't host directly on Penguin Random House servers and which may be represented in the system as web links which can be accessed via the /weblinks subresource. For a complete list of the different types of links that can be returned see the Web link attrs document.

Image existence

The image URLs that are returned in the links array are constructed without knowledge of whether an actual image exists or not. If you need to know ahead of time whether an image exists for a particular ISBN or Author ID, there are a couple of ways to do that.

The "hasCoverImage" element

Some views contain a boolean element called hasCoverImage. This element is set to true whenever the database has a record of a cover image existing for that ISBN. If this element is false, then no such record was found in the database.

/domains/PRH.US/works/258951/views/product-display

          "hasCoverImage": true,

Note that the process which updates the database from the file system works but may not be perfect. If you find an instance where the API returns true but no image is found (or vice versa), please notify us at api@penguinrandomhouse.com so that we can file a bug ticket for it.

The "hideBooksWithNoCover" parameter

If you only want to see Title records that have a cover image, you can use the hideBooksWithNoCover parameter. When this parameter is set to true, a join is added to the query that restricts the titles being considered to only those that have a record of a cover image.

To see this working, we can issue a pair of queries, first without the parameter and then with the parameter. We can use the recordCount element in the response to see the impact of the filter.

/domains/PRH.US/titles?catUri=/fantasy

  "recordCount": 5832,

/domains/PRH.US/titles?catUri=/fantasy&hideBooksWithNoCover=true

  "recordCount": 5456,