News API v1.5 - API Notes

Back to top

Interactive Documentation

To try our API please ensure you're logged in and click on the IO Docs link.

API Base URL

The base URL for News API v1.5 is as follows:

http://news.api.press.net/v1.5

All endpoints discussed are assumed to have this prefix.

Authentication

The API requires an API key to access. The API will be provided at the time of registration and can be passed as either an header or query parameter with the key "apikey".

The following examples demonstrate both options for authentication using CURL.

Header Value

curl -v --header "apikey: <API_KEY>" http://news.api.press.net/v1.5/feeds

Query Parameter

curl -v http://news.api.press.net/v1.5/feeds\?apikey\=<API_KEY>

Content Types

All endpoints are capable of returning JSON, ATOM and RSS response types via content negotiation. By default JSON responses will be returned.

The content type can be negotiated in two ways;

Accept Header

Header Value	Content-Type	Description
application/rss+xml	RSS	The response will be in RSS format.
application/json	JSON	The response will be in JSON format (default format). JSONP is also available by passing the "callback" query parameter.
application/atom+xml	ATOM	The response will be in ATOM format.

For example;

curl -v --header "apikey: <API_KEY>" --header "Accept: application/atom+xml" http://news.api.press.net/v1.5/feeds

curl -v --header "apikey: <API_KEY>" --header "Accept: application/rss+xml" http://news.api.press.net/v1.5/feeds

Accept Query Parameter

Parameter Value (accept)	Content-Type	Description
rss	RSS	The response will be in RSS format.
json	JSON	The response will be in JSON format (default format). JSONP is also available by passing the "callback" query parameter.
atom	ATOM	The response will be in ATOM format.

For example;

curl -v --header "apikey: <API_KEY>" http://news.api.press.net/v1.5/feeds?accept=rss

curl -v --header "apikey: <API_KEY>" http://news.api.press.net/v1.5/feeds?accept=atom


Response Encoding

The JSON, Atom and RSS responses from the News API are UTF-8 encoded, when received uncompressed.

GZIP Compression

The News API will also honour the Accept-Encoding header if you wish have responses compressed in GZIP format. This is generally a good idea if your client HTTP software supports it, and is often a default behavior in many HTTP client libraries and browsers. Compressed responses will use less network bandwidth between your client and the News API, and could result in a faster transport of the smaller amount of compressed data. This is at the very small cost of server side gzip compression and client side decompression of the received binary data.

Response compression is enabled by passing the Accept-Encoding header as follows:

Accept-Encoding: gzip

Only the gzip value is supported. Any other value may result in a 406 Unacceptable error.

If the response has been successfully gzipped, the News API will response with the following header in the response:

Content-Encoding: gzip

Upon receipt of this header, your client HTTP software should automatically unzip the received stream of gzipped data and transparently provide the News API response you expected. If your software cannot do this, the decompression may have to be performed programmatically. If you find that your client is receiving a compressed response with this header, and you cannot handle the compression, you will need to ensure that you do not pass any Accept-Encoding header in your requests. 

Response Codes

Endpoints also return different HTTP response codes depending on the status of the request The API currently returns the following response HTTP response codes:

Response Code	Type	Description
200	Success	The request was successful.
204	Success	The request was made against a valid resource but there is current no content available to return.
404	Warning	The endpoint or resource does not exist.
405	Warning	The operation requested is not available on that endpoint (e.g. DELETE on a GET only endpoint).
406	Error	The API cannot honour the accept type or encoding requested
403	Warning	The service or key is currently over allowed Queries per Second. Please retry again in 1 second.
500	Error	An internal server error occurred please report this issue to your key provider.
593	Error	The endpoint you are trying to access does not exist. Please refer to the documentation.

API Trial Experience

By default the initial experience of the News API is a trial, that offers a limited amount of access to PA generated content. The following restrictions are are place in the trial, at the time of writing:

Searching is disabled

Full text search, via the query parameter, will be disabled if attempted against the assets or feeds endpoints. You will find that this paramter is simply ignored and does not affect the returnede results. However it will still be possible to utilise other query paramters against these endpoints, such as tag and date. Therefore it is still possible to drill down into feeds using tags and date ranges.

Archive access is disabled

When accessing the assets or feeds endpoints, it will not be possible to discover articles older than six months. However when accessing packages and schedules this limitation will not be in effect, since these are curated aggregations that may hold older articles.

Assets are restricted

When accessing the assets endpoint, to discover all published articles, you will find that the range of article types is restricted to the general wire output of the PA, similar to what you would find in the ukNewswire feed.

Embargoes are restricted

Articles currently under embargo will not be visible in the API, until that embargo has expired or been lifted.

Packages are restircted

The packages access is limited to the following packages in the trial:

Feeds are restricted

The feeds access is limited to the following feeds in the trial:

Schedules are restricted

The schedules access is limited to the following schedules in the trial:

Galleries are restricted

The galleries access is limited to the following galleries in the trial:

Media copyrights are restricted

The access to copyrighted media (pictures and video links) that is attached to assets is restricted to the usual unrestricted copyrights. Media with an AP, Empics or Racing Editoral copyright will not be visible.

Beyond the API Trial

Access to more content than the trial, or if the trial has ended, will require the full set up of your API key. This provides opportunity to alter any of the restrictions mentioned above, such as access to specific packages. Please contact PA customer services or your PA account manager to discuss these arrangements.