News API v1.5 - Developers' Guide

Back to top

Endpoints

The News API provides a number of endpoints, exposing content published by PA Editorial. The content exposed by these endpoints is determined by entitlements assigned to the APIKEY used in the request. 

Resource types

News API endpoints respond with various types of resource object, rendered appropiately in the accepted response formats. A summary of these types follows: 

Query Parameters

The News API supports the following query parameters:

accept

The accept parameter is used, as an alternative to the Accept HTTP header, in order to change the response format of the API. By default, the API responds in JSON.

If provided, the accept parameter supercedes any value specified by the Accept HTTP header. This is because we have observed that many client libraries and applications, including low-level ones such as curl, will specify Accept: */* if the developer does not specify their own headers - which would cause the News API to respond with JSON (which is its preferred response format) regardless of the value of the accept parameter.

callback

The callback parameter can be used by JSON-P clients in order to set the callback function. When set, the response format of the API is changed to Content-Type: application/javascript

The callback parameter has no effect if the requested response format is not JSON.

query

The query parameter is used for specifying the search terms to be used when filtering the results. It supports boolean operators, quoted phrases, parentheses, and the negation of terms by preceding them with a minus sign.

The parameter will only be effective if search capability is enabled for the APIKEY in use, and if supported by the endpoint called e.g. assets

A string query is a plain text search string composed of terms, phrases, and operators that can be easily composed by end users typing into an application search box. For example, 'cat AND dog' is a string query for finding documents that contain both the term 'cat' and the term 'dog'.

The search engine provides a robust ability to generate complex queries. The following are some examples:

(cat OR dog) NEAR vet

at least one of the terms cat or dog within 10 terms of the word vet

dog NEAR/30 vet

the word dog within 30 terms of the word vet

cat -dog

the word cat where there is no word dog.

For more details, see the Query Grammar page.

date

The date filter criteria restricts the results to articles most recently published on the specified calendar day.

Dates should be specified in CCYY-MM-DD format. Optionally, a timezone can be specified e.g. 2014-06-03+01:00 in order to clarify in which timezone the date should be interpreted, i.e. when midnight is considered to be. If no timezone offset is specified, the date is assumed to be Europe/London local time for the specified day - matching the Press Association's news cycle.

from/to

The from and to parameters provide fine-grained control over the date and time range filter for the search results. Both must be specified as ISO 8601 formatted datetimes, in the form CCYY-MM-DDThh:mm:ss.sssZ

As with date, if no timezone is specified then Europe/London local time is assumed. Where this is invalid (a time is specified but the clocks would have jumped forwards over that time), the filter will be rejected with an error. Where the time is ambiguous (i.e. the clocks go backwards and the same clock time appears twice on the given day) then the earlier time is assumed.

Note that from is inclusive, but to is exclusive. This enables you to easily search on day boundaries by setting e.g. from=2014-06-03T00:00:00+01:00 and to=2014-06-05T00:00:00+01:00 and receive only items published on 3rd and 4th of June, and none published at or after midnight on the 5th, without having to set to=2014-06-04T23:59:59.999+01:00 and having to worry about millisecond precision for the end criteria.

when

The when parameter is an alternative time-based banding criteria that recognises that searches for news are generally biased towards recency. when offers the following time periods:

The calendar days used are relative to Europe/London local time, to match the Press Association's news cycle.

The when parameter may be returned as a facet in search-style responses (see below).

tag

The tag constraint is used to filter search results based on various types of classification, including (but not limited to) the traditional PA topic schemes. Multiple tags can be specified by repeating the constraint, in which case only articles that match both tags will be returned (i.e. a logical AND). More complex searching based on tag can be performed by including it as a term in the query parameter (e.g. to search for Politics articles that are not also tagged Environment, you can do query=tag:patopic:POLITICS -tag:patopic:ENVIRONMENT). See the query grammar for more details.

The tag parameter may be returned as a facet in search-style responses (see below).

limit

The limit and offset parameters are used to scroll/page through the set of available results for a given search.

limit affects the number of results returned in each page. In most cases the default (if no limit is specified) this will be 10 results; this can be altered up to a maximum of 100. Setting it to a value greater than 100 will result in an error response.

In the endpoints that return a single package or schedule, the limit will default automatically to the number of items in that collection; which may be more than 10. An alternative limit can still be specified.

offset

The offset value affects where in the result set the page starts. By default (if no offset is specified) this will be 1, i.e. the first available result. This can be altered up to a maximum of 500. Setting it to a value greater than 500 will result in an error response.

sortby

By default, search results are returned in newest-first order. This can be changed via the sortby parameter. Permitted values are:

facets

The facets parameter is used to enable facet information in a search response, such as from an assets list call. By default no facets are calculated, since it has an impact on search time. Facets are calculated for the total set of results matched by the current call, providing values that can be used to drill-down further in the next call. Each facet returns the top 10 (or less) most frequently occuring values of that facet type. The id of each facet value returned may be used as a query parameter value, to return the set counted by the facet. Possible facet values are:

crop

The crop parameter is used to enable extra point-of-interest and crop rectangle information for each image of every asset or story. This may be used to facilitate client side cropping of the downloaded full size images. Possible crop values are POI, SQUARE, THREE_TO_TWO, FOUR_TO_THREE, SIXTEEN_TO_NINE, FIVE_TO_FOUR, TWO_TO_ONE, SEVEN_TO_TWO.

When passing multiple values to the parameter, please separate with commas but no spaces e.g. crop=POI,SQUARE

Response formats

The News API offers the following response formats:

Regardless of format, there are 3 kinds of response that can be provided based upon the endpoint. Furthermore, the level of detail provided in each response can vary according to certain defaults, or overriding query parameters. Generally a list response will provide a feed containing a summary of each item, whilst an individual fetch will provide a feed containing a full item.

Where assets are provided, the level of detail for each asset varies across the endpoints in order to cater to the most likely use case for that endpoint and format. For example, the ATOM response for a package provides a feed of full size assets by default, for convenience.

List response

In a list response, the items are returned as a JSON array, or as an ATOM or RSS feed. List responses are paginated but do not include facets.

Lists are for short finite sets of results - be that a list of options, or an editorially curated list of content on a given theme.

Search response

Search responses look like list responses at a high level, but contain extra information in order to allow for paging through the results. The search response is used where the potential number of results is not bounded.

Search result response formats include OpenSearch information in order to assist the API client to page through the result set, and a list of facets - a breakdown of subsequent search terms along with counts, in order to provide guided navigation of the result set.

Summary asset response

The summary asset response is used in a context where the API client is expected to be searching or browsing for a single item that they will eventually consume. It provides a headline and abstract for each story, along with its classification metadata, and a thumbnail image if available.

Full asset response

The full asset response contains all of the same metadata as the summary response, but also includes the full body text of the article, and references all of the attached media items rather than just one.

Facets

The News API provides facets in all search-style responses. The facets provide a breakdown of the results of the search into how many of those results also match the given term, providing the API consumer with guided navigation to help refine the search further to find the content they are looking for. Currently, facets are provided for both the when and tag search constraints.

For when, the News API returns each of the bands that contains at least one search result, with a count of how many results fall into that band.

For tag, it returns a list (maximum of 10), in decreasing order of popularity, of the tags used across the result set.

Facets are available in all three response formats. In JSON, they look like this:

"facets": {
  "tag" : {
    "terms" : [
      { "id":"pacategory:HHH", "name":"General News", "count":2532 }, 
      { "id":"patopic:POLITICS", "name":"Politics", "count":1234 }, 
      { "id":"patopic:COMMONS", "name":"Commons", "count":973 } 
    ]
  }  
}

In the XML formats (ATOM and RSS), they appear like this:

<pa:facets>
   <pa:facet field="tag" term="pacategory:HHH" name="General News" count="2532"/>
   <pa:facet field="tag" term="patopic:POLIICS" name="Politics" count="1234"/>
   <pa:facet field="tag" term="patopic:COMMONS" name="Commons" count="973"/>
 </pa:facets>

Assets and Stories

In the News API an asset is an individually published article containing at least one 'page' within the content. The number of pages may grow over time, as the article develops. Also, editorial may add images and video to the asset to further enrich the content, and may even curate a collection of social media to go with the article. There are four main types of asset:

• Quickfire 'snap' articles, which are used for breaking news and developments in a story. They contain only a short paragraph, no headline, and minimal metadata e.g. tags. They do not belong to a story however.
• Regular 'asset' articles that have at least one page, a headline and a rich set of metadata such as tags.They belong to a story.
• Sidebar 'asset' articles that are in themselves fully developed with for a story. They belong to their own story, but also are children to assets in a parent story. 
• Occasional 'advisory' articles that serve editorial advisory purposes, such as detailing news coverage. These look like regular assets but are always embargoed. These will not tend to have leads.

Over time an asset may be revised as the overall 'story' develops. This is called a writethrough or lead. When this happens a new asset is generated with a brand new unique id, rather than replacing the previous asset. In the new 'lead' asset, the lead number is incremented by one to indicate that it is the nth successor to a previous asset. Not all assets will have leads, depending on how the story evolves over the editorial day.

Assets are exposed individually by the /assets endpoint, but also as members of feeds, packages and schedules - which are collections of assets.

Gallery assets

There are also gallery assets, effectively their own type, which are used to convey a curated collection of media on a chosen theme, such as the past week in photos. There is a dedicated set of endpoints it discover and use these:

/galleries

Returning a list of galleries published so far, and:

/galleries/{gallery id}

Returning a specific gallery, with all of its metadata and media. Galleries don't adhere to the usual rules of having a story, so the response is somewhat specialised.

Stories

Regular assets and sidebars always belong to a 'story'. The story is the grouping of all of the lead assets published so far, and has a unique id of it's own. As each new lead asset is published with a new id, the story id remains the same. All of the media attached to an asset is actually attached to the story, so will remain in place for each lead as it is published. Therefore each asset that belongs to the same story will always expose the same selection of media, and potential link to a social collection.

It is possible to discover the story that an asset belongs to by looking at the asset rendition as follows:

In JSON, the story id is found in the story.id key. Also note that the media list lives in the story object, not the root of the asset:

{
   "kind":"asset",
   "id":"20f3d9b2-a6dc-46b9-a6a8-b3021e06200a",
   "story":{
      "id":"b253ea93-6a56-4db1-86f9-ffba5818d329",
      "media":[
         {
            "kind":"picture",
            "id":"2.23790501",
            "title":"karen",
            "summary":"Karen Buckley, 24, was murdered by Alexander Pacteau (Crown Office/PA)",
            "credit":"Torch One time usage images",
            "renditions":{
               "thumb":{
                  "width":84,
                  "height":127,
                  "size":5630,
                  "href":"https://news.static.press.net/v2/image/thumbnail/0214b5b46cb0f9b98cfae0724f2f66d1/2.23790501.jpg"
               },
               "preview":{
                  "width":337,
                  "height":511,
                  "size":47969,
                  "href":"https://news.static.press.net/v2/image/preview/e9359c81cde31f4c1b003226ea47f701/2.23790501.jpg"
               },
               "full":{
                  "width":2304,
                  "height":3492,
                  "size":752716,
                  "href":"https://news.static.press.net/v2/image/production/d305b981d806bb8d217c3d3457909bf6/2.23790501.jpg"
               }
            }
         }
      ],
      "meta":{
         "pictureCount":"6",
         "videoCount":"0",
         "curatedSocialAttached":"false"
      }
   },
   ...
}

In the Atom and RSS, the story is indicated by an Atom link element in the entry, pointing to the /stories endpoint. The rel attribute will be "story":

<link rel="story" href="http://news.api.press.net/v1.5/stories/387e7242-6cee-496c-8350-117689c52990" />

The story itself can be fetched using the story endpoint, passing the story id or using the link provided e.g.

/stories/{story id}

This endpoint returns a simple summary of the last published lead for the story, and all of the current media.

Assets in packages and schedules

When consuming the response for a package or schedule, you will see that assets have been returned (in either summary or full form depending on the type). It is important to not that in these responses you are automatically provided the last published lead from the story of each asset in the collection. Effectively the story is a member of of the package or schedule, and is providing it's last published lead.

Therefore the asset id can be seen to change in these collections, as new leads are published for each story involved. The package or schedule is providing the most recent lead automatically via the story. Although the asset id can be seen to change, the referenced story id will remain the same for each successive lead, as the lead number increments.

Leads in a story

Since the story is the grouping of all the asset leads and more, it is possible to get a list of all the leads via the story leads list endpoint e.g.

/stories/{story id}/leads

This endpoint returns each lead asset that has been published, counting from lead number 0. There will always be at at least one original asset. Each asset is in summary form.

For convenience, there is also an endpoint to take you directly to the last published lead asset of a story as follows:

/stories/{story id}/leads/latest 

This endpoint returns a full asset response, revealing all detail the same as visiting /assets/{id}.

Sidebars belonging to story

An asset or story may also have its 'sidebars', which are child articles which themselves are assets of a story, but are existing in child relationship to a main asset/story. There are various ways to discover the sidebars to a story. Firstly it is indicated in the JSON by parent object in the story object:

"story": {
 "id": "20f3d9b2-a6dc-46b9-a6a8-b3021e06200a",
 ..., 
 "parent": {
            "id": "d529f6d3-bd18-4372-984d-0b9a0d31ee06"
        }
} 

The story.parent.id is actually also a story, but is the parent story to the sidebar's story. Regular assets do not have this parent.

In the Atom and RSS a sidebar is indicated by an Atom link element to the parent story. The rel attribute will be "related":

<link rel="related" href="http://news.api.press.net/v1.5/stories/d529f6d3-bd18-4372-984d-0b9a0d31ee06" />

It is also possible to discover the sidebars that exist for a parent story by hitting the story sidebars list endpoint:

/stories/{parent story id}/sidebars

This returns a list of assets that are sidebars to {parent story id}. Please note that the last published lead of each sidebar asset is always returned (remember that sidebars themselves have their own story, leads, media etc).

Snaps related to a story

Although snaps do not explicitly belong to a story at present, there is an endpoint to help find the snaps that may be related to a story. Please not that this endpoint is not guaranteed to find all related snaps, because it depends upon common metadata between the leads in the story and the snaps that have been published in the same time period. To see if any snaps related to a story can be found, call the following endpoint:

/stories/{story id}/snaps

The response is a list of zero or more snap assets in summary form, that were published with similar metadata to any of the leads of the story on the same day.

Embargoed stories

Some assets published by PA editorial are embargoed until a certain date and time, or indefinately. Access to assets currently under embargo depends upon the entitlements set up for your API key. If you have access to embargoes, they will be discoverable in asset lists such when searching assets or fetching a schedule. However if your key does not permit embargoes, they will be filtered out from these lists.

Once an embargo period has expired for an asset, it will become discoverable if you are not permitted embargoes.

Please note that advisory assets are always embargoed indefinately, and so will remain invisible to those who cannot see embargoes. This is because advisories are generally written for the attention of trusted media customers, who would receive our embargoes anyway.

The JSON for an embargoed asset, where the embargo information is conveyed by isEmbargoed and embargoedUntil keys.

{
    "kind": "asset",
    "id": "170ebba0-2805-4ca3-ad69-5832feb01f96",
    ...,	
    "isEmbargoed": true,
    "embargoedUntil": "2015-08-19T17:00:00.000Z",
    ...,
}  

The embargo related keys will not be present if an asset have never been embargoed. The isEmbargoed key will become false when the embargo time has expired, and will remain true for an indefinite embargo - where the embargoedUntil key will not be present.

In Atom and RSS the embargo is conveyed via a pa:embargoed element:

<pa:embargoed>2015-08-19T17:00:00.000Z</pa:embargoed>

The element will be not be present when an asset has never been embargoed, and will be empty e.g. <pa:embargoed/> when the embargo is indefinite.

Images and cropping

The News API provides download links for any images that have been attached to an asset or gallery. When an asset is accessed directly via the /assets/{asset_id} endpoint, or exposed as part of a larger response such as a package, the JSON, Atom or RSS rendition of the asset will provide the image download links for three sizes of the image:

• Full - the full size production image
• Preview - a middle size suitable for image preview purposes
• Thumbnail - a small thumbnail suitable only for thumbnail display

The image download links may be followed as is, with no need to add your API key or any special request headers. A typical download link to a production image looks like this:

https://news.static.press.net/v2/image/production/d06f81607f972f7361252c5367a3e8a3/2.16081267.jpg

It is also possible, at this time, to download images using plain HTTP and not HTTPS, but this would require some client side alteration of the URL to be http://.

News API images are in a variety of resolutions and ratios as per the original PA image. Some may be landscape or portrait, and will vary in size, though almost always the full size will be of very high production quality. The preview and thumbnail renditions are always in the same aspect ratio as the full size image.

The News API does not provide scaled and/or cropped images, except for the preview and thumbnail download. However it is capable or providing suggested point-of-interest (POI) and cropping information for each image. This can be enabled by using the crop parameter to express which crop types are required. This information will then be added to the response, so that client side software may apply its own cropping to the full size image. The crop parameter will honour a set number of crop types as follows:

• POI
• SQUARE
• THREE_TO_TWO
• FOUR_TO_THREE
• SIXTEEN_TO_NINE
• FIVE_TO_FOUR,
• TWO_TO_ONE
• SEVEN_TO_TWO

The POI crop means point-of-interest and is just a co-ordinate of the full size image, and not a cropping rectangle. The other crop are expressed as rextangles on the full size images using x, y, height and width values from the top left corner.

Here is an example segment of JSON for an image, where the parameter crop=POI,SQUARE has been passed in the call:

{
   "kind":"picture",
   "id":"2.20360036",
   "title":"Public sector strike",
   "summary":"Public sector workers marched through Newcastle city centre as part of the one-day walkout ",
   "credit":"PA WIRE",
   "renditions":{
      "thumb":{
         "width":127,
         "height":84,
         "size":7999,
         "href": "https://news.static.press.net/v2/image/thumbnail/97c79ce5a33be45d48bfadbb428e11b6/2.20360036.jpg"
      },
      "preview":{
         "width":511,
         "height":340,
         "size":98295,
         "href": "https://news.static.press.net/v2/image/preview/2656b3c8b05f809a223a82caa9e047c3/2.20360036.jpg"
      },
      "full":{
         "width":4252,
         "height":2830,
         "size":2210113,
         "href": "https://news.static.press.net/v2/image/production/318b0438136563e83e2200ee67e6c11b/2.20360036.jpg",
         "crops":{
            "POI":{
               "x":2126,
               "y":1415
            },
            "SQUARE":{
               "height":2829,
               "width":2829,
               "x":1315,
               "y":0
            }
         }
      }
   }
}

Here is the a segment of Atom and RSS, which both use elements in the Media RSS namespace, and the PA namespace for the crop info:

<media:content url="https://news.static.press.net/v2/image/production/318b0438136563e83e2200ee67e6c11b/2.20360036.jpg" type="image/jpeg" width="4252" height="2830" fileSize="2210113">
   <media:thumbnail url="https://news.static.press.net/v2/image/thumbnail/97c79ce5a33be45d48bfadbb428e11b6/2.20360036.jpg" width="127" height="84" />
   <media:thumbnail url="https://news.static.press.net/v2/image/preview/2656b3c8b05f809a223a82caa9e047c3/2.20360036.jpg" width="511" height="340" />
   <media:title>Public sector strike</media:title>
   <media:description>Public sector workers marched through Newcastle city centre as part of the one-day walkout</media:description>
   <media:credit>PA WIRE</media:credit>
   <pa:crop name="POI" x="2126" y="1415" />
   <pa:crop name="SQUARE" height="2829" width="2829" x="1315" y="0" />
</media:content> 

Curated Social Collections

Some assets will provide a link to the PA Social API, in the media section usually reserved for images and video. This link provides access to a curated collection of Social Media items that are related to the content, such as in Twitter, Instagram andYoutube. This social content may be used to further enrich the editorial content in the asset.

Access to the Social API can be organisedthrough PA customer services or your usual PA business contact.

In the JSON media section, a social link is as follows:

{
  "kind": "social-collection",
  "href": "http://social.api.press.net/v1/collections/urn:newsapi:storychain:680353ba-6535-42f2-92db-12989f17e015"        
}

In the Atom and RSS the link to the social collection appears as a link in the Atom namespace as follows:

<link rel="social-collection" href="http://social.api.press.net/v1/collections/urn:newsapi:storychain:680353ba-6535-42f2-92db-12989f17e015">