The Content API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors.
We use built-in HTTP features, like header based authentication and also support cross-origin resource sharing, allowing you to interact securely with our API from both client-side and server-side applications.
The Content API provides a JSON response by default. The JSON returned by our API is based on the IPTC NinJS standard.
For full details please refer to the NinJS developer site.
Content API is secured using API key based authentication. This key not only determines if you're permitted to access the API but also what content you're entitled to consume.
When developing against Content API it's essential you identify yourself with your API key for every single request.
Passing the API key via the "apikey" header can be achieved as follows:
curl \ -H "apikey: <API KEY>" \ https://api.ldrs.org.uk/v1/item
The Content API fully supports partial response meaning that you can determine the exact item fields you'd like returned in your API responses.
In order to return a partial representation of a response use the fields query parameter. Let's take a look at an example of how partial response could be used using this parameter.
To demonstrate how this can be used let's make the following request to return the 2 latest items:
curl \ -H "Accept: application/json" \ -H "apikey: <API KEY>" \ https://api.ldrs.org.uk/v1/item?sort=versioncreated:desc&limit=2
Upon execution Content API returns a full response that looks a like the following snippet:
{
"total": 20,
"limit": 2,
"offset": 0,
"item": [
{
"id": 1,
"uri": "https://ldrs.org.uk/article/1",
"type": "Story",
"versioncreated": "2017-09-29T14:54:20",
"byline": "Mark Miller",
"headline": "Example Story",
"body_text": "Example text",
"body_html": "<p>Example text</p>",
"subject": [
{
"code": "category:education",
"name": "Education",
"lang": "en",
"rel": "category",
"guid": "6942cb29-9d3f-4c9c-9806-0a0578c286d6"
}
...
]
...
}
...
]
}
This response is great if you require all metadata, however if you only require certain fields, then you can choose which fields to return.
The following is the same request but this time we only choose fields we need:
curl \ -H "Accept: application/json" \ -H "apikey: <API KEY>" \ https://api.ldrs.org.uk/v1/item?sort=versioncreated:desc&limit=2&fields=id,versioncreated,headline,subject.code
Upon execution of the modified request the API returns a response that looks a like the following snippet:
{
"total": 20,
"limit": 2,
"offset": 0,
"item": [
{
"id": 1,
"versioncreated": "2017-09-29T14:54:20",
"headline": "Example Story",
"subject": [
{
"code": "category:news"
}
...
]
...
}
...
]
}
Tho format of the fields request parameter is as following:
Pagination of results can be done by using the offset and limit parameters. The offset parameter defines the offset from the first result you want to fetch. The limit parameter allows you to configure the maximum amount of hits to be returned.
The default offset value is 0 and the default limit value is 20. The maximum limit value supported by the API is 100.
The following demonstrates a request that will only return 10 results (if 10 results are available):
curl \ -H "Accept: application/json" \ -H "apikey: <API KEY>" \ https://api.ldrs.org.uk/v1/item?limit=10
Building on the above request, to get the next 10 results we would need to simply set the offset to the value of the previous offset plus the limit, so 0 + 10.
curl \ -H "Accept: application/json" \ -H "apikey: <API KEY>" \ https://api.ldrs.org.uk/v1/item?limit=10&offset=10
In order to return the next "pages", simply keep adding the offset to the limit of the previous request.
When querying the item collection, several filters can be passed to get a more accurate response.
Fields that can be used for filtering are the following:
| Property | Description |
|---|---|
| limit | Number of items returned. Defaults to 20. |
| offset | Offset to start from. Defaults to 0. |
| sort | The expression to sort items with (property:order). Defaults to versioncreated:desc. |
| query |
The string query to use. By default, the query will search in the following fields:
Example: animal (cat OR dog) "is an" -white This will search within the above defined fields for stories containing the word animal AND containing the word cat or the word dog AND containing the phrase "is an" AND does not contain the word white. Furthermore, the subject search is an OR search unlike when specified directly in the subject field. So if you were to pass 'test' as an example in the search field and no subject parameter was passed, it will search for stories with the word 'test' OR stories with subject code 'test'. However, if in the search field 'test' is passed and 'test' is passed as well in the subject field in the advanced search, the api will search for stories with the word 'test' AND having the subject code 'test'. |
| aqAllWords |
The search for all the words. If the query parameter is passed, this parameter is ignored. By default, the query will search in the following fields:
Example: council project budget This will search within the above defined fields for stories containing the word council AND containing the word project AND containing the word budget |
| aqExactWords |
The search for exact words or phrases. If the query parameter is passed, this parameter is ignored. By default, the query will search in the following fields:
Example: budget meeting This will search within the above defined fields for stories containing the exact phrase "budget meeting" |
| aqAnyWords |
The search for any of the words. If the query parameter is passed, this parameter is ignored. By default, the query will search in the following fields:
Example: budget cost This will search within the above defined fields for stories containing the word budget OR the word cost |
| aqNoWords |
The search for none of the words. If the query parameter is passed, this parameter is ignored. By default, the query will search in the following fields:
Example: tax This will search within the above defined fields for stories that do not contain the word tax |
| type | The type of item to return [story, advisory]. Supports multiple types as a comma seperated string. (e.g. type=story) |
| pubstatus | The status of item to return [usable, withheld]. Supports multiple types as a comma seperated string. (e.g. pubstatus=usable) |
| byline | The byline to search for. Wrapping the string in double quotes will search for an exact phrase, otherwise it searches for each word seperately (e.g. byline="Eric Fox") |
| headline | The headline to search for. Wrapping the string in double quotes will search for an exact phrase, otherwise it searches for each word seperately (e.g. headline=my headline) |
| description | The description to search for. Wrapping the string in double quotes will search for an exact phrase, otherwise it searches for each word seperately (e.g. description="my description") |
| subject | Only return items for this subject code. Supports multiple categories and/or tags as a comma seperated string. (e.g. subject=category:news) |
| notSubject | Only return items that do not belong to this subject code. Supports multiple categories and/or tags as a comma seperated string. (e.g. notsubject=category:news) |
| start | Only return items updated since the start date time. (e.g. start=2017-08-25) |
| end | Only return items updated before the end date time. (e.g. end=2017-08-25) |
| rangeField | The date range field to search for the start and end parameters. Defaults to versioncreated (e.g. rangeField=firstcreated) |
Any parameter that accepts a date-time value can either accept a standard ISO 8601 formatted value or an ElasticSearch compatible Date Math expression.
The following table provide examples of accepted formats:
| 2017-01-01 | YYYY-MM-DD |
| 2015-01-01T00:00:00 | YYYY-MM-DDThh:mm:ss |
| now-1h | The current time plus one hour. |
| now-1h-1m | The current time plus one hour plus one minute. |