Please take a look at the getting started guide if you are unfamiliar with the Netcopy API.
GET /articles
Search for articles based on issue, content, locations, topics, and more with optional result faceting.
Parameters
| Name | Required? | Default | Example | Description |
|---|---|---|---|---|
| term | No | n/a | "prime minister 1934" | Free text search term matched against article body. |
| from | No | n/a | "2012-12-02" | Only include articles whose date is greater than or equal to {from}. See supported date formats |
| to | No | n/a | "2012-12-02" | Only include articles whose date is less than or equal to {to}. See supported date formats |
| facet | No | n/a | "people,year" | Generate facets for the fields specified. |
| filter | No | n/a | "people:'Queen Elizabeth'" | Return only articles that mention Queen Elizabeth. |
| sort | No | "relevance" | "date" | Metric to sort the articles by. |
| descending | No | "false" | "true" | If set to "true" then articles will be sorted in descending order. See supported boolean formats |
| items-per-page | No | 20 | 13 | Limit the number of issues returned per request. |
| page | No | 1 | 3 | Specify which page of issues to return. |
Filtering
As well as searching based on a user entered query or free-text term it is possible to filter based on specific fields.
Filters are specified as a key-value pair separated by a colon. Multiple filters can be specified by separating with a comma, for example:
people:'Queen Elizabeth',topic:'Human Interest'
You can filter on the following fields:
- types - publication article types
- topics - overall topic of article (Entertainment, Education, Human Interest, etc...)
- people - people named in the article
- keywords - keywords relevant to the article
- organisations - orgnisations named in the article
- cities - cities mentioned in the article
- countries - countries mentioned in the article
Sorting
By default results are returned in order of relevance based on the term provided. You may optionally sort results on the following fields:
- date - Date on which the article was published
- headline - Alphabetically by headline
- length - The length, in words, of the article body
- type - Type of article. Article types are specific to a publication (e.g. Letter, Editorial, Review)
- random - Randomised
Faceting
A list of facets based on sector
Faceted searches enable users to drill-down through collections of articles based on their attributes. Facets can be shown alongside search results with the number of articles within the facet.
Date facets
Faceting by date lets you break down your archived content into periods. As well as producing counts for the number of articles per month, year, or decade a suitable title for the period is also generated (i.e. "August 2012", "1965", or "1980s").
- months - months based on publication date
- years - years based on publication date
- decades - decades based on publication date
Location facets
Location facets are returned with latitude and longitude values.
- locations - location based on city
Other facets
- types - publication article types
- topics - overall topic of article (Entertainment, Education, Human Interest, etc...)
- people - people named in the article
- keywords - keywords relevant to the article
- organisations - orgnisations named in the article
- cities - cities mentioned in the article
- countries - countries mentioned in the article
Examples
Click an example link to see the results below.
http://demo.content-api.netcopy.co.uk/articles?term=chamberlain&page=5&items-per-page=3
Get articles mentioning "chamberlain" (page 5, 3 results per page)
-
Get articles published between 1st September 1893 and 31st September 1893 in reverse date order.
http://demo.content-api.netcopy.co.uk/articles?facet=months&items-per-page=0
Get the number of articles published per month.
http://demo.content-api.netcopy.co.uk/articles?filter=cities:London
Get all articles that mention London.
Result
The method returns a list of articles that matched the search terms specified.