GuidesAPI ReferenceDiscussions
Guides

Images

This page details how images are handled within Content API

Suggest Edits

Feature Images

We provide a special type of image that represents the story, called the "feature image". You may wish to use this feature image for thumbnail or header image purposes on your website.

For Atom and RSS users we provide this feature image in both the media:thumbnail element, for easy access (example below):

<media:thumbnail url="https://content.assets.pressassociation.io/2017/06/21215207/PA-31006423-Cropped.jpg?rect=0,0,3000,1687&ext=.jpg" width="1920" height="1080"/>

<media:thumbnail url="https://content.assets.pressassociation.io/2016/08/18074456/fb4e778d5118b86f5ab43af56538ac0c-1920x1080.jpg" width="1920" height="1080"/>

{
        "featureimage": {
          "type": "picture",
          "headline": "1933 Mercedes-Benz 38",
          "description_text": "1933 Mercedes-Benz 380 at the 2015 Concorso d'Eleganza, Lake Como, Italy (Matt Kimberley/PA)",
          "byline": "Superdesk Admin",
          "renditions": {
            "3x2": {
              "href": "https://content.assets.pressassociation.io/20160518/e7db161aa0ac10559171c400a9147fab526fe9c5bd15d26bd1413bb683dfaa9d.jpg",
              "mimetype": "image/jpeg",
              "poi": {
                "x": 1151,
                "y": 684
              }
            },
            "16x9": {
              "href": "https://content.assets.pressassociation.io/20160518/39c0f9bf5ac7070ce74072dd49a14a6a9c14eeeadc51402139087646c2abf1e7.jpg",
              "mimetype": "image/jpeg",
              "poi": {
                "x": 1151,
                "y": 506
              }
            },
            "4x3": {
              "href": "https://content.assets.pressassociation.io/20160518/9c191bc19b7a20120a0b84590de728372e6714766e1071b4203b3e33c770c367.jpg",
              "mimetype": "image/jpeg",
              "poi": {
                "x": 948,
                "y": 684
              }
            },
            "1x1": {
              "href": "https://content.assets.pressassociation.io/20160518/c3e58da0e2cac3734b817160046506b6bb82a845ebc17ed4151b5480d4a232e7.jpg",
              "mimetype": "image/jpeg",
              "poi": {
                "x": 594,
                "y": 684
              }
            },
            "original": {
              "href": "https://content.assets.pressassociation.io/20160518/7b9db5405a23bdd31209be40a1d97ff46e62c86bea1818d26a87b99c823c49c3.jpg",
              "mimetype": "image/jpeg",
              "height": 1181,
              "width": 1772,
              "poi": {
                "x": 1151,
                "y": 684
              }
            }
          }
}

and also as the first item in the media:group list should you wish to access additional image metadata or renditions.

<media:thumbnail url="https://content.assets.pressassociation.io/2017/06/21212034/PA-31469571-Cropped.jpg?rect=0,0,3500,1969&amp;ext=.jpg" width="3500" height="1969"/>
<media:group>
  <media:content url="https://content.assets.pressassociation.io/2017/06/21212034/PA-31469571-Cropped.jpg" type="image/jpeg" width="3500" height="1969">
    <media:category scheme="urn:pa:media:rendition">original</media:category>
    <pa:poi x="1800" y="903"/>
  </media:content>
  <media:content url="https://content.assets.pressassociation.io/2017/06/21212034/PA-31469571-Cropped.jpg?rect=0,0,3500,1969&amp;ext=.jpg" type="image/jpeg" width="3500" height="1969">
    <media:category scheme="urn:pa:media:rendition">16x9</media:category>
  </media:content>
  <media:content url="https://content.assets.pressassociation.io/2017/06/21212034/PA-31469571-Cropped.jpg?rect=481,0,2625,1969&amp;ext=.jpg" type="image/jpeg" width="2625" height="1969">
    <media:category scheme="urn:pa:media:rendition">4x3</media:category>
  </media:content>
  <media:content url="https://content.assets.pressassociation.io/2017/06/21212034/PA-31469571-Cropped.jpg?rect=306,0,2953,1969&amp;ext=.jpg" type="image/jpeg" width="2953" height="1969">
    <media:category scheme="urn:pa:media:rendition">3x2</media:category>
  </media:content>
  <media:content url="https://content.assets.pressassociation.io/2017/06/21212034/PA-31469571-Cropped.jpg?rect=0,22,3500,1750&amp;ext=.jpg" type="image/jpeg" width="3500" height="1750">
    <media:category scheme="urn:pa:media:rendition">2x1</media:category>
  </media:content>
  <media:content url="https://content.assets.pressassociation.io/2017/06/21212034/PA-31469571-Cropped.jpg?rect=809,0,1969,1969&amp;ext=.jpg" type="image/jpeg" width="1969" height="1969">
    <media:category scheme="urn:pa:media:rendition">1x1</media:category>
  </media:content>
  <media:title>The Missing People Choir</media:title>
  <media:description>The choir made it through to the competition’s final stages (Tom Dymond/Syco/Thames/PA)</media:description>
  <media:text>The choir made it through to the competition's final stages.</media:text>
  <media:copyright></media:copyright>
  <media:credit></media:credit>
  <media:category scheme="urn:pa:media:association">featureimage</media:category>
</media:group>
<media:content url="https://content.assets.pressassociation.io/2017/06/21211645/PA-30933927.jpg" type="image/jpeg" width="3500" height="2333">
  <media:title>Britain’s Got Talent 2016</media:title>
  <media:description>Missing People Choir audition for BGT (Tom Dymond/Syco/Thames/PA)</media:description>
  <media:text>Missing People Choir audition for BGT.</media:text>
  <media:copyright></media:copyright>
  <media:credit>Press Association Images</media:credit>
  <media:category scheme="urn:pa:media:rendition">original</media:category>
  <media:category scheme="urn:pa:media:association">embedded5933</media:category>
</media:content>
<media:content url="https://content.assets.pressassociation.io/2017/06/21211919/DSC_3838.jpg" type="image/jpeg" width="4500" height="2994">
  <media:title>The Missing People Choir</media:title>
  <media:description>The Christmas album will feature 10 charity choirs (James Hawkins Music/PA)</media:description>
  <media:text>The Christmas album will feature 10 charity choirs.</media:text>
  <media:copyright></media:copyright>
  <media:credit></media:credit>
  <media:category scheme="urn:pa:media:rendition">original</media:category>
  <media:category scheme="urn:pa:media:association">embedded5935</media:category>
</media:content>

<media:thumbnail url="https://content.assets.pressassociation.io/2017/06/21212034/PA-31469571-Cropped.jpg?rect=0,0,3500,1969&amp;ext=.jpg" width="3500" height="1969"/>
<media:group>
  <media:content url="https://content.assets.pressassociation.io/2017/06/21212034/PA-31469571-Cropped.jpg" type="image/jpeg" width="3500" height="1969">
    <media:category scheme="urn:pa:media:rendition">original</media:category>
    <pa:poi x="1800" y="903"/>
  </media:content>
  <media:content url="https://content.assets.pressassociation.io/2017/06/21212034/PA-31469571-Cropped.jpg?rect=0,0,3500,1969&amp;ext=.jpg" type="image/jpeg" width="3500" height="1969">
    <media:category scheme="urn:pa:media:rendition">16x9</media:category>
  </media:content>
  <media:content url="https://content.assets.pressassociation.io/2017/06/21212034/PA-31469571-Cropped.jpg?rect=481,0,2625,1969&amp;ext=.jpg" type="image/jpeg" width="2625" height="1969">
    <media:category scheme="urn:pa:media:rendition">4x3</media:category>
  </media:content>
  <media:content url="https://content.assets.pressassociation.io/2017/06/21212034/PA-31469571-Cropped.jpg?rect=306,0,2953,1969&amp;ext=.jpg" type="image/jpeg" width="2953" height="1969">
    <media:category scheme="urn:pa:media:rendition">3x2</media:category>
  </media:content>
  <media:content url="https://content.assets.pressassociation.io/2017/06/21212034/PA-31469571-Cropped.jpg?rect=0,22,3500,1750&amp;ext=.jpg" type="image/jpeg" width="3500" height="1750">
    <media:category scheme="urn:pa:media:rendition">2x1</media:category>
  </media:content>
  <media:content url="https://content.assets.pressassociation.io/2017/06/21212034/PA-31469571-Cropped.jpg?rect=809,0,1969,1969&amp;ext=.jpg" type="image/jpeg" width="1969" height="1969">
    <media:category scheme="urn:pa:media:rendition">1x1</media:category>
  </media:content>
  <media:title>The Missing People Choir</media:title>
  <media:description>The choir made it through to the competition’s final stages (Tom Dymond/Syco/Thames/PA)</media:description>
  <media:text>The choir made it through to the competition's final stages.</media:text>
  <media:copyright></media:copyright>
  <media:credit></media:credit>
  <media:category scheme="urn:pa:media:association">featureimage</media:category>
</media:group>
<media:content url="https://content.assets.pressassociation.io/2017/06/21211645/PA-30933927.jpg" type="image/jpeg" width="3500" height="2333">
  <media:title>Britain’s Got Talent 2016</media:title>
  <media:description>Missing People Choir audition for BGT (Tom Dymond/Syco/Thames/PA)</media:description>
  <media:text>Missing People Choir audition for BGT.</media:text>
  <media:copyright></media:copyright>
  <media:credit>Press Association Images</media:credit>
  <media:category scheme="urn:pa:media:rendition">original</media:category>
  <media:category scheme="urn:pa:media:association">embedded5933</media:category>
</media:content>
<media:content url="https://content.assets.pressassociation.io/2017/06/21211919/DSC_3838.jpg" type="image/jpeg" width="4500" height="2994">
  <media:title>The Missing People Choir</media:title>
  <media:description>The Christmas album will feature 10 charity choirs (James Hawkins Music/PA)</media:description>
  <media:text>The Christmas album will feature 10 charity choirs.</media:text>
  <media:copyright></media:copyright>
  <media:credit></media:credit>
  <media:category scheme="urn:pa:media:rendition">original</media:category>
  <media:category scheme="urn:pa:media:association">embedded5935</media:category>
</media:content>

If you do not wish to be returned media:group or media:content extended elements from the Atom or RSS response you can add the excludeExtendedMediaRss=true option to your API requests. By passing this option only the media:thumbnail element will be returned in the XML response.

curl https://content.api.pressassociation.io/v1/service/paservice:sport/item?apikey=<API KEY>&accept=atom&excludeExtendedMediaRss=true

All features images support dynamic resizing simply by adding a "w" query parameter to the URL.

The following example demonstrates how a 1280 pixel width image can be requested:

curl https://content.assets.pressassociation.io/2016/08/18074456/fb4e778d5118b86f5ab43af56538ac0c-1920x1080.jpg?w=1280

Image Types

Within Content API there are two type of image; associated and embedded. We'll cover off each of these image types in more detail below.

Associated Images

Associated images are available for direct download and can have multiple crop renditions provided (e.g. 1x1, 4x3, 16x9).

{
  "associations": {
    "featureimage": {
      "type": "picture",
      "headline": "GBBO",
      "description_text": "GBBO (Love Productions/Channel 4/Mark/PA)",
      "body_text": "GBBO.",
      "byline": "",
      "renditions": {
        "original": {
          "href": "https://content.assets.pressassociation.io/2017/06/21215207/PA-31006423-Cropped.jpg",
          "mimetype": "image/jpeg",
          "height": 1688,
          "width": 3000,
          "poi": {
            "x": 1537,
            "y": 867
          }
        },
        "16x9": {
          "href": "https://content.assets.pressassociation.io/2017/06/21215207/PA-31006423-Cropped.jpg?rect=0,0,3000,1687&ext=.jpg",
          "mimetype": "image/jpeg",
          "height": 1687,
          "width": 3000
        },
        "4x3": {
          "href": "https://content.assets.pressassociation.io/2017/06/21215207/PA-31006423-Cropped.jpg?rect=412,0,2250,1687&ext=.jpg",
          "mimetype": "image/jpeg",
          "height": 1687,
          "width": 2250
        },
        "3x2": {
          "href": "https://content.assets.pressassociation.io/2017/06/21215207/PA-31006423-Cropped.jpg?rect=262,0,2531,1687&ext=.jpg",
          "mimetype": "image/jpeg",
          "height": 1687,
          "width": 2531
        },
        "2x1": {
          "href": "https://content.assets.pressassociation.io/2017/06/21215207/PA-31006423-Cropped.jpg?rect=0,113,3000,1500&ext=.jpg",
          "mimetype": "image/jpeg",
          "height": 1500,
          "width": 3000
        },
        "1x1": {
          "href": "https://content.assets.pressassociation.io/2017/06/21215207/PA-31006423-Cropped.jpg?rect=694,0,1687,1687&ext=.jpg",
          "mimetype": "image/jpeg",
          "height": 1687,
          "width": 1687
        }
      }
    }
  }
}

<media:thumbnail url="https://content.assets.pressassociation.io/2017/06/21212034/PA-31469571-Cropped.jpg?rect=0,0,3500,1969&amp;ext=.jpg" width="3500" height="1969"/>
<media:group>
  <media:content url="https://content.assets.pressassociation.io/2017/06/21212034/PA-31469571-Cropped.jpg" type="image/jpeg" width="3500" height="1969">
    <media:category scheme="urn:pa:media:rendition">original</media:category>
    <pa:poi x="1800" y="903"/>
  </media:content>
  <media:content url="https://content.assets.pressassociation.io/2017/06/21212034/PA-31469571-Cropped.jpg?rect=0,0,3500,1969&amp;ext=.jpg" type="image/jpeg" width="3500" height="1969">
    <media:category scheme="urn:pa:media:rendition">16x9</media:category>
  </media:content>
  <media:content url="https://content.assets.pressassociation.io/2017/06/21212034/PA-31469571-Cropped.jpg?rect=481,0,2625,1969&amp;ext=.jpg" type="image/jpeg" width="2625" height="1969">
    <media:category scheme="urn:pa:media:rendition">4x3</media:category>
  </media:content>
  <media:content url="https://content.assets.pressassociation.io/2017/06/21212034/PA-31469571-Cropped.jpg?rect=306,0,2953,1969&amp;ext=.jpg" type="image/jpeg" width="2953" height="1969">
    <media:category scheme="urn:pa:media:rendition">3x2</media:category>
  </media:content>
  <media:content url="https://content.assets.pressassociation.io/2017/06/21212034/PA-31469571-Cropped.jpg?rect=0,22,3500,1750&amp;ext=.jpg" type="image/jpeg" width="3500" height="1750">
    <media:category scheme="urn:pa:media:rendition">2x1</media:category>
  </media:content>
  <media:content url="https://content.assets.pressassociation.io/2017/06/21212034/PA-31469571-Cropped.jpg?rect=809,0,1969,1969&amp;ext=.jpg" type="image/jpeg" width="1969" height="1969">
    <media:category scheme="urn:pa:media:rendition">1x1</media:category>
  </media:content>
  <media:title>The Missing People Choir</media:title>
  <media:description>The choir made it through to the competition’s final stages (Tom Dymond/Syco/Thames/PA)</media:description>
  <media:text>The choir made it through to the competition's final stages.</media:text>
  <media:copyright></media:copyright>
  <media:credit></media:credit>
  <media:category scheme="urn:pa:media:association">featureimage</media:category>
</media:group>
<media:content url="https://content.assets.pressassociation.io/2017/06/21211645/PA-30933927.jpg" type="image/jpeg" width="3500" height="2333">
  <media:title>Britain’s Got Talent 2016</media:title>
  <media:description>Missing People Choir audition for BGT (Tom Dymond/Syco/Thames/PA)</media:description>
  <media:text>Missing People Choir audition for BGT.</media:text>
  <media:copyright></media:copyright>
  <media:credit>Press Association Images</media:credit>
  <media:category scheme="urn:pa:media:rendition">original</media:category>
  <media:category scheme="urn:pa:media:association">embedded5933</media:category>
</media:content>
<media:content url="https://content.assets.pressassociation.io/2017/06/21211919/DSC_3838.jpg" type="image/jpeg" width="4500" height="2994">
  <media:title>The Missing People Choir</media:title>
  <media:description>The Christmas album will feature 10 charity choirs (James Hawkins Music/PA)</media:description>
  <media:text>The Christmas album will feature 10 charity choirs.</media:text>
  <media:copyright></media:copyright>
  <media:credit></media:credit>
  <media:category scheme="urn:pa:media:rendition">original</media:category>
  <media:category scheme="urn:pa:media:association">embedded5935</media:category>
</media:content>

<media:thumbnail url="https://content.assets.pressassociation.io/2017/06/21212034/PA-31469571-Cropped.jpg?rect=0,0,3500,1969&amp;ext=.jpg" width="3500" height="1969"/>
<media:group>
  <media:content url="https://content.assets.pressassociation.io/2017/06/21212034/PA-31469571-Cropped.jpg" type="image/jpeg" width="3500" height="1969">
    <media:category scheme="urn:pa:media:rendition">original</media:category>
    <pa:poi x="1800" y="903"/>
  </media:content>
  <media:content url="https://content.assets.pressassociation.io/2017/06/21212034/PA-31469571-Cropped.jpg?rect=0,0,3500,1969&amp;ext=.jpg" type="image/jpeg" width="3500" height="1969">
    <media:category scheme="urn:pa:media:rendition">16x9</media:category>
  </media:content>
  <media:content url="https://content.assets.pressassociation.io/2017/06/21212034/PA-31469571-Cropped.jpg?rect=481,0,2625,1969&amp;ext=.jpg" type="image/jpeg" width="2625" height="1969">
    <media:category scheme="urn:pa:media:rendition">4x3</media:category>
  </media:content>
  <media:content url="https://content.assets.pressassociation.io/2017/06/21212034/PA-31469571-Cropped.jpg?rect=306,0,2953,1969&amp;ext=.jpg" type="image/jpeg" width="2953" height="1969">
    <media:category scheme="urn:pa:media:rendition">3x2</media:category>
  </media:content>
  <media:content url="https://content.assets.pressassociation.io/2017/06/21212034/PA-31469571-Cropped.jpg?rect=0,22,3500,1750&amp;ext=.jpg" type="image/jpeg" width="3500" height="1750">
    <media:category scheme="urn:pa:media:rendition">2x1</media:category>
  </media:content>
  <media:content url="https://content.assets.pressassociation.io/2017/06/21212034/PA-31469571-Cropped.jpg?rect=809,0,1969,1969&amp;ext=.jpg" type="image/jpeg" width="1969" height="1969">
    <media:category scheme="urn:pa:media:rendition">1x1</media:category>
  </media:content>
  <media:title>The Missing People Choir</media:title>
  <media:description>The choir made it through to the competition’s final stages (Tom Dymond/Syco/Thames/PA)</media:description>
  <media:text>The choir made it through to the competition's final stages.</media:text>
  <media:copyright></media:copyright>
  <media:credit></media:credit>
  <media:category scheme="urn:pa:media:association">featureimage</media:category>
</media:group>
<media:content url="https://content.assets.pressassociation.io/2017/06/21211645/PA-30933927.jpg" type="image/jpeg" width="3500" height="2333">
  <media:title>Britain’s Got Talent 2016</media:title>
  <media:description>Missing People Choir audition for BGT (Tom Dymond/Syco/Thames/PA)</media:description>
  <media:text>Missing People Choir audition for BGT.</media:text>
  <media:copyright></media:copyright>
  <media:credit>Press Association Images</media:credit>
  <media:category scheme="urn:pa:media:rendition">original</media:category>
  <media:category scheme="urn:pa:media:association">embedded5933</media:category>
</media:content>
<media:content url="https://content.assets.pressassociation.io/2017/06/21211919/DSC_3838.jpg" type="image/jpeg" width="4500" height="2994">
  <media:title>The Missing People Choir</media:title>
  <media:description>The Christmas album will feature 10 charity choirs (James Hawkins Music/PA)</media:description>
  <media:text>The Christmas album will feature 10 charity choirs.</media:text>
  <media:copyright></media:copyright>
  <media:credit></media:credit>
  <media:category scheme="urn:pa:media:rendition">original</media:category>
  <media:category scheme="urn:pa:media:association">embedded5935</media:category>
</media:content>

When requesting an associated image you can also pass a width and height query parameter to dynamically resize the image to your specific requirements (please note this is not available across all content services, please review per-service documentation).

The following HTTP request demonstrates an image being requested with specific height (h) and width (w) query parameters. Please note depending on the crop rendition this may result in distorted images.

curl https://content.assets.pressassociation.io/20160518/7b9db5405a23bdd31209be40a1d97ff46e62c86bea1818d26a87b99c823c49c3.jpg?w=1280&h=720

The following HTTP request demonstrates an image being request with specific height (h) and a dynamic width.

This type of request will ensure that the images returned have the desired width:

curl https://content.assets.pressassociation.io/20160518/7b9db5405a23bdd31209be40a1d97ff46e62c86bea1818d26a87b99c823c49c3.jpg?w=1280

Embedded Images

Embedded images exist within the HTML body of a content item. To ensure an optimum experience across devices these images support HTML5 srcset attributes.

The following code snippet show how the srcset attribute is used:

<figure>
  <img src="https://content.assets.pressassociation.io/20160518/96587ed5d67c34bee5cbce0783273e43ae5bddacd1d1b601b64636cc7f033c31.jpg" alt="2015 Concorso d'Eleganza, Lake Como, Italy (Matt Kimberley/PA)" srcset="//content.assets.pressassociation.io/20160518/42c497ea2b5c1f392f7e3152696cb8c0077566599b2ae538d5a825c61ffff040.jpg 360w, //content.assets.pressassociation.io/20160518/b1cd9eaa780bf1b57e7822d5263fa762413ef68d3cfe1764670b80b71639414a.jpg 720w, //content.assets.pressassociation.io/20160518/0a82ffd962503e5b364231d724759931a020768ad49a618f9fd213ea1ffe279d.jpg 1080w">
  <figcaption>2015 Concorso d'Eleganza, Lake Como, Italy (Matt Kimberley/PA</figcaption>
</figure>

All embedded images are also available for direct download within the associations (or media) array.

Disabling HTTPS

By default Content API returns all image rendition URLs as HTTPS (secure) URLs, if your system does not support HTTPS you can pass the disableSecureRenditionUrls option to specifically return non-secure (HTTP) URLs.

Note: It is recommended to use the default HTTPS URLs.

An example of such a request is as follows:

curl https://content.api.pressassociation.io/v1/service/paservice:sport/item?apikey=<API KEY>&accept=atom&=&disableSecureRenditionUrls=true

Exclude Extended MediaRSS (Atom and RSS)

By default Content API returns multiple image renditions at different crop ratios. If you do not wish to utilise these additional renditions and would prefer to use a simple 16x9 feature image you can pass the excludeExtendedMediaRss=true option to only return the media:thumbnail image (all additional media:content/media:group elements will be excluded).

An example of such a request is as follows:

curl https://content.api.pressassociation.io/v1/service/paservice:sport/item?apikey=<API KEY>&accept=atom&=&excludeExtendedMediaRss=true

Dynamic Image Sizing

Content API offers the ability to return images at the exact width or height that you require. This can be achieved simply passing a width (w) or height (h) query parameter when requesting an image.

The following example demonstrates how a feature image can be returned with a width of 360 pixels.

curl https://content.assets.pressassociation.io/2016/12/13113252/1a6ff94940b24088dde608a23d79402c-1920x1080.jpg?w=360

Updated about 5 years ago