NPR logo Coming Soon To The API: Collections And Image Crops


Coming Soon To The API: Collections And Image Crops

Here's a heads up for all API users: in March we will add some new elements to our NPRML output that you might be interested in.


On March 2nd, the current image element will be changed to include information about the various crops available for the image. The current image XML won't change, but we'll add some new metadata for various crop sizes for images. Up to this point, our image elements contained a URL in the "src" attribute for the primary crop for the image:

<image id="133849355" type="primary" width="200" src="" hasBorder="false">

Image elements also contained a subelement for the enlargement URL if one existed:

<enlargement src="">

We will continue to include these fields in our NPRML output.

But these aspect ratios might not work for your applications. We'll add to the image element a "crop" subelement with a variety of different aspect ratios as selected by editorial:

<crop type="square" src="" height="440" width="440"/>

The current crop types are:

  • standard: 4:3
  • square: 1:1
  • wide: 16:9
  • brick: 300:138
  • alt promo: 4:3
  • vertical: 3:4
  • custom and enlargements can be any aspect ratio


You might have noticed the variety of "end of the year" lists produced by NPR every December. Our music team puts together lists like this one from All Songs Considered throughout the year and we are starting to add lists to news pages like this one from the Science Desk. We are constantly adding new types of lists, but at their heart they are simply a collection of other assets (images, audio, video, etc.) that are ordered along with some editorial text describing them. We will be adding more information about these collections of assets in our API so outside applications can start taking advantage of the rich content associated with them.

Up to this point in the API we have included all the assets that appear in collections, but we never included any information about how the editors grouped and displayed the data, nor did we include any of the editorial text describing the assets. On March 16th we will be adding two new elements: <collection> and <member> to our API.

The <collection> element will include two attributes:

type: At this point the only type of collection we have defined is a "list" but we reserve the right to add new types going forward.

displayType: We are planning to have a variety of ways to display these collections of assets and this attribute is intended to give you a sense of how the list is being displayed. At this point our display types include "Music Classic Playlist" and "Simple List" but we are planning a variety of book lists in the near future.

The <collection> element will include a number of subelements:

<title>: CDATA enclosed text and some simple HTML mark up.

<introText> : CDATA enclosed text and some simple HTML mark up.

<member> : a pointer via a "refId" attribute to the complete member element, with the following additional attributes:

num: The order of this member in the collection as a whole

label: If the member has a separate label within the list, such as a number (Think of a David Letterman style top 10 list that counts backward), then it will be listed here. Otherwise the label will be "none" indicating that just the member title is displayed.

The <member> element will include a number of subelements as well:

<title>: CDATA enclosed text and some simple HTML mark up.

<memberText> : CDATA enclosed text and some simple HTML mark up.

References to the various assets in the member such as images, audio, video, links, etc.

The subelements in a <member> element will be ordered with a "num" attribute in the order in which they appear (going from the top left to bottom right) in the list itself on Image reference elements will include an attribute "crop" to indicate which image crop was selected by the editor to appear in the list.

An example might be helpful here. Here is a member displayed on a music classic playlist:

It would have the following XML:

<member id="132652688">

<image refId="132652709" crop="square" num="1"/>
<title num="2"><![CDATA[Nat Geo]]</title>
<audio refId="132652704" num="3"/>
<song refId="132649319" num="4"/>
<memberText num="5"><![CDATA[<p><em><strong>Advisory: </strong>This song contains explicit language not suitable for all audiences.</em></p>]]</memberText>
<link refId="132652740" num="6"/>


Each of the assets such as the image or audio will be found elsewhere in the same API output and can be found by using the refId attribute.

We hope that these new elements allow users of our API to take advantage of more of our rich editorial content.

Joanne Garlow is the lead developer for NPR's Digital Media Software team