The Headline Licence grants you:
The headline licence mostly uses the Search Endpoint
Note: The full text of the article cannot be requested - if this is a requirement please contact us to discuss.
All your requests to the FT APIs should use the following base URL:
http://api.ft.com
You must supply a valid API Key with each request. There are two ways to do this.
1. Supply an “apiKey” Request Parameter
GET /content/search/v1?apiKey=yourApiKey
2. Supply an “X-Api-Key” Request Header
X-Api-Key: yourApiKey
The simplest search request to find headlines looks like this:
POST http://api.ft.com/content/search/v1?apiKey=yourApiKey Content-Type: application/jsonBODY: { “queryString”: “banks” }
You need to supply a Content-Type header of application/json. The response will look like this:
{
“query”: {
“queryString”: “banks”,
“queryContext”: {
“curations”: [
“ARTICLES”,
“BLOGS”,
“PAGES”,
“PODCASTS”,
“VIDEOS”
]
},
“resultContext”: {
“maxResults”: 100,
“offset”: 0,
“contextual”: true,
“highlight”: false
}
},
“results”: [
{
“indexCount”: 216893,
“curations”: [
“ARTICLES”,
“BLOGS”,
“PAGES”,
“PODCASTS”,
“VIDEOS”
],
“results”: [
{
“aspectSet”: “article”,
“modelVersion”: “1”,
“id”: “6405e5ce-fb7e-11e3-aa19-00144feab7de”,
“apiUrl”: “http://api.ft.com/content/items/v1/6405e5ce-fb7e-11e3-aa19-00144feab7de"
},
{
“aspectSet”: “article”,
“modelVersion”: “1”,
“id”: “328be012-f6dc-11e3-8ed6-00144feabdc0”,
“apiUrl”: “http://api.ft.com/content/items/v1/328be012-f6dc-11e3-8ed6-00144feabdc0"
},
{
“aspectSet”: “article”,
“modelVersion”: “1”,
“id”: “9626850e-fafc-11e3-8959-00144feab7de”,
“apiUrl”: “http://api.ft.com/content/items/v1/9626850e-fafc-11e3-8959-00144feab7de"
},
{
“aspectSet”: “blogPost”,
“modelVersion”: “1”,
“id”: “7cf44b09-d2c1-3a43-afb0-25a92a75d4f4”,
“apiUrl”: “http://api.ft.com/content/items/v1/7cf44b09-d2c1-3a43-afb0-25a92a75d4f4"
}…
]
}
]
}
The first part of the response is about your query. You can see:
{
“query”: {
“queryString”: “banks”,
“queryContext”: {
“curations”: [
“ARTICLES”,
“BLOGS”,
“PAGES”,
“PODCASTS”,
“VIDEOS”
]
},
“resultContext”: {
“maxResults”: 100,
“offset”: 0,
“contextual”: true,
“highlight”: false
}
},
…
}
The second part of the response contains the results. You can see:
The following shows the default fields you see for each result:
{
…
“results”: [
{
“indexCount”: 216893,
“curations”: [
“ARTICLES”,
“BLOGS”,
“PAGES”,
“PODCASTS”,
“VIDEOS”
],
“results”: [
{
“aspectSet”: “article”,
“modelVersion”: “1”,
“id”: “6405e5ce-fb7e-11e3-aa19-00144feab7de”,
“apiUrl”: “http://api.ft.com/content/items/v1/6405e5ce-fb7e-11e3-aa19-00144feab7de"
},
{
“aspectSet”: “article”,
“modelVersion”: “1”,
“id”: “328be012-f6dc-11e3-8ed6-00144feabdc0”,
“apiUrl”: “http://api.ft.com/content/items/v1/328be012-f6dc-11e3-8ed6-00144feabdc0"
},
{
“aspectSet”: “article”,
“modelVersion”: “1”,
“id”: “9626850e-fafc-11e3-8959-00144feab7de”,
“apiUrl”: “http://api.ft.com/content/items/v1/9626850e-fafc-11e3-8959-00144feab7de"
},
{
“aspectSet”: “blogPost”,
“modelVersion”: “1”,
“id”: “7cf44b09-d2c1-3a43-afb0-25a92a75d4f4”,
“apiUrl”: “http://api.ft.com/content/items/v1/7cf44b09-d2c1-3a43-afb0-25a92a75d4f4"
}…
]
}
]
}
See the Examples section below for details on how to make more advanced queries and how to see more information for each result. You can also go to the Search Tutorial for in-depth coverage.
Note: These are specific to the Headline licence agreement and in addition to the FT Developer Programme Terms and Conditions.
All users of the FT API, when linking back to FT.com are required to append a campaign parameter to the URL in the following format:
http://www.ft.com/cms/{article uuid}.html?FTCamp=engage/CAPI/{SOURCE}/Channel_{ORGNAME}//B2B
where:
Example
So a developer from the FT using the API and serving links into a web app would apply the following parameter and value:
FTCamp=engage/CAPI/webapp/Channel_FT//B2B
Note: Failure to add the campaign parameter may result in your API key being revoked.
All users of the licence, when displaying FT content in their platform, must comply with the following Attribution Guidelines.
The headline licence has a default rate limit of 2 API calls per second and 5,000 API calls per day. We are willing to increase this quota for applications that demonstrate compliance, for an additional charge.
1) Retrieve more information for each result
POST http://api.ft.com/content/search/v1?apiKey=yourApiKey Content-Type: application/jsonBODY: { “queryString”: “banks”, “resultContext” : { “aspects” :[ “title”,“lifecycle”,“location”,“summary”,“editorial” ] } }
Aspects are used to specify which fields you want to see in the results. For the headline licence, you are restricted to the title, lifecycle, location, summary and editorial aspects. Each result will now look like this:
{
“aspectSet”: “article”,
“modelVersion”: “1”,
“id”: “4f2990dc-f314-11e3-a3f8-00144feabdc0”,
“apiUrl”: “http://api.ft.com/content/items/v1/4f2990dc-f314-11e3-a3f8-00144feabdc0",
“title”: {
“title”: “Power to the people on product design”
},
“lifecycle”: {
“initialPublishDateTime”: “2014-06-24T10:37:35Z”,
“lastPublishDateTime”: “2014-06-24T10:37:35Z”
},
“location”: {
“uri”: “http://www.ft.com/cms/s/0/4f2990dc-f314-11e3-a3f8-00144feabdc0.html"
},
“summary”: {
“excerpt”: “Reaching break-even on a new car programme when vehicle sales approach 100 would sound like a pipe-dream”
},
“editorial”: {
“byline”: “By Richard Waters”
}
}
2) How to search for text that appears in the headline
POST http://api.ft.com/content/search/v1?apiKey=yourApiKey Content-Type: application/jsonBODY: { “queryString”: “Trump AND title:\“Clinton\“”, “queryContext” : { “curations” : [ “ARTICLES”] } }
This will search for content that mentions Trump in any of the searchable fields, but where the headline (title) contains ‘Clinton’. There are many Searchable Fields that can be used like this in queries.
3) How to search for videos or blogposts
POST http://api.ft.com/content/search/v1?apiKey=yourApiKey Content-Type: application/jsonBODY: { “queryString”: “Trump”, “queryContext” : { “curations” : [ “BLOGS”] } }
Curations let you specify the type or types of content you want to see, for example ARTICLES, BLOGS or VIDEOS. Each result contains an aspectSet that indicates whether it represents a blog post, video or article:
{
“aspectSet”: “blogPost”,
“modelVersion”: “1”,
“id”: “e0c40a0a-93ad-3937-a65c-a5c2c053e83a”,
“apiUrl”: “http://api.ft.com/content/items/v1/e0c40a0a-93ad-3937-a65c-a5c2c053e83a"
}
4) How to search for content about British Telecom
You can do a simple search using “British Telecom” in the query string, but if you want to specifically look for content that is about the organisation British Telecom, you can also do that.
There is a bit of exploration to do to work out exactly what your search needs to be.
Your search is going to be made for the specific ‘organisations’ field. To work out what value to search for, you need to work out what the tag is for British Telecom as an organisation. You can do that by looking at the facets available when you search for content that is about British Telecom.
Facets allow you to refine your query. You can find out what the currently supported facets are via a discovery method on the API. The result will look something like this:
[
“authors”,
“brand”,
“category”,
“format”,
“genre”,
“icb”,
“iptc”,
“organisations”,
“people”,
“primarySection”,
“primaryTheme”,
“regions”,
“sections”,
“specialReports”,
“subjects”,
“topics”,
]
We are interested in the organisations facet. You need to know what tag is used for British Telecom as an organisation. One way to do this is to search for relevant content and ask the search to show details of the facets found in the results. For example:
POST http://api.ft.com/content/search/v1?apiKey=yourApiKey Content-Type: application/jsonBODY: { “queryString”: “British Telecom”, “queryContext” : { “curations” : [ “ARTICLES”] }, “resultContext” : { “maxResults”: 1, “facets” : {“names”:[ “organisations”],“maxElements”:20,“minThreshold”:1} } }
This search restricts the number of results to 1, just to make it easier to find what you’re interested in. It then requests the top 5 organisation facets for that search. That should include the one for British Telecom! Your result should look something like this:
{
“query”: {
“queryString”: “British Telecom”,
“queryContext”: {
“curations”: [
“ARTICLES”
]
},
“resultContext”: {
“maxResults”: 1,
“offset”: 0,
“facets”: {
“names”: [
“organisations”
],
“maxElements”: 5,
“minThreshold”: 1
},
“contextual”: false,
“highlight”: false
}
},
“results”: [
{
“indexCount”: 1274,
“curations”: [
“ARTICLES”
],
“results”: [
{
“aspectSet”: “article”,
“modelVersion”: “1”,
“id”: “b3bb8f14-c574-11e3-a7d4-00144feabdc0”,
“apiUrl”: “http://api.ft.com/content/items/v1/b3bb8f14-c574-11e3-a7d4-00144feabdc0"
}
],
“facets”: [
{
“name”: “organisations”,
“facetElements”: [
{
“name”: “BT Group PLC”,
“count”: 328
},
{
“name”: “France Telecom SA”,
“count”: 216
},
{
“name”: “Vodafone Group PLC”,
“count”: 206
},
{
“name”: “Deutsche Telekom”,
“count”: 156
},
{
“name”: “BSkyB”,
“count”: 103
}
]
}
]
}
]
}
From this, you can see that “BT Group PLC” is used for British Telecom as an organisation. Now you can use this in your search:
POST http://api.ft.com/content/search/v1?apiKey=yourApiKey Content-Type: application/jsonBODY: { “queryString”: “British Telecom OR organisations:=\“BT Group PLC\“” }
5) How to search for blogs that mention Apple and have been published this year
POST http://api.ft.com/content/search/v1?apiKey=yourApiKey Content-Type: application/jsonBODY: { “queryString”: “Apple AND lastPublishDateTime:>2017-01-01T00:00:00Z”, “queryContext” : { “curations” : [ “BLOGS”] } }
Last published date is another Searchable Field. The date must be specified in ISO 8601 datetime format. Some valid examples:
6) How to search for byline Martin Wolf published since 2014
POST http://api.ft.com/content/search/v1?apiKey=yourApiKey Content-Type: application/jsonBODY: { “queryString”: “byline:\“Martin Wolf\” AND lastPublishDateTime:>2017-01-01T00:00:00Z”, “queryContext”: { “curations”: [ “ARTICLES” ] }, “resultContext” : { “aspects” :[ “title”,“lifecycle”,“location”,“summary”,“editorial” ]
}}
7) How to sort by date (most recent first)
By default, results are returned in order of relevancy. To Sort based on something else, you need to specify what field you would like to sort on, and whether to sort ASC or DESC.
POST http://api.ft.com/content/search/v1?apiKey=yourApiKey Content-Type: application/jsonBODY: { “queryString”: “Banks” , “resultContext” : { “aspects” :[ “title”,“lifecycle”,“location”,“summary”,“editorial” ], “sortOrder” : “DESC”, “sortField” : “initialPublishDateTime”
}}
For more information on sortable fields, see the Sortable Fields Discovery Method.
8) How to search based on section
For example, to retrieve all content in the Energy section. Sometimes content is tagged as belonging to multiple sections. The primary section is the most relevant. Firstly, you need to decide whether you only want content where Energy is the primary section (use field “primarySection”), or whether you want all content that has Energy as a section (use field “sections”).
POST http://api.ft.com/content/search/v1?apiKey=yourApiKey Content-Type: application/jsonBODY: { “queryString”: “sections:\“Energy\“”, “resultContext” : { “aspects” :[ “title”,“lifecycle”,“location”,“summary”,“editorial” ] } }
9) How to navigate when you get multiple pages of results
The maximum number of results returned to you in one hit will be 100. You can choose to ask for less than that if you want by specifying the number of results to return:
POST http://api.ft.com/content/search/v1?apiKey=yourApiKey Content-Type: application/jsonBODY: { “queryString”: “banks”, “resultContext” : { “aspects” :[ “title”,“lifecycle”,“location”,“summary”,“editorial” ], “maxResults” : “10” } }
If you want to get back subsequent pages of results, you specify an offset to use. For example, if you got back 100 results (the default) in your first response, your next request should have offset of 100 - so you will get back results 101 to 200. NB: the offset is zero based, meaning the first result is counted as result 0.
POST http://api.ft.com/content/search/v1?apiKey=yourApiKey Content-Type: application/jsonBODY: { “queryString”: “banks”, “resultContext” : { “aspects” :[ “title”,“lifecycle”,“location”,“summary”,“editorial” ], “offset” : “100” } }
If you are getting back 100 per request, you can keep moving through the results by adding 100 to the offset each time.
10) How to use boolean operators in your searches