Headlines Endpoint
Get top headlines and breaking news from around the world
The Headlines endpoint returns the latest top headlines and breaking news articles. Headlines are curated from major news sources and updated in real-time.
https://api.allnewsapi.com/headlinesQuery Parameters
Name | Type | Default Value | Description |
|---|---|---|---|
apikeyRequired | string | — | Your API key for authentication. Get your API key from the dashboard |
q | string | — | This parameter allows you fetch news articles that match your keyword. Your keywords help the system find the most fitting articles for you. You can use words together with logical operators, which you can learn more about in the Examples: technology"artificial intelligence"apple AND iphone |
startDate | string | — | This parameter allows you filter articles based on their publication date. You can specify a date, and the API will only return articles published on or after that date Examples: 2024-12-15T17:48:56Z2025-05-20 |
endDate | string | — | This parameter allows you filter articles based on their publication date. You can specify a date, and the API will only return articles published on or before that date Examples: 2024-08-14T17:48:56Z2024-01-23 |
content | boolean | false | This parameter enables you retrieve the full content of the articles. By default, the content is trimmed. Set this to true to get the full content Examples: truefalse |
lang | string | — | This parameter allows you to specify the language of the news articles returned by the API. You can combine multiple languages by separating them with a comma. See the list of Examples: enen,fr,de |
country | string | — | This parameter allows you to specify the country where the news articles returned by the API were published. You can combine multiple countries by separating them with a comma. See the full list of Examples: usgb,de,fr |
region | string | — | This parameter allows you to specify the region where the news articles returned by the API were published. You can combine multiple regions by separating them with a comma. See the full list of Examples: americasafrica,asia |
category | string | — | This parameter allows you to filter the news articles returned by a specific category. You can combine multiple categories by separating them with a comma. See the full list of Examples: financefood,health,hobbies,lifestyle |
max | integer | 5 | This parameter allows you to specify the number of news articles returned by the API in a single request. Valid values are between 1 to 100, depending on your subscription Examples: 1020 |
attributes | string | title,description | This parameter allows you select which parts of the news articles the keywords are searched in. Valid values are title, description, and content. You can combine multiple attributes by separating them with a comma. For example, "title,description" means searching in both the title and description. Examples: titletitle,description,content |
page | integer | 1 | This parameter allows you to control the pagination of the results returned by the API. Each page displays a certain number of articles, determined by the value of "max". Examples: 120 |
sortby | string | publishedAt | This parameter allows you choose how the articles are sorted. There are two options: Examples: publishedAtrelevance |
publisher | string | — | Search for news from a specific publisher. You can combine multiple publishers by separating them with a comma Examples: bbc.comforbes.com,cnn.com,bbc.com |
format | string | json | This parameter allows you select the data format returned by the API. You can choose between json, csv, or xlsx Examples: csvxlsx |
Response
The API returns a JSON object containing an array of top headline articles.
Name | Type | Default Value | Description |
|---|---|---|---|
totalArticles | integer | — | The total number of articles matching your search query |
currentPage | integer | — | The current page number in the paginated results |
nextPage | integer | — | The next page number (null if on last page) |
articles | array | — | An array of article objects matching your search criteria |
articles[].title | string | — | The title of the news article |
articles[].description | string | — | The description or summary of the news article |
articles[].category | string | — | The category that the article falls under |
articles[].content | string | — | The full content of the news article (premium feature) |
articles[].country | string | — | The country code where the article was published (ISO 3166-1 alpha-2) |
articles[].region | string | — | The geographic region where the article was published |
articles[].lang | string | — | The language code of the article (ISO 639-1) |
articles[].sentiment | string | — | The overall sentiment of the article (positive, negative, neutral) analyzed using AI |
articles[].sentimentScores | object | — | Detailed sentiment scores with numerical values for negative, neutral, and positive sentiments |
articles[].url | string | — | The direct URL to the original article |
articles[].image | string | — | The main image or thumbnail URL of the article |
articles[].publishedAt | string | — | The publication date and time of the article in ISO 8601 format (UTC) |
articles[].source.name | string | — | The name of the news publisher or source |
articles[].source.url | string | — | The homepage URL of the news source |