Top Headlines
his endpoint provides live top and breaking headlines for a country, specific category in a country, single source, or multiple sources. You can also search with keywords. Articles are sorted by the earliest date published first.
This endpoint is great for retrieving headlines for display on news tickers or similar.
Request parameters
-
country
The 2-letter ISO 3166-1 code of the country you want to get headlines for. Possible options:
ae,ar,at,au,be,bg,br,ca,ch,cn,co,cu,cz,de,eg,fr,gb,gr,hk,hu,id,ie,il,in,it,jp,kr,lt,lv,ma,mx,my,ng,nl,no,nz,ph,pl,pt,ro,rs,ru,sa,se,sg,si,sk,th,tr,tw,ua,us,ve,za,. Note: you can’t mix this param with thesourcesparam. -
category
The category you want to get headlines for. Possible options:
businessentertainmentgeneralhealthsciencesportstechnology. Note: you can’t mix this param with thesourcesparam. -
sources
A comma-seperated string of identifiers for the news sources or blogs you want headlines from. Use the /sources endpoint to locate these programmatically or look at the sources index. Note: you can’t mix this param with the
countryorcategoryparams. -
q
Keywords or a phrase to search for.
-
pageSizeint
The number of results to return per page (request). 20 is the default, 100 is the maximum.
-
pageint
Use this to page through the results if the total results found is greater than the page size.
-
apiKeyREQUIRED
Your API key. Alternatively you can provide this via the
X-Api-KeyHTTP header.
Response object
-
statusstring
If the request was successful or not. Options:
ok,error. In the case oferroracodeandmessageproperty will be populated. -
totalResultsint
The total number of results available for your request.
-
articlesarray[article]
The results of the request.
-
sourceobject
The identifier
idand a display namenamefor the source this article came from. -
authorstring
The author of the article
-
titlestring
The headline or title of the article.
-
descriptionstring
A description or snippet from the article.
-
urlstring
The direct URL to the article.
-
urlToImagestring
The URL to a relevant image for the article.
-
publishedAtstring
The date and time that the article was published, in UTC (+000)
-
contentstring
The unformatted content of the article, where available. This is truncated to 200 chars.
-