List Response - Navigation
This response type is used for enumerating the available lists of feeds, schedules and packages when accessing the corresponding base endpoint:
{
"kind": "newsapi#feed",
"title": "Press Association News API Feeds",
"id": "feeds",
"updated": "2014-06-09T15:05:02.574438Z",
"totalResults": 19,
"startIndex": 1,
"itemsPerPage": 19,
"items": [
{
"kind": "newsapi#feed",
"id": "businessFinance",
"title": "Business and Finance",
"updated": "2014-06-09T15:04:53.16381Z"
}
]
}
Navigation list responses use the newsapi#feed kind, which means that you can expect a title, id and updated timestamp for the resource, and an optional set of OpenSearch data (totalResults, startIndex, itemsPerPage) and optional list of items. Note that for navigation list responses, itemsPerPage andtotalResults will be the same - all results are returned, and no paging of results is enabled.
Each item has the same kind, and comes with an id, title and updated time. The corresponding item can be visited by appending the id to the list endpoint e.g./v1/feeds/businessFinance
List Response - Assets
The asset list response is returned for packages and schedules, where there is a managed finite set of assets curated by PA editorial teams.
{
"kind": "newsapi#feed",
"id": "sportdigital",
"title": "Sport Digital",
"updated": "2014-06-12T08:24:50.131Z",
"totalResults": 42,
"startIndex": 1,
"itemsPerPage": 42,
"items": [
{
"kind": "newsapi#story",
...
},
...
]
}
Asset list responses use the newsapi#feed kind, which means that you can expect a title, id and updated timestamp for the resource, and an optional set of OpenSearch data (totalResults, startIndex, itemsPerPage) and a list of items. Note that for list responses, itemsPerPage and totalResults will be the same - all results are returned, and no paging of results is enabled.
Each entry in the items array is a story represented using the short-form Summary Asset Response.
Search Response
The search response is returned for feed listing/searching and ad-hoc general searches. The response is based on the list response, but with additional information to assist navigation through the result space.
{
"kind": "newsapi#feed",
"title": "Search Results",
"id": "assets?query=Cameron&tag=patopic:POLITICS",
"updated": "2014-06-12T10:42:20.465Z",
"totalResults": 8392,
"startIndex": 1,
"itemsPerPage": 10,
"facets": {
"when": [
{
"id": "today",
"name": "Today",
"count": 6
},
{
"id": "yesterday",
"name": "Yesterday",
"count": 24
},
{
"id": "7-days",
"name": "Last 7 Days",
"count": 129
},
{
"id": "30-days",
"name": "Last 30 Days",
"count": 393
},
{
"id": "older",
"name": "Older",
"count": 7999
}
],
"tag": [
{
"id": "pacategory:HHH",
"name": "Home News",
"count": 6974
},
{
"id": "patopic:POLITICS",
"name": "Politics",
"count": 4743
},
{
"id": "patopic:CITY",
"name": "City",
"count": 1383
},
...
]
},
"items": [
{
"kind": "newsapi#story",
...
},
...
]
}
totalResults and itemsPerPage now have different values, indicating that you can page through the set of search results using the limit and offset parameters.
The search response also includes a set of facets which can be used to drill down further into the result set. The when facet provides a breakdown of results into commonly-used time bands (if a specific band contains no results then it will be omitted). The tag facet reveals how many results include the (up to) 10 most commonly used tags within the result set, inviting guided navigation by adding an additional ?tag= query parameter to add the relevant filter.
Each story in the items array is a Summary Asset Response story.
Summary Asset Response
This short-form representation of an asset is used in all JSON list and search responses.
{
"kind": "newsapi#story",
"id": "05947487-4cac-42ba-8b2e-5e15de51f278",
"isPartOf": "634297b7-aa11-4842-8b4c-80b98559db7c",
"title": "SHOWBIZ Sunshine",
"headline": "Leona Lewis shines at film premiere",
"updated": "2014-06-12T08:22:54.051Z",
"tags": [
{
"id": "pafeattopic:SHOWBIZ",
"name": "Showbiz",
"types": [
"cpnat:abstract"
]
},
{
"id": "pafeattopic:FILM",
"name": "Film",
"types": [
"cpnat:abstract"
]
},
{
"id": "pafeattopic:MUSIC",
"name": "Music",
"types": [
"cpnat:abstract"
]
}
],
"summary": "Leona Lewis was Walking On Sunshine at the premiere of her debut film.",
"media": [
{
"kind": "newsapi#picture",
"id": "2.20081663",
"summary": "Leona Lewis attending the Walking On Sunshine premiere in London",
"renditions": {
"thumb": {
"width": 76,
"height": 127,
"size": 5049,
"href": "https://static.images.api.press.net/v1/image/thumbnail/fb5b068c8aff005cc81b4c1a83af984a/2.20081663.jpg"
},
"preview": {
"width": 307,
"height": 512,
"size": 50228,
"href": "https://static.images.api.press.net/v1/image/preview/fb5b068c8aff005cc81b4c1a83af984a/2.20081663.jpg"
}
}
}
]
}
The keys presented in the summary response are similar to those in the Full Asset Response (see below), excluding content and providing only the first picture in themedia list, and just the thumbnail and preview representations of that image.
Full Asset Response
The full asset response is used when a specific asset is retrieved by ID from the /v1/assets/{asset_id} endpoint.
{
"kind": "newsapi#story",
"id": "05947487-4cac-42ba-8b2e-5e15de51f278",
"isPartOf": "634297b7-aa11-4842-8b4c-80b98559db7c",
"title": "SHOWBIZ Sunshine",
"headline": "Leona Lewis shines at film premiere",
"updated": "2014-06-12T08:22:54.051Z",
"tags": [
{
"id": "pafeattopic:SHOWBIZ",
"name": "Showbiz",
"types": [
"cpnat:abstract"
]
},
{
"id": "pafeattopic:FILM",
"name": "Film",
"types": [
"cpnat:abstract"
]
},
{
"id": "pafeattopic:MUSIC",
"name": "Music",
"types": [
"cpnat:abstract"
]
}
],
"summary": "Leona Lewis was Walking On Sunshine at the premiere of her debut film.",
"media": [
{
"kind": "newsapi#picture",
"id": "2.20081663",
"summary": "Leona Lewis attending the Walking On Sunshine premiere in London",
"renditions": {
"thumb": {
"width": 76,
"height": 127,
"size": 5049,
"href": "https://static.images.api.press.net/v1/image/thumbnail/fb5b068c8aff005cc81b4c1a83af984a/2.20081663.jpg"
},
"preview": {
"width": 307,
"height": 512,
"size": 50228,
"href": "https://static.images.api.press.net/v1/image/preview/fb5b068c8aff005cc81b4c1a83af984a/2.20081663.jpg"
},
"full": {
"width": 2099,
"height": 3500,
"size": 990303,
"href": "https://static.images.api.press.net/v1/image/fb5b068c8aff005cc81b4c1a83af984a/2.20081663.jpg"
}
}
},
{
"kind": "newsapi#picture",
"id": "2.20081743",
"summary": "A kilt-wearing Greg Wise attends the premiere of Walking On Sunshine with wife Emma Thompson and their daughter Gaia",
"renditions": {
"thumb": {
"width": 87,
"height": 128,
"size": 4635,
"href": "https://static.images.api.press.net/v1/image/thumbnail/91eee60b35bca275e236974dd3429236/2.20081743.jpg"
},
"preview": {
"width": 348,
"height": 512,
"size": 48875,
"href": "https://static.images.api.press.net/v1/image/preview/91eee60b35bca275e236974dd3429236/2.20081743.jpg"
},
"full": {
"width": 2381,
"height": 3500,
"size": 1288932,
"href": "https://static.images.api.press.net/v1/image/91eee60b35bca275e236974dd3429236/2.20081743.jpg"
}
}
},
{
"kind": "newsapi#picture",
"id": "2.20081575",
"summary": "Hannah Arterton shows off her vocal talents in Walking On Sunshine",
"renditions": {
"thumb": {
"width": 81,
"height": 127,
"size": 5187,
"href": "https://static.images.api.press.net/v1/image/thumbnail/b473fada52b20a6a6501727d1c2b9eba/2.20081575.jpg"
},
"preview": {
"width": 324,
"height": 511,
"size": 56049,
"href": "https://static.images.api.press.net/v1/image/preview/b473fada52b20a6a6501727d1c2b9eba/2.20081575.jpg"
},
"full": {
"width": 2221,
"height": 3500,
"size": 1469480,
"href": "https://static.images.api.press.net/v1/image/b473fada52b20a6a6501727d1c2b9eba/2.20081575.jpg"
}
}
},
{
"kind": "newsapi#video",
"id": "urn:newsml:pressassociation.com:20140612:Ipkg1402560019886I"
}
],
"content": "Leona Lewis was Walking On Sunshine at the premiere of her debut film.
The former X Factor winner appears in musical film Walking On Sunshine, about a woman getting married in Italy who realises her whirlwind romance is with her sister's former holiday fling.
Leona said: \"Because I'd been to theatre school when I was young, I'd done a bit of acting before, so I wanted to do something like this - specifically I did really want to do a musical and then this came along and it was perfect.\"
The Bleeding Love singer, who wore a glittering black gown and white blazer, said she would love to act again.
\"If an opportunity arises from it and it's the right kind of thing, why not? I'd love to do a musical again because this was so much fun and maybe I'll do something more serious too,\" she said.
The film also stars Greg Wise, Hannah Arterton, Annabel Scholey, Giulio Berruti and Katy Brand, who were all on the red carpet at the Vue cinema in London's Leicester Square.
Greg, who arrived with wife Emma Thompson and their daughter, wore a kilt which he said had been his wedding outfit, and danced along the carpet.
He said: \"I can't actually dance, you saw as I walked in what little dancing I could actually do.\"
The actor added: \"Emma hasn't seen the film yet. My daughter's never seen anything I've been in ever.\"
Hannah said of working with Leona: \"I was starstruck for quite a long time, it took me a couple of days to pluck up the courage to relax around her. She's such an icon.
\"I do most of the lead vocal on this film so I was, 'oh my God it's Leona, how is that going to work?'.\"
Walking On Sunshine is released in cinemas on June 27.
"
}
The keys have the following usage:
| Key | Required? | Usage |
kind |
mandatory |
Specifies the type of asset. Usually newsapi#story but could also be newsapi#gallery, newsapi#snap |
id |
mandatory |
The unique identifier for the asset |
isPartOf |
optional |
Where a story is part of an update chain - new stories written on the same theme, rather than the same story itself being corrected or extended - then isPartOf is an identifier for that set of stories. |
title |
mandatory |
A PA moniker for the story, intended for editorial use but not for display to consumers. |
headline |
mandatory |
the headline for the story |
updated |
mandatory |
The date and time of the last published update to this story |
tags |
mandatory |
The set of classification and entity metadata tagged against the asset. Each tag has an id, which can be used in a ?tag={tag_id} search query, and a name which is intended for display use for that tag. Tags may also have a set of types, for example cpnat:abstract indicates classification; cpnat:organisation for organisations. The IPTC scheme for types can be found here: http://cv.iptc.org/newscodes/cpnature/ |
summary |
mandatory |
A short abstract/description of the story. Commonly this is the first paragraph of the story (PA's intros are written to be stand-alone in this way) unless a specific abstract has been written. |
media |
mandatory |
Related pictures and videos for the story. The media array will always be present (but empty), even if the story has no attached pictures or videos. |
media.kind |
mandatory |
The type of media asset - either newsapi#picture or newsapi#video. Note that videos only have an id which matches the ID used to upload the video content directly to the client's CDN. Videos are not available for access via the News API. |
media.id |
mandatory |
A unique identifier for the media object |
media.summary |
mandatory |
A caption for use with the picture |
media.renditions |
mandatory |
Pictures can have multiple renditions - full, preview and thumbnail. Each rendition includes dimensions, file size, and a download link. |
content |
mandatory |
The body content of the story, encoded as an HTML5 article
|
