Documentation
Sign up for free!
Get instant access to the API with your free API token. No billing details required!
Getting Started
Introduction
Our API was developed to provide global news from thousands of sources with exceptional response times. On average we add over 1 million articles weekly, so you will never be short of content. Even better, it is completely free!
To get started simply sign up and use your API token in any of the available API endpoints documented below for instant access.
If you have any questions or concerns, feel free to contact us.
Authentication
As mentioned above, when you sign up for free you will find your API token on your dashboard. Simply add this to any of our API endpoints as a GET parameter to gain access. Examples of how this is done can be found below.
API Endpoints
Headlines Available on: Standard plan and above
Endpoint
GET https://api.thenewsapi.com/v1/news/headlines HTTP/1.1
Use this endpoint to find get the latest headlines by category along with similar articles, allowing you to create the perfect news aggregation page similar to Google News .
If you have issues with your requests, please ensure your GET parameters are URL-encoded.
All text data returned is UTF-8.
All dates are in UTC (GMT).
HTTP GET Parameters
name | required | description |
---|---|---|
api_token |
true | Your API token which can be found on your account dashboard. |
locale |
false | Comma separated list of country codes to include in the result set. Default is all countries.
Click here for a list of supported countries.
Example: us,ca (US + Canada).
|
domains |
false | Comma separated list of domains to include. List of domains can be obtained through our Sources endpoint, found further down this page. |
exclude_domains |
false | Comma separated list of domains to exclude |
source_ids |
false | Comma separated list of source_ids to include. List of source_ids can be obtained through our Sources endpoint, found further down this page. |
exclude_source_ids |
false | Comma separated list of source_ids to exclude. |
language |
false | Comma separated list of languages to include. Default is all.
Click here for a list of supported languages. Examples: en,es (English + Spanish)
|
published_on |
false | Find headlines for articles published on the specified date. Supported formats include: Y-m-d .
Examples: 2024-11-21
|
headlines_per_category |
false | Specify the number of articles you want to return per category. The maximum is 10 and the default is 6. |
include_similar |
false | Specify if you wish to include similar articles with each base article. Default is true . |
Response Objects
name | description |
---|---|
data > uuid |
The unique identifier for an article in our system. Store this and use it to find specific articles using our single article endpoint. |
data > title |
The article title. |
data > description |
The article meta description. |
data > keywords |
The article meta keywords. |
data > snippet |
The first 60 characters of the article body. |
data > url |
The URL to the article. |
data > image_url |
The URL to the article image. |
data > language |
The language of the source. |
data > published_at |
The datetime the article was published. |
data > source |
The domain of the source. |
data > categories |
Array of strings which the source is categorized as. |
data > locale |
Locale of the source. |
data > similar |
An array of similar articles to the base article. |
If no results are found, the data object will be empty.
Example Request
GET https://api.thenewsapi.com/v1/news/headlines?locale=us&language=en&api_token=YOUR_API_TOKEN
Example Response
{
"data": {
"general": [
{
"uuid": "cc2691e9-d568-4ed5-afde-27e74fee9841",
"title": "2024 CMA Awards: The Complete List of Winners",
"description": "The 2024 CMA Awards, airing live from Nashville Nov. 20, award the genre's biggest acts. See every winner of the 58th annual county music ceremony so far.",
"keywords": "",
"snippet": "Watch : Dolly Parton Defends CMAs After Beyoncé Snub\n\nThe Country Music Awards have found a deeper well of winners.\n\nIndeed, country music’s biggest night co...",
"url": "https://www.eonline.com/news/1409923/2024-cma-awards-the-complete-list-of-winners?cmpid=rss-syndicate-genericrss-us-top_stories",
"image_url": "https://akns-images.eonline.com/eol_images/Entire_Site/20241020/cr_1200x1200-241120162421-GettyImages-2185821604.jpg?fit=around|1080:1080&output-quality=90&crop=1080:1080;center,top",
"language": "en",
"published_at": "2024-11-21T00:25:55.000000Z",
"source": "eonline.com",
"categories": [
"entertainment",
"general"
],
"locale": "us",
"similar": [
{
"uuid": "a957fd18-7160-4a06-a227-397fcdd3dd77",
"title": "CMA Awards 2024: Complete List of Nominees and Winners",
"description": "Morgan Wallen, Post Malone and Lainey Wilson were among the most-nominated artists at the 2024 CMA Awards on Wednesday, November 20",
"keywords": "",
"snippet": "The 2024 CMA Awards are honoring the best of country music.\n\nThe ceremony is being held at Bridgestone Arena in Nashville, Tennessee, on Wednesday, November 20,...",
"url": "https://www.usmagazine.com/entertainment/news/cma-awards-2024-complete-list-of-nominees-and-winners/",
"image_url": "https://www.usmagazine.com/wp-content/uploads/2024/11/CMA-Awards-2024-Complete-List-of-Nominees-and-Winners-0261.jpg?crop=0px,25px,1334px,702px&resize=1200,630&quality=40&strip=all",
"language": "en",
"published_at": "2024-11-21T01:04:02.000000Z",
"source": "usmagazine.com",
"categories": [
"entertainment",
"general"
],
"locale": "us"
},
{
"uuid": "6329162f-441b-423b-9f2d-f9b06327207b",
"title": "Luke Bryan, Peyton Manning, Lainey Wilson Open 2024 CMA Awards",
"description": "Hosts Luke Bryan, Peyton Manning and Lainey Wilson delivered an opening monologue during the 2024 CMA Awards on Wednesday, November 20",
"keywords": "",
"snippet": "Hosts Luke Bryan, Peyton Manning and Lainey Wilson opened the 2024 Country Music Association Awards with a bang.\n\nThe trio took the stage after Post Malone and ...",
"url": "https://www.usmagazine.com/entertainment/news/luke-bryan-peyton-manning-lainey-wilson-open-2024-cma-awards/",
"image_url": "https://www.usmagazine.com/wp-content/uploads/2024/11/Luke-Bryan-and-Peyton-Manning-Give-Lainey-Wilson-Hosting-Tips-in-2024-CMA-Awards-Monologue-388.jpg?crop=0px,0px,2000px,1051px&resize=1200,630&quality=86&strip=all",
"language": "en",
"published_at": "2024-11-21T01:46:37.000000Z",
"source": "usmagazine.com",
"categories": [
"entertainment",
"general"
],
"locale": "us"
},
{
"uuid": "6f9f1088-714d-4476-abc2-22601cf9f420",
"title": "Post Malone Performs Song Dedicated to Daughter at 2024 CMA Awards",
"description": "Post Malone paid tribute to his 2-year-old daughter with his performance of ‘Yours’ during the 2024 CMA Awards",
"keywords": "",
"snippet": "Post Malone paid a heartfelt tribute to his 2-year-old daughter with his performance of “Yours” during the 2024 Country Music Association Awards.\n\nThe artis...",
"url": "https://www.usmagazine.com/entertainment/news/post-malone-performs-song-dedicated-to-daughter-at-2024-cma-awards/",
"image_url": "https://www.usmagazine.com/wp-content/uploads/2024/11/Post-Malone-Performs-Song-Dedicated-to-His-Daughter-at-the-CMA-Awards-01-2024.jpg?crop=0px,229px,1333px,699px&resize=1200,630&quality=86&strip=all",
"language": "en",
"published_at": "2024-11-21T02:58:25.000000Z",
"source": "usmagazine.com",
"categories": [
"entertainment",
"general"
],
"locale": "us"
},
{
"uuid": "a89b169c-49cc-4d45-b7f7-19ff18d8e15c",
"title": "Carrie Underwood Makes Surprise 2024 CMA Awards Return",
"description": "Carrie Underwood made a surprise return to the 2024 CMA Awards to sing her and Cody Johnson’s duet ‘I’m Gonna Love You’",
"keywords": "",
"snippet": "Carrie Underwood made a surprising return to the 2024 Country Music Association Awards.\n\nThe moment came when Cody Johnson, who was up for five awards at this y...",
"url": "https://www.usmagazine.com/entertainment/news/carrie-underwood-makes-surprise-2024-cma-awards-return/",
"image_url": "https://www.usmagazine.com/wp-content/uploads/2024/11/Carrie-Underwood-Makes-Surprising-CMA-Awards-Return-to-Duet-With-Cody-Johnson-394.jpg?crop=90px,21px,1555px,815px&resize=1200,630&quality=86&strip=all",
"language": "en",
"published_at": "2024-11-21T03:14:57.000000Z",
"source": "usmagazine.com",
"categories": [
"entertainment",
"general"
],
"locale": "us"
},
{
"uuid": "6ad71d38-ee6e-47a2-902b-6c4404fe310e",
"title": "Billy Ray Cyrus Say’s He’s ‘Surprised’ by Beyonce’s CMA Awards Snub",
"description": "Billy Ray Cyrus is baffled by the CMA Awards’ snub of Beyonce’s ‘brilliant’ country album",
"keywords": "",
"snippet": "Billy Ray Cyrus is baffled by the CMA Awards’ snub of Beyoncé’s “brilliant” country album.\n\nCyrus, 63, defended the “Texas Hold ‘Em” icon via Ins...",
"url": "https://www.usmagazine.com/entertainment/news/billy-ray-cyrus-says-hes-surprised-by-beyonces-cma-awards-snub/",
"image_url": "https://www.usmagazine.com/wp-content/uploads/2024/07/Miley-Cyrus-Hugs-Mom-Tish-In-Behind-the-Scenes-Photos-After-Dad-Billy-Rays-Leaked-Audio-2.jpg?crop=0px,35px,1373px,721px&resize=1200,630&quality=86&strip=all",
"language": "en",
"published_at": "2024-11-21T04:36:34.000000Z",
"source": "usmagazine.com",
"categories": [
"entertainment",
"general"
],
"locale": "us"
}
]
},
{
"uuid": "d9a02eac-4409-42d9-a754-937ffdb59846",
"title": "DOJ calls for breakup of Google and sale of Chrome",
"description": "The Department of Justice is calling for Google to divest its Chrome browser, following a ruling in August that the company holds a monopoly in the search market.",
"keywords": "",
"snippet": "The Department of Justice is calling for Google to divest its Chrome browser, following a ruling in August that the company holds a monopoly in the search marke...",
"url": "https://www.nbcnews.com/news/us-news/google-department-of-justice-chrome-sale-breakup-microsoft-apple-rcna181133",
"image_url": "https://media-cldnry.s-nbcnews.com/image/upload/t_nbcnews-fp-1200-630,f_auto,q_auto:best/rockcms/2023-08/230802-google-logo-headquarters-mjf-1644-449266.jpg",
"language": "en",
"published_at": "2024-11-21T09:21:41.000000Z",
"source": "nbcnews.com",
"categories": [
"general",
"politics"
],
"locale": "us",
"similar": [
{
"uuid": "28db6c20-4aa9-4c02-b5b1-3d07a473db01",
"title": "Justice Department calls for break up of Google and sale of Chrome",
"description": "The proposed breakup calls for Google to sell its industry-leading Chrome web browser and impose restrictions designed to prevent its Android smartphone software from favoring its search engine.",
"keywords": "Google, United States Department of Justice, Antitrust",
"snippet": "U.S. regulators want a federal judge to break up Google to prevent the company from continuing to squash competition through its dominant search engine after a ...",
"url": "https://www.cbsnews.com/news/justice-department-calls-for-break-up-of-google-sale-of-chrome/",
"image_url": "https://assets2.cbsnewsstatic.com/hub/i/r/2024/11/21/bdc5cfe5-b771-4527-a180-afc7fc54043e/thumbnail/1200x630/00445716db0db9617d74ecdbff333f1e/gettyimages-2184968601.jpg?v=6056e68389c16974d8d95eeea60b7a3a",
"language": "en",
"published_at": "2024-11-21T04:40:28.000000Z",
"source": "cbsnews.com",
"categories": [
"general"
],
"locale": "us"
},
{
"uuid": "920d5e12-e2a9-449d-8c2a-4103fc533f77",
"title": "DOJ pushes for Google to break off Chrome browser after antitrust case",
"description": "The Department of Justice is pushing a federal judge to make Google divest its Chrome internet browser as a remedy following the antitrust case.",
"keywords": "Internet, Alphabet Inc, Google, Breaking News: Technology, Technology, Alphabet Class C, Microsoft Corp, business news",
"snippet": "U.S. Assistant Attorney General Jonathan Kanter speaks about the antitrust lawsuit against Live Nation Entertainment during a press conference as Attorney Gener...",
"url": "https://www.cnbc.com/2024/11/20/doj-pushes-for-google-to-break-off-chrome-browser-after-antitrust-case.html",
"image_url": "https://image.cnbcfm.com/api/v1/image/107419359-17164832022024-05-23t164342z_1582584387_rc2gw7auohk2_rtrmadp_0_live-nation-antitrust.jpeg?v=1716483268&w=1920&h=1080",
"language": "en",
"published_at": "2024-11-21T04:42:17.000000Z",
"source": "cnbc.com",
"categories": [
"general",
"business"
],
"locale": "us"
},
{
"uuid": "c0e43c5d-7995-485d-8c44-92017f8106aa",
"title": "US regulators seek to break up Google, forcing Chrome sale as part of monopoly punishment",
"description": "U.S. regulators want a federal judge to break up Google to prevent the company from continuing to squash competition through its dominant search engine after a court found it had maintained an abusive monopoly over the past decade.",
"keywords": "U.S. Department of Justice, Monopoly and antitrust, Donald Trump, General news, CA State Wire, U.S. news, District of Columbia, Business, Lifestyle, Counterfeiting and forgery, Legal proceedings, World news, Joe Biden, Software, Technology, Politics, World News, U.S. News",
"snippet": "U.S. regulators want a federal judge to break up Google to prevent the company from continuing to squash competition through its dominant search engine after a ...",
"url": "https://apnews.com/article/google-search-monopoly-penalty-justice-department-84e07fec51c5c59751d846118cb900a7",
"image_url": "https://dims.apnews.com/dims4/default/3dbcea3/2147483647/strip/true/crop/5322x2994+0+277/resize/1440x810!/quality/90/?url=https%3A%2F%2Fassets.apnews.com%2Fab%2F4d%2Fbd011caaa45f8e7386318fc8be7a%2F26ddd32ffc40438ca117f857e5efea19",
"language": "en",
"published_at": "2024-11-21T05:23:02.000000Z",
"source": "apnews.com",
"categories": [
"general"
],
"locale": "us"
}
]
}
],
"business": ...,
"sports": ...,
"tech": ...,
"science": ...,
"health": ...
}
}
Top Stories Available on: All plans
Endpoint
GET https://api.thenewsapi.com/v1/news/top HTTP/1.1
Use this endpoint to find live and historical top stories around the world or filter to get only top stories for specific countries. Filtering by language, category, source and publish date is also possible, as well as advanced searching on title and the main text of the article.
If you have issues with your requests, please ensure your GET parameters are URL-encoded.
All text data returned is UTF-8.
All dates are in UTC (GMT).
HTTP GET Parameters
name | required | description |
---|---|---|
api_token |
true | Your API token which can be found on your account dashboard. |
search |
false | Use the search as a basic search tool by entering regular search terms or it has more advanced usage to build search queries:+ signifies AND operation| signifies OR operation- negates a single token" wraps a number of tokens to signify a phrase for searching* at the end of a term signifies a prefix query( and ) signify precedence
To use one of these characters literally, escape it with a preceding backslash ( \ ).
Example 1: forex + (usd | gbp) -cad (searches for forex articles which include usd or gbp but excludes cad)Example 2: "Apple Inc" (searches for articles with exact matches for "Apple Inc")
For more advanced query examples, see our API Examples section. When using special characters (+, -, |, ", *, ()) you MUST URL-encode this parameter. |
search_fields |
false | Comma separated list of fields to apply the search parameter to.
Supported fields: title | description | keywords | main_text
Example: title,description,keywords Default: title,main_text
|
locale |
false | Comma separated list of country codes to include in the result set. Default is all countries.
Click here for a list of supported countries.
Example: us,ca (US + Canada).
|
categories |
false | Comma separated list of categories to include.
Supported categories: general | science | sports | business | health | entertainment | tech | politics | food | travel Example: business,tech
|
exclude_categories |
false | Comma separated list of categories to exclude. |
domains |
false | Comma separated list of domains to include. List of domains can be obtained through our Sources endpoint, found further down this page. |
exclude_domains |
false | Comma separated list of domains to exclude |
source_ids |
false | Comma separated list of source_ids to include. List of source_ids can be obtained through our Sources endpoint, found further down this page. |
exclude_source_ids |
false | Comma separated list of source_ids to exclude. |
language |
false | Comma separated list of languages to include. Default is all.
Click here for a list of supported languages. Examples: en,es (English + Spanish)
|
published_before |
false | Find all articles published before the specified date. Supported formats include:
Y-m-d\TH:i:s | Y-m-d\TH:i | Y-m-d\TH | Y-m-d | Y-m | Y .
Examples: 2024-11-21T10:17:17 |
2024-11-21T10:17 |
2024-11-21T10 |
2024-11-21 |
2024-11 |
2024
|
published_after |
false | Find all articles published after the specified date. Supported formats include:
Y-m-d\TH:i:s | Y-m-d\TH:i | Y-m-d\TH | Y-m-d | Y-m | Y .
Examples: 2024-11-21T10:17:17 |
2024-11-21T10:17 |
2024-11-21T10 |
2024-11-21 |
2024-11 |
2024
|
published_on |
false | Find all articles published on the specified date. Supported formats include: Y-m-d .
Examples: 2024-11-21
|
sort |
false | Sort by published_on or relevance_score (only available when used in conjunction with search ).
Default is published_at unless search is used and sorting by published_at is not included,
in which case relevance_score is used. |
limit |
false | Specify the number of articles you want to return in the request. The maximum limit is based on your plan. The default limit is the maximum specified for your plan. |
page |
false | Use this to paginate through the result set. Default is 1. Note that the max result set can't exceed 20,000. For example if your limit is 50, the max page you can have is 400 (50 * 400 = 20,000).
Example: page=2
|
Response Objects
name | description |
---|---|
meta > found |
The number of articles found for the request. |
meta > returned |
The number of articles returned on the page.
This is useful to determine the end of the result set as if this is lower than limit , there are no more articles after this page. |
meta > limit |
The limit based on the limit parameter. |
meta > page |
The page number based on the page parameter. |
data > uuid |
The unique identifier for an article in our system. Store this and use it to find specific articles using our single article endpoint. |
data > title |
The article title. |
data > description |
The article meta description. |
data > keywords |
The article meta keywords. |
data > snippet |
The first 60 characters of the article body. |
data > url |
The URL to the article. |
data > image_url |
The URL to the article image. |
data > language |
The language of the source. |
data > published_at |
The datetime the article was published. |
data > source |
The domain of the source. |
data > categories |
Array of strings which the source is categorized as. |
data > relevance_score |
Relevance score based on the search parameter. If the search parameter is not used, this will be null . |
data > locale |
Locale of the source. |
If no results are found, the data object will be empty.
Example Request
GET https://api.thenewsapi.com/v1/news/top?api_token=YOUR_API_TOKEN&locale=us&limit=3
Example Response
{
"meta": {
"found": 1164147,
"returned": 10,
"limit": 10,
"page": 1
},
"data": [
{
"uuid": "75c6ac52-c145-4186-b4fa-1c780b781184",
"title": "Ukraine’s military says Russia launches ICBM, a claim denied by Western official",
"description": "Ukraine this week launched U.S.-made missiles at targets inside Russia.",
"keywords": "Article, 116085317",
"snippet": "LONDON -- Russia on Thursday launched an intercontinental ballistic missile toward Ukraine, officials in Kyiv said, but a Western official told ABC News that th...",
"url": "https://abcnews.go.com/International/ukraine-russia-icbm-launch-intercontinental-ballistic-missile/story?id=116085317",
"image_url": "https://i.abcnewsfe.com/a/a06a8d30-cac9-4866-9b56-7adda8ff5c70/putin-main_1732182155654_hpMain_16x9.jpg?w=1600",
"language": "en",
"published_at": "2024-11-21T10:04:08.000000Z",
"source": "abcnews.go.com",
"categories": [
"general"
],
"relevance_score": null,
"locale": "us"
},
{
"uuid": "915b9049-e6c6-4249-af90-4e0087290e76",
"title": "John Prescott, pugnacious deputy U.K. prime minister to Tony Blair, dies at 86",
"description": "John Prescott, the pugnacious deputy prime minister to Britain’s Tony Blair during his 10 years in government, has died aged 86 after a battle with Alzheimer?...",
"keywords": "",
"snippet": "John Prescott, the pugnacious deputy prime minister to Britain’s Tony Blair during his 10 years in government, has died aged 86 after a battle with Alzheimer?...",
"url": "https://www.nbcnews.com/news/world/john-prescott-dead-deputy-uk-prime-minister-tony-blair-labour-rcna181136",
"image_url": "https://media-cldnry.s-nbcnews.com/image/upload/t_nbcnews-fp-1200-630,f_auto,q_auto:best/rockcms/2024-11/241121-john-prescott-mb-0921-cc3510.jpg",
"language": "en",
"published_at": "2024-11-21T10:03:29.000000Z",
"source": "nbcnews.com",
"categories": [
"general",
"politics"
],
"relevance_score": null,
"locale": "us"
},
{
"uuid": "150f7614-4b8e-4809-bd49-100a8696d643",
"title": "Spike Lee Named President Of Red Sea International Film Festival Jury",
"description": "Spike Lee has been named President Of the Red Sea International Film Festival Jury",
"keywords": "",
"snippet": "Spike Lee will head up the jury for the upcoming Red Sea International Film Festival.\n\nThe decorated Malcolm X filmmaker will preside over the features competit...",
"url": "https://deadline.com/2024/11/spike-lee-president-red-sea-international-film-festival-jury-1236183623/",
"image_url": "https://deadline.com/wp-content/uploads/2024/11/Spike-Lee-e1732182275940.jpeg?w=1024",
"language": "en",
"published_at": "2024-11-21T09:46:05.000000Z",
"source": "deadline.com",
"categories": [
"entertainment"
],
"relevance_score": null,
"locale": "us"
},
{
"uuid": "b8f089ae-73e8-41c6-b309-5d69e5257271",
"title": "NYC urologist sentenced to life for sexual abuse of patients, including minors",
"description": "A New York City urologist was handed a life sentence Wednesday after previously being convicted of the yearslong sexual abuse of patients, some of whom were min...",
"keywords": "",
"snippet": "A New York City urologist was handed a life sentence Wednesday after previously being convicted of the yearslong sexual abuse of patients, some of whom were min...",
"url": "https://www.nbcnews.com/news/us-news/nyc-urologist-sentenced-life-sexual-abuse-patients-minors-rcna181128",
"image_url": "https://media-cldnry.s-nbcnews.com/image/upload/t_nbcnews-fp-1200-630,f_auto,q_auto:best/rockcms/2024-11/241121-lqt-darius-paduch-mb-0942-134cc7.jpg",
"language": "en",
"published_at": "2024-11-21T09:44:01.000000Z",
"source": "nbcnews.com",
"categories": [
"general",
"politics"
],
"relevance_score": null,
"locale": "us"
},
{
"uuid": "8fe7d96c-8e10-40de-8d33-8511040be44e",
"title": "Anthony Mackie On ‘Captain America: Brave New World’, His Favorite MCU Character & Jumping Around In A Circle With Chris Evans — Disney APAC Showcase",
"description": "Anthony Mackie shared more about the upcoming 'Captain America: Brave New World,' and his",
"keywords": "",
"snippet": "Anthony Mackie has outlined why Sam Wilson will be “brains over brawn” in the upcoming Captain America: Brave New World and revealed where he was when he le...",
"url": "https://deadline.com/2024/11/anthony-mackie-captain-america-brave-new-world-disney-showcase-1236182161/",
"image_url": "https://deadline.com/wp-content/uploads/2024/11/Anthony-Mackie-star-of-Captain-America-Brave-New-World_1.jpg?w=1024",
"language": "en",
"published_at": "2024-11-21T09:41:49.000000Z",
"source": "deadline.com",
"categories": [
"entertainment"
],
"relevance_score": null,
"locale": "us"
},
{
"uuid": "63e12df1-8d75-40b7-84ff-723ffca1b78d",
"title": "Two British-made long-range missiles shot down – Russian MOD",
"description": "Russian air defenses have destroyed two UK-made Storm Shadow missiles over the past 24 hours, the Defense Ministry in Moscow has said",
"keywords": "",
"snippet": "The ministry has not specified where exactly the Storm Shadow missiles were intercepted\n\nRussian air defenses have intercepted two UK-produced Storm Shadow miss...",
"url": "https://www.rt.com/news/607967-storm-shadows-taken-down/",
"image_url": "https://mf.b37mrtl.ru/files/static.en/article/breaking.jpg",
"language": "en",
"published_at": "2024-11-21T09:41:22.000000Z",
"source": "rt.com",
"categories": [
"general",
"politics"
],
"relevance_score": null,
"locale": "us"
},
{
"uuid": "e386d49c-e479-4c62-9d4e-b411dd7fd12b",
"title": "Grammy Winner & 15-Time Oscar Nominee Diane Warren To Compose Original Song For ‘Maserati: The Brothers’",
"description": "Filming is underway on the project which stars Anthony Hopkins, Michele Morrone, Andy Garcia and Jessica Alba.",
"keywords": "",
"snippet": "EXCLUSIVE: Grammy winner and 15-time Oscar nominee Diane Warren is set to compose an original song for Maserati: The Brothers, starring Anthony Hopkins, Michele...",
"url": "https://deadline.com/2024/11/diane-warren-compose-song-for-maserati-the-brothers-anthony-hopkins-1236183536/",
"image_url": "https://deadline.com/wp-content/uploads/2024/03/GettyImages-2066786028.jpg?w=1024",
"language": "en",
"published_at": "2024-11-21T09:30:29.000000Z",
"source": "deadline.com",
"categories": [
"entertainment"
],
"relevance_score": null,
"locale": "us"
},
{
"uuid": "7d9fc857-9820-437d-93b9-ae753895c2a9",
"title": "Archegos’ Bill Hwang sentenced to 18 years in prison for massive U.S. fraud",
"description": "Former billionaire investor Sung Kook “Bill” Hwang was sentenced to 18 years in prison on Wednesday over the collapse of Archegos Capital Management, which ...",
"keywords": "",
"snippet": "Former billionaire investor Sung Kook “Bill” Hwang was sentenced to 18 years in prison on Wednesday over the collapse of Archegos Capital Management, which ...",
"url": "https://www.nbcnews.com/news/us-news/archegos-bill-hwang-sentenced-18-years-prison-massive-us-fraud-rcna181134",
"image_url": "https://media-cldnry.s-nbcnews.com/image/upload/t_nbcnews-fp-1200-630,f_auto,q_auto:best/rockcms/2024-11/241121-bill-hwang-mb-0923-18a0df.jpg",
"language": "en",
"published_at": "2024-11-21T09:28:15.000000Z",
"source": "nbcnews.com",
"categories": [
"general",
"politics"
],
"relevance_score": null,
"locale": "us"
},
{
"uuid": "fe10fea5-0712-4d3a-8604-3f0d79febf8c",
"title": "Ukraine says Russia launched an intercontinental missile in an attack for the first time in the war",
"description": "Ukraine says Russia has launched an intercontinental ballistic missile overnight targeting Dnipro city in the central-east of the country, which, if confirmed, ...",
"keywords": "Ukraine, Russia, General news, AP Top News, Russia Ukraine war, United States government, Ukraine government, World news, Military and defense, North Korea government",
"snippet": "KYIV, Ukraine (AP) — Ukraine says Russia launched an intercontinental ballistic missile overnight targeting Dnipro city in the central-east of the country, wh...",
"url": "https://apnews.com/article/russia-ukraine-icbm-attackddnipro-38b0faf6eed2cef98bdbc9be18f58244",
"image_url": "https://dims.apnews.com/dims4/default/852b37f/2147483647/strip/true/crop/4134x2325+0+215/resize/1440x810!/quality/90/?url=https%3A%2F%2Fassets.apnews.com%2Fa2%2F88%2Fa8f5e39936269a0be4d0794211f6%2F252048eb21ce4d888d7b3b4dfdf9f559",
"language": "en",
"published_at": "2024-11-21T09:23:02.000000Z",
"source": "apnews.com",
"categories": [
"general"
],
"relevance_score": null,
"locale": "us"
},
{
"uuid": "d9a02eac-4409-42d9-a754-937ffdb59846",
"title": "DOJ calls for breakup of Google and sale of Chrome",
"description": "The Department of Justice is calling for Google to divest its Chrome browser, following a ruling in August that the company holds a monopoly in the search marke...",
"keywords": "",
"snippet": "The Department of Justice is calling for Google to divest its Chrome browser, following a ruling in August that the company holds a monopoly in the search marke...",
"url": "https://www.nbcnews.com/news/us-news/google-department-of-justice-chrome-sale-breakup-microsoft-apple-rcna181133",
"image_url": "https://media-cldnry.s-nbcnews.com/image/upload/t_nbcnews-fp-1200-630,f_auto,q_auto:best/rockcms/2023-08/230802-google-logo-headquarters-mjf-1644-449266.jpg",
"language": "en",
"published_at": "2024-11-21T09:21:41.000000Z",
"source": "nbcnews.com",
"categories": [
"general",
"politics"
],
"relevance_score": null,
"locale": "us"
}
]
}
All News Available on: All plans
Endpoint
GET https://api.thenewsapi.com/v1/news/all HTTP/1.1
Use this endpoint to find all live and historical articles we collect. Filtering by language, category, source and publish date is also possible, as well as advanced searching on title and the main text of the article.
If you have issues with your requests, please ensure your GET parameters are URL-encoded.
All text data returned is UTF-8.
All dates are in UTC (GMT).
HTTP GET Parameters
name | required | description |
---|---|---|
api_token |
true | Your API token which can be found on your account dashboard. |
search |
false | Use the search as a basic search tool by entering regular search terms or it has more advanced usage to build search queries:+ signifies AND operation| signifies OR operation- negates a single token" wraps a number of tokens to signify a phrase for searching* at the end of a term signifies a prefix query( and ) signify precedence
To use one of these characters literally, escape it with a preceding backslash ( \ ).
Example 1: forex + (usd | gbp) -cad (searches for forex articles which include usd or gbp but excludes cad)Example 2: "Apple Inc" (searches for articles with exact matches for "Apple Inc")
For more advanced query examples, see our API Examples section. When using special characters (+, -, |, ", *, ()) you MUST URL-encode this parameter. |
search_fields |
false | Comma separated list of fields to apply the search parameter to.
Supported fields: title | description | keywords | main_text
Example: title,description,keywords Default: title,main_text
|
categories |
false | Comma separated list of categories to include.
Supported categories: general | science | sports | business | health | entertainment | tech | politics | food | travel Example: business,tech
|
exclude_categories |
false | Comma separated list of categories to exclude. |
domains |
false | Comma separated list of domains to include. List of domains can be obtained through our Sources endpoint, found further down this page. |
exclude_domains |
false | Comma separated list of domains to exclude |
source_ids |
false | Comma separated list of source_ids to include. List of source_ids can be obtained through our Sources endpoint, found further down this page. |
exclude_source_ids |
false | Comma separated list of source_ids to exclude. |
language |
false | Comma separated list of languages to include. Default is all.
Click here for a list of supported languages. Examples: en,es (English + Spanish)
|
published_before |
false | Find all articles published before the specified date. Supported formats include:
Y-m-d\TH:i:s | Y-m-d\TH:i | Y-m-d\TH | Y-m-d | Y-m | Y .
Examples: 2024-11-21T10:17:17 |
2024-11-21T10:17 |
2024-11-21T10 |
2024-11-21 |
2024-11 |
2024
|
published_after |
false | Find all articles published after the specified date. Supported formats include:
Y-m-d\TH:i:s | Y-m-d\TH:i | Y-m-d\TH | Y-m-d | Y-m | Y .
Examples: 2024-11-21T10:17:17 |
2024-11-21T10:17 |
2024-11-21T10 |
2024-11-21 |
2024-11 |
2024
|
published_on |
false | Find all articles published on the specified date. Supported formats include: Y-m-d .
Examples: 2024-11-21
|
sort |
false | Sort by published_on or relevance_score (only available when used in conjunction with search ).
Default is published_at unless search is used and sorting by published_at is not included,
in which case relevance_score is used. |
limit |
false | Specify the number of articles you want to return in the request. The maximum limit is based on your plan. The default limit is the maximum specified for your plan. |
page |
false | Use this to paginate through the result set. Default is 1. Note that the max result set can't exceed 20,000. For example if your limit is 50, the max page you can have is 400 (50 * 400 = 20,000).
Example: page=2
|
Response Objects
name | description |
---|---|
meta > found |
The number of articles found for the request. |
meta > returned |
The number of articles returned on the page.
This is useful to determine the end of the result set as if this is lower than limit , there are no more articles after this page. |
meta > limit |
The limit based on the limit parameter. |
meta > page |
The page number based on the page parameter. |
data > uuid |
The unique identifier for an article in our system. Store this and use it to find specific articles using our single article endpoint. |
data > title |
The article title. |
data > description |
The article meta description. |
data > keywords |
The article meta keywords. |
data > snippet |
The first 60 characters of the article body. |
data > url |
The URL to the article. |
data > image_url |
The URL to the article image. |
data > language |
The language of the source. |
data > published_at |
The datetime the article was published. |
data > source |
The domain of the source. |
data > categories |
Array of strings which the source is categorized as. |
data > relevance_score |
Relevance score based on the search parameter. If the search parameter is not used, this will be null . |
If no results are found, the data object will be empty.
Example Request
GET https://api.thenewsapi.com/v1/news/all?api_token=YOUR_API_TOKEN&language=en&limit=3
Example Response
{
"meta": {
"found": 49531823,
"returned": 10,
"limit": 10,
"page": 1
},
"data": [
{
"uuid": "17e743fa-da62-406b-85fd-6a913fbadf07",
"title": "롯데웰푸드, 베트남 협력사와 관계 강화…분유 시장 경쟁력 제고",
"description": "롯데웰푸드(옛 롯데제과)가 베트남 우수 거래처 관계자를 초청, 한국 공장 투어를 진행하는 등 협력사와 관계를 강화해 ?...",
"keywords": "",
"snippet": "롯데웰푸드의 베트남 우수 거래처 관계자들이 ‘뉴본’ 파트너십 행사를 위해 한국을 방문, 기념촬영을 하고 있다. 사진...",
"url": "http://www.foodnews.co.kr/news/articleView.html?idxno=110859",
"image_url": "https://cdn.foodnews.co.kr/news/thumbnail/202411/110859_74847_1715_v150.jpg",
"language": "ko",
"published_at": "2024-11-21T10:17:26.000000Z",
"source": "foodnews.co.kr",
"categories": [
"food"
],
"relevance_score": null
},
{
"uuid": "0179365e-97cf-48b6-8299-2b320b474091",
"title": "식약처, 美국립암연구소와 암 연구 협력",
"description": "식품의약품안전처(처장 오유경) 소속 식품의약품안전평가원은 미국 국립암연구소(National Cancer Institute, NCI)와 지난 19일 ?...",
"keywords": "",
"snippet": "식품의약품안전처(처장 오유경) 소속 식품의약품안전평가원은 미국 국립암연구소(National Cancer Institute, NCI)와 지난 19일 ?...",
"url": "http://www.docdocdoc.co.kr/news/articleView.html?idxno=3023282",
"image_url": "https://cdn.docdocdoc.co.kr/news/thumbnail/202411/3023282_3025951_2044_v150.jpg",
"language": "ko",
"published_at": "2024-11-21T10:17:19.000000Z",
"source": "docdocdoc.co.kr",
"categories": [],
"relevance_score": null
},
{
"uuid": "f2719082-b74f-4dc8-a7e6-d5474ddfa0b2",
"title": "不正に作った合鍵で侵入か…カフェの売り上げ金を盗んだのは元副店長の32歳女「間違いありません」営業終了後の時間帯狙う 札幌市",
"description": "北海道の放送局として、北海道内で起こったニュースを毎日動画でお伝えしています。身近に起こった話題や情報をメ?...",
"keywords": "",
"snippet": "不正に作った合鍵で侵入か…カフェの売り上げ金を盗んだのは元副店長の32歳女「間違いありません」営業終了後の時?...",
"url": "https://www.hbc.co.jp/news/a8a6535b0c7cdbb6547bc121c0aa5f17.html",
"image_url": "https://www.hbc.co.jp/news/picture/ee368c63fb4f7e9985051c7a50782b28L.jpg",
"language": "ja",
"published_at": "2024-11-21T10:17:12.000000Z",
"source": "hbc.co.jp",
"categories": [],
"relevance_score": null
},
{
"uuid": "cb36fa42-4216-41ef-8238-11b102baf748",
"title": "제주 전통 돌담쌓기 ‘돌챙이’ 자격시험 어때요?",
"description": "제주 전통 돌담쌓기(돌챙이) 자격시험이 치러진다. '2024 돌챙이(쌓기석공)' 민간자격 시험은 민간자격기본법 제17조에 따?...",
"keywords": "",
"snippet": "제주 전통 돌담쌓기(돌챙이) 자격시험이 치러진다.\n\n제주 전통 돌담쌓기(돌챙이) 자격시험이 치러진다.\n\n'2024 돌챙이(쌓기...",
"url": "http://www.jejusori.net/news/articleView.html?idxno=431983",
"image_url": "https://cdn.jejusori.net/news/thumbnail/202411/431983_455386_172_v150.jpg",
"language": "ko",
"published_at": "2024-11-21T10:17:11.000000Z",
"source": "jejusori.net",
"categories": [
"general"
],
"relevance_score": null
},
{
"uuid": "12fff339-a6b8-475b-bd93-53f74138a557",
"title": "運動星球 sportsplanetmag",
"description": "我非常熱愛碳水化合物。如果有人問我「妳喜歡什麼食物呢?」,我一定會回答「我喜歡碳水化合物」。比起炸雞,我更?...",
"keywords": "",
"snippet": "過度攝取碳水化合物的副作用\n\n嘴巴覺得熟悉的碳水化合物最對味,我又能怎麼辦?如同有人為肉類痴狂,我也認為對碳?...",
"url": "https://www.sportsplanetmag.com/article/desc/240007141",
"image_url": "https://www.sportsplanetmag.com/public/article/atl_20241121103121_154.png",
"language": "zh",
"published_at": "2024-11-21T10:17:00.000000Z",
"source": "sportsplanetmag.com",
"categories": [
"sports"
],
"relevance_score": null
},
{
"uuid": "31b9f1fa-844e-451e-92dd-06c21e286a3e",
"title": "베트남 영유아가 먹는 롯데웰푸드 '뉴본' 분유 인기",
"description": "롯데웰푸드는 베트남 현지 분유시장에서 영향력을 확대하고 있다고 21일 밝혔다.롯데웰푸드는 현재 베트남 호찌민과 하?...",
"keywords": "롯데웰푸드, 베트남, 한국공장투어, 뉴본, 분유, 호찌민, 하노이, 영유아, 성장과정, 현지상황, 체중증가, 뉴본플러스, 라인업, 말레이시아, 유통망확대",
"snippet": "올 10월까지 수출액 전년比 82%↑\n\n'뉴본 플러스' 등 다양한 라인업\n\n롯데웰푸드의 베트남 우수 거래처가 ‘뉴본’ 파트너?...",
"url": "http://www.shinailbo.co.kr/news/articleView.html?idxno=1964810",
"image_url": "http://www.shinailbo.co.kr/news/thumbnail/202411/1964810_1085254_642_v150.jpg",
"language": "ko",
"published_at": "2024-11-21T10:16:53.000000Z",
"source": "shinailbo.co.kr",
"categories": [],
"relevance_score": null
},
{
"uuid": "23c55560-9f1d-4498-a320-d4fa47451689",
"title": "認知症疑い、容易な検出手法開発 慶応大、三つの質問で|【西日本新聞me】",
"description": "慶応大や済生会横浜市東部病院のチームは21日、認知症のアルツハイマー病やその前段階である軽度認知障害(MCI)の?...",
"keywords": "西日本新聞me, 西日本新聞, ニュース, 九州, 福岡",
"snippet": "慶応大や済生会横浜市東部病院のチームは21日、認知症のアルツハイマー病やその前段階である軽度認知障害(MCI)の?...",
"url": "https://www.nishinippon.co.jp/item/o/1284323/",
"image_url": "https://www.nishinippon.co.jp/uploads/image/1724360/sns_PN2024112101000329.-.-.CI0003.jpg",
"language": "ja",
"published_at": "2024-11-21T10:16:53.000000Z",
"source": "nishinippon.co.jp",
"categories": [],
"relevance_score": null
},
{
"uuid": "575aecce-f0ae-4c3d-9da1-674aa66653c1",
"title": "印度Airtel 与诺基亚签订网络扩展协议_光纤在线",
"description": "光纤在线讯:以将 5G 覆盖范围扩大到关键领域并实现其 4G 覆盖范围的现代化,为推出 5G-Advanced 设备做准备。",
"keywords": "印度Airtel 与诺基亚签订网络扩展协议 Airtel 诺基亚 5G",
"snippet": "",
"url": "http://www.c-fol.net/news/2_202411/20241121101650.html",
"image_url": "http://www.c-fol.net/images/ico/favicon.png",
"language": "zh",
"published_at": "2024-11-21T10:16:50.000000Z",
"source": "c-fol.net",
"categories": [],
"relevance_score": null
},
{
"uuid": "1880927b-7ebe-449f-8849-283533ee9db2",
"title": "교통안전공단, 몽골에 'K-자동차 안전관리' 도입 지원 - 건설타임즈",
"description": "(건설타임즈) 이헌규 기자 = 한국교통안전공단(TS)은 20일부터 오는 28일까지 몽골 내각사무처, 도로교통부 및 국가도로교?...",
"keywords": "",
"snippet": "▲지난 20일 김천 교통안전공사 본사에서 개최된 ‘코이카 공공협력사업 고위급 초청연수’에 참석한 정용식 이사장(왼?...",
"url": "https://www.constimes.co.kr/news/articleView.html?idxno=300351",
"image_url": "https://cdn.constimes.co.kr/news/photo/202411/300351_60223_1354.jpg",
"language": "ko",
"published_at": "2024-11-21T10:16:41.000000Z",
"source": "constimes.co.kr",
"categories": [],
"relevance_score": null
},
{
"uuid": "4f360157-915b-454b-a614-f44e57da6946",
"title": "Activity of gamma-L-glutamyl derivatives on glutamate receptors",
"description": "Introduction:\r\nGlutamate is the major excitatory neurotransmitter in the central nervous system. It has many naturally-occurring derivatives obtained by modifyi...",
"keywords": "gamma l-glutamyl dipeptides",
"snippet": "Résumé en\n\nIntroduction: Glutamate is the major excitatory neurotransmitter in the central nervous system. It has many naturally-occurring derivatives obtaine...",
"url": "https://hal.science/hal-04794934v1",
"image_url": "https://hal.science/assets/favicon/apple-touch-icon.png",
"language": "fr",
"published_at": "2024-11-21T10:16:40.000000Z",
"source": "hal.archives-ouvertes.fr",
"categories": [],
"relevance_score": null
}
]
}
Similar News Available on: All plans
Endpoint
GET https://api.thenewsapi.com/v1/news/similar/uuid HTTP/1.1
Use this endpoint to find similar stories to a specific article based on its UUID.
If you have issues with your requests, please ensure your GET parameters are URL-encoded.
All text data returned is UTF-8.
All dates are in UTC (GMT).
HTTP GET Parameters
name | required | description |
---|---|---|
api_token |
true | Your API token which can be found on your account dashboard. |
categories |
false | Comma separated list of categories to include.
Supported categories: general | science | sports | business | health | entertainment | tech | politics | food | travel Example: business,tech
|
exclude_categories |
false | Comma separated list of categories to exclude. |
domains |
false | Comma separated list of domains to include. List of domains can be obtained through our Sources endpoint, found further down this page. |
exclude_domains |
false | Comma separated list of domains to exclude |
source_ids |
false | Comma separated list of source_ids to include. List of source_ids can be obtained through our Sources endpoint, found further down this page. |
exclude_source_ids |
false | Comma separated list of source_ids to exclude. |
language |
false | Comma separated list of languages to include. Default is all.
Click here for a list of supported languages. Examples: en,es (English + Spanish)
|
published_before |
false | Find all articles published before the specified date. Supported formats include:
Y-m-d\TH:i:s | Y-m-d\TH:i | Y-m-d\TH | Y-m-d | Y-m | Y .
Examples: 2024-11-21T10:17:17 |
2024-11-21T10:17 |
2024-11-21T10 |
2024-11-21 |
2024-11 |
2024
|
published_after |
false | Find all articles published after the specified date. Supported formats include:
Y-m-d\TH:i:s | Y-m-d\TH:i | Y-m-d\TH | Y-m-d | Y-m | Y .
Examples: 2024-11-21T10:17:17 |
2024-11-21T10:17 |
2024-11-21T10 |
2024-11-21 |
2024-11 |
2024
|
published_on |
false | Find all articles published on the specified date. Supported formats include: Y-m-d .
Examples: 2024-11-21
|
limit |
false | Specify the number of articles you want to return in the request. The maximum limit is based on your plan. The default limit is the maximum specified for your plan. |
page |
false | Use this to paginate through the result set. Default is 1. Note that the max result set can't exceed 20,000. For example if your limit is 50, the max page you can have is 400 (50 * 400 = 20,000).
Example: page=2
|
Response Objects
name | description |
---|---|
meta > found |
The number of articles found for the request. |
meta > returned |
The number of articles returned on the page.
This is useful to determine the end of the result set as if this is lower than limit , there are no more articles after this page. |
meta > limit |
The limit based on the limit parameter. |
meta > page |
The page number based on the page parameter. |
data > uuid |
The unique identifier for an article in our system. Store this and use it to find specific articles using our single article endpoint. |
data > title |
The article title. |
data > description |
The article meta description. |
data > keywords |
The article meta keywords. |
data > snippet |
The first 60 characters of the article body. |
data > url |
The URL to the article. |
data > image_url |
The URL to the article image. |
data > language |
The language of the source. |
data > published_at |
The datetime the article was published. |
data > source |
The domain of the source. |
data > categories |
Array of strings which the source is categorized as. |
data > relevance_score |
Relevance score based on the article provided. |
If no results are found, the data object will be empty.
Example Request
GET https://api.thenewsapi.com/v1/news/similar/cc11e3ab-ced0-4a42-9146-e426505e2e67?api_token=YOUR_API_TOKEN&language=en&published_on=2020-12-01
Example Response
{
"meta": {
"found": 3571,
"returned": 3,
"limit": 3,
"page": 1
},
"data": [
{
"uuid": "df4ad427-a672-4c67-b6c6-6f81aa00e164",
"title": "Tesla stock jumps after announcement it will join S&P 500 in one go",
"description": "Tesla's stock price surged early Tuesday after the company b...",
"keywords": "Business, s&p 500, stocks, tesla",
"snippet": "Tesla’s stock price surged early Tuesday after the company...",
"url": "https://nypost.com/2020/12/01/tesla-stock-jumps-on-news-it-will-join-sp-500-in-one-shot/",
"image_url": "https://nypost.com/wp-content/uploads/sites/2/2020/12/tesla-52.jpg?quality=90&strip=all&w=1200",
"language": "en",
"published_at": "2020-12-01T14:35:46.000000Z",
"source": "nypost.com",
"categories": [
"business"
],
"relevance_score": 153.61266
},
{
"uuid": "c9a23881-12dd-4005-8982-7b6552a2eb50",
"title": "Tesla To Join S&P 500 With Full Market Cap On December 21",
"description": "Tesla will be added to the S&P 500 index all at once at its ...",
"keywords": "Tesla, S&P500, EV, Automotive, Stocks, Investing",
"snippet": "Tesla (NASDAQ: TSLA) will be added to the S&P 500 index all ...",
"url": "https://oilprice.com/Latest-Energy-News/World-News/Tesla-To-Join-SP-500-With-Full-Market-Cap-On-December-21.html",
"image_url": "https://d32r1sh890xpii.cloudfront.net/news/718x300/2020-12-01_xwjdajwctl.jpg",
"language": "en",
"published_at": "2020-12-01T16:30:00.000000Z",
"source": "oilprice.com",
"categories": [
"general",
"business"
],
"relevance_score": 146.92773
},
{
"uuid": "18afdb1c-7742-4016-bf8c-a2f114e11199",
"title": "Tesla to Enter S&P 500 at Full Weight in December",
"description": "The electric-vehicle maker will be added to the broad stock-...",
"keywords": "Motor Vehicles, Alternative Fuel Vehicles, Trusts Funds Financial Vehicles, Diversified Holding Companies, Automotive",
"snippet": "S&P Dow Jones Indices said it will add Tesla Inc.’s full w...",
"url": "https://www.wsj.com/articles/tesla-to-enter-s-p-500-at-full-weight-in-december-11606780897?mod=pls_whats_news_us_business_f",
"image_url": "https://images.wsj.net/im-265933/social",
"language": "en",
"published_at": "2020-12-01T00:01:00.000000Z",
"source": "online.wsj.com",
"categories": [
"business"
],
"relevance_score": 128.22346
}
]
}
News by UUID Available on: All plans
Endpoint
GET https://api.thenewsapi.com/v1/news/uuid/uuid HTTP/1.1
Use this endpoint to find specific articles by the UUID which is returned on our search endpoints. This is useful if you wish to store the UUID to return the article later.
If you have issues with your requests, please ensure your GET parameters are URL-encoded.
All text data returned is UTF-8.
All dates are in UTC (GMT).
HTTP GET Parameters
name | required | description |
---|---|---|
api_token |
true | Your API token which can be found on your account dashboard. |
Response Objects
name | description |
---|---|
uuid |
The unique identifier for an article in our system. Store this and use it to find specific articles using our single article endpoint. |
title |
The article title. |
description |
The article meta description. |
keywords |
The article meta keywords. |
snippet |
The first 60 characters of the article body. |
url |
The URL to the article. |
image_url |
The URL to the article image. |
language |
The language of the source. |
published_at |
The datetime the article was published. |
source |
The domain of the source. |
categories |
Array of strings which the source is categorized as. |
If no results are found, a resource_not_found
error will be returned.
Example Request
GET https://api.thenewsapi.com/v1/news/uuid/147013d8-6c2c-4d50-8bad-eb3c8b7f5740?api_token=YOUR_API_TOKEN
Example Response
{
"uuid": "147013d8-6c2c-4d50-8bad-eb3c8b7f5740",
"title": "These Are The Four American Companies Worth Over $1 Trillion Each – 24",
"description": "America’s major market indexes set records in the early pa...",
"keywords": "",
"snippet": "These Are The Four American Companies Worth Over $1 Trillion...",
"url": "https://247wallst.com/investing/2020/10/17/these-are-the-four-american-companies-worth-over-1-trillion-each/",
"image_url": "https://247wallst.com/wp-content/uploads/2020/08/imageForEntry2-Qrj.jpg",
"language": "en",
"published_at": "2020-10-17T11:16:20.000000Z",
"source": "247wallst.com",
"categories": [
"business"
]
}
Sources Available on: All plans
Endpoint
GET https://api.thenewsapi.com/v1/news/sources HTTP/1.1
Use this endpoint to sources to use in your news API requests. Note that the limit is 50 for all requests.
If you have issues with your requests, please ensure your GET parameters are URL-encoded.
All text data returned is UTF-8.
HTTP GET Parameters
name | required | description |
---|---|---|
categories |
false | Comma separated list of categories to include
Example: business,tech
|
exclude_categories |
false | Comma separated list of categories to exclude |
language |
false | Comma separated list of languages to include. Default is all.
Click here for a list of supported languages. Examples: en,es (English + Spanish)
|
page |
false | Use this to paginate through the result set. Default is 1.
Example: page=2
|
Response Objects
name | description |
---|---|
meta > found |
The number of sources found for the request. |
meta > returned |
The number of sources returned on the page. |
meta > limit |
The limit is 50. This currently can not be changed. |
meta > page |
The page number based on the page parameter. |
data > source_id |
The unique ID of the source feed. Use this for the source_ids or exclude_source_ids parameters in the news endpoints.
There may be many source_ids for each domain, therefore we would generally suggest using the domains filter instead the source_ids filter. |
data > domain |
The domain of the source. You can use this for the domains or exclude_domains parameters in the news endpoints. |
data > language |
The source language. |
data > locale |
The source locale. Note that only select sources have locales. |
data > categories |
Array of strings which the source is categorized as. |
If no results are found, the data object will be empty.
Example Request
GET https://api.thenewsapi.com/v1/news/sources?api_token=YOUR_API_TOKEN&language=en
Example Response
{
"meta": {
"found": 15453,
"returned": 50,
"limit": 50,
"page": 1
},
"data": [
{
"source_id": "arstechnica.com-1",
"domain": "arstechnica.com",
"language": "en",
"locale": null,
"categories": [
"tech"
]
},
{
"source_id": "adweek.com-1",
"domain": "adweek.com",
"language": "en",
"locale": null,
"categories": [
"business"
]
},
...
Errors
Errors
If your request was unsuccessful, you will receive a JSON formatted error. Below you will find the potential errors you may encounter when using the API.
Errors
error code | HTTP status | description |
---|---|---|
malformed_parameters |
400 |
Validation of parameters failed. The failed parameters are usually shown in the error message. |
invalid_api_token |
401 |
Invalid API token. |
usage_limit_reached |
402 |
Usage limit of your plan has been reached. Usage limit and remaining requests can be found on the X-UsageLimit-Limit header. |
endpoint_access_restricted |
403 |
Access to the endpoint is not available on your current subscription plan. |
resource_not_found |
404 |
Resource could not be found. |
invalid_api_endpoint |
404 |
API route does not exist. |
rate_limit_reached |
429 |
Too many requests in the past 60 seconds. Rate limit and remaining requests can be found on the X-RateLimit-Limit header. |
server_error |
500 |
A server error occured. |
maintenance_mode |
503 |
The service is currently under maintenance. |
Example Error Response
{
"error": {
"code": "malformed_parameters",
"message": "The published_before parameter(s) are incorrectly formatted."
}
}
Examples
API Examples
Our endpoints are very useful for filtering to find only specific resources you need. Follow each example request below to see how you can build dynamic queries.
Example Request 1
This is a basic request which will return all articles which match the search term "usd" within the title or body of the article:
GET https://api.thenewsapi.com/v1/news/all?api_token=YOUR_API_TOKEN&search=usd
Example Request 2
This will return all articles which match the search term "usd" OR "gbp":
GET https://api.thenewsapi.com/v1/news/all?api_token=YOUR_API_TOKEN&search=usd | gbp
Example Request 3
This will return all articles which match the search term "usd" AND "gbp":
GET https://api.thenewsapi.com/v1/news/all?api_token=YOUR_API_TOKEN&search=usd + gbp
Example Request 4
This will return all articles which match the search term "usd" AND "gbp" but removes any articles which mentions "cad":
GET https://api.thenewsapi.com/v1/news/all?api_token=YOUR_API_TOKEN&search=usd + gbp -cad
Example Request 5
This will return all articles which match the search term "forex" AND "usd" OR "gbp" but removes any articles which mentions "cad":
GET https://api.thenewsapi.com/v1/news/all?api_token=YOUR_API_TOKEN&search=forex + (usd | gbp) -cad
Example Request 6
This is the same as Example Request 5 but will also ensure the articles returned are in English and categorized by business or tech but not travel, and are published within the last week:
GET https://api.thenewsapi.com/v1/news/all?api_token=YOUR_API_TOKEN&search=forex + (usd | gbp) -cad&language=en&categories=business,tech&exclude_categories=travel&published_after=2024-11-14
Code Examples
See our prepared examples below to quickly get started implementing our API into your next project.
PHP
$queryString = http_build_query([
'api_token' => 'YOUR_API_TOKEN',
'categories' => 'business,tech',
'search' => 'apple',
'limit' => 50,
]);
$ch = curl_init(sprintf('%s?%s', 'https://api.thenewsapi.com/v1/news/all', $queryString));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$json = curl_exec($ch);
curl_close($ch);
$apiResult = json_decode($json, true);
print_r($apiResult);
Python
# Python 3
import http.client, urllib.parse
conn = http.client.HTTPSConnection('api.thenewsapi.com')
params = urllib.parse.urlencode({
'api_token': 'YOUR_API_TOKEN',
'categories': 'business,tech',
'limit': 50,
})
conn.request('GET', '/v1/news/all?{}'.format(params))
res = conn.getresponse()
data = res.read()
print(data.decode('utf-8'))
Go
package main
import (
"fmt"
"io/ioutil"
"net/http"
"net/url"
)
func main() {
baseURL, _ := url.Parse("https://thenewsapi.com")
baseURL.Path += "v1/news/all"
params := url.Values{}
params.Add("api_token", "YOUR_API_TOKEN")
params.Add("categories", "business,tech")
params.Add("search", "apple")
params.Add("limit", "50")
baseURL.RawQuery = params.Encode()
req, _ := http.NewRequest("GET", baseURL.String(), nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(string(body))
}
JavaScript
var requestOptions = {
method: 'GET'
};
var params = {
api_token: 'YOUR_API_TOKEN',
categories: 'business,tech',
search: 'apple',
limit: '50'
};
var esc = encodeURIComponent;
var query = Object.keys(params)
.map(function(k) {return esc(k) + '=' + esc(params[k]);})
.join('&');
fetch("https://api.thenewsapi.com/v1/news/all?" + query, requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
C#
var client = new RestClient("https://api.thenewsapi.com/v1/news/all");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddQueryParameter("api_token", "YOUR_API_TOKEN");
request.AddQueryParameter("categories", "business,tech");
request.AddQueryParameter("search", "apple");
request.AddQueryParameter("limit", "50");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
HttpUrl.Builder httpBuilder = HttpUrl.parse("https://api.thenewsapi.com/v1/news/all").newBuilder();
httpBuilder.addQueryParameter("api_token", "YOUR_API_TOKEN");
httpBuilder.addQueryParameter("categories", "business,tech");
httpBuilder.addQueryParameter("search", "apple");
httpBuilder.addQueryParameter("limit", "50");
Request request = new Request.Builder().url(httpBuilder.build()).build();
Response response = client.newCall(request).execute();