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: 2026-05-20
|
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": "46989fec-8f59-4986-8045-898ee4be1d3b",
"title": "San Diego mosque shooters livestreamed deadly attack as FBI probes footage",
"description": "A livestream video of the mass shooting attack at the Islamic Center of San Diego is making rounds on social media showing Cain Clark and Caleb Velasquez.",
"keywords": "Metro, US News, california, exclusive, san diego, social media, suicide",
"snippet": "See more of our coverage in your search results.\n\nThe FBI is investigating footage the San Diego mosque shooters livestreamed during their brutal attack on an I...",
"url": "https://nypost.com/2026/05/19/us-news/san-diego-mosque-shooters-livestreamed-deadly-attack-as-fbi-probes-footage/",
"image_url": "https://nypost.com/wp-content/uploads/sites/2/2026/05/newspress-collage-hpprnwxii-1779216630536.jpg?quality=75&strip=all&1779202333&w=1200",
"language": "en",
"published_at": "2026-05-19T18:55:15.000000Z",
"source": "nypost.com",
"categories": [
"general"
],
"locale": "us",
"similar": [
{
"uuid": "2d55ad05-b559-4312-b47a-a762badc6268",
"title": "Fundraiser for hero security guard killed in San Diego mosque shooting tops $1M in less than 24 hours",
"description": "Amin Abdullah, a security guard at the mosque, is being hailed as a hero for his actions during Monday’s shooting at the Islamic Center in San Diego.",
"keywords": "Metro, US News, islamophobia, mass shootings, suicide",
"snippet": "See more of our coverage in your search results.\n\nA LaunchGood fundraiser for the security guard hailed as a hero for protecting a San Diego Islamic Center, aft...",
"url": "https://nypost.com/2026/05/19/us-news/fundraiser-for-guard-killed-in-san-diego-mosque-shooting-tops-1m/",
"image_url": "https://nypost.com/wp-content/uploads/sites/2/2026/05/128224947.jpg?quality=75&strip=all&w=1200",
"language": "en",
"published_at": "2026-05-19T19:07:58.000000Z",
"source": "nypost.com",
"categories": [
"general"
],
"locale": "us"
},
{
"uuid": "72fedc0e-4393-459e-8f8c-4aaba94ba167",
"title": "Watch: San Diego officials provide new info on heroism during Islamic Center shooting",
"description": "Officials in San Diego took questions Tuesday about Monday's shooting at the Islamic Center of San Diego, giving new details on some of the heroic actions taken by the three victims to draw the shooters away from the children who were present at the mosque. Following the news conference, CBS News national correspondent Lana Zak provided additional reporting.",
"keywords": "Shooting, Islam, San Diego",
"snippet": "Watch: San Diego officials provide new info on heroism during Islamic Center shooting Officials in San Diego took questions Tuesday about Monday's shooting at t...",
"url": "https://www.cbsnews.com/video/watch-san-diego-officials-give-update-on-islamic-center-shooting/",
"image_url": "https://assets3.cbsnewsstatic.com/hub/i/r/2026/05/19/09272e42-bd98-49b9-9359-89fa1ce4fd72/thumbnail/1200x630/f8e2b099603c837471af63cf0018b288/cbsn-fusion-watch-san-diego-officials-give-update-on-islamic-center-shooting-thumbnail.jpg",
"language": "en",
"published_at": "2026-05-19T19:48:38.000000Z",
"source": "cbsnews.com",
"categories": [
"general",
"politics"
],
"locale": "us"
},
{
"uuid": "bb171104-a573-4ddc-a76a-f2a6f0ae9fd8",
"title": "Identities of 2 more victims killed in San Diego mosque shooting revealed",
"description": "The three victims killed Monday by two teen gunmen at the Islamic Center of San Diego were identified Tuesday.",
"keywords": "Metro, US News, islamophobia, mass shootings, muslims, san diego",
"snippet": "See more of our coverage in your search results.\n\nTwo more members of San Diego Muslim community have been identified among those killed in Monday’s horror sh...",
"url": "https://nypost.com/2026/05/19/us-news/victims-killed-in-shooting-at-san-diego-mosque-identified/",
"image_url": "https://nypost.com/wp-content/uploads/sites/2/2026/05/128227854.jpg?quality=75&strip=all&w=1200",
"language": "en",
"published_at": "2026-05-19T20:02:54.000000Z",
"source": "nypost.com",
"categories": [
"general"
],
"locale": "us"
},
{
"uuid": "8cdf261d-f296-44d4-aa21-bc8a44221c2e",
"title": "Investigators looking into manifesto left by San Diego shooting suspects",
"description": "Investigators say they are looking into a 75-page manifesto left by the suspects in the San Diego mosque shooting. The documents, which authorities say are filled with extremist material against minorities and praise the shooter in the Christchurch massacre in New Zealand, were found in the suspects' vehicle. NBC News correspondent Tom Winter outlines some of the details of the documents, which NBC News has reviewed.",
"keywords": "",
"snippet": "Investigators say they are looking into a 75-page manifesto left by the suspects in the San Diego mosque shooting. The documents, which authorities say are fill...",
"url": "https://www.nbcnews.com/now/video/investigators-looking-into-manifesto-left-by-san-diego-shooting-suspects-263595589760",
"image_url": "https://media-cldnry.s-nbcnews.com/image/upload/t_nbcnews-fp-1200-630,f_auto,q_auto:best/mpx/2704722219/2026_05/1779222718521_now_daily_b_san_diego_shooting_260519_S3_1920x1080-y8kbly.jpg",
"language": "en",
"published_at": "2026-05-19T20:32:06.000000Z",
"source": "nbcnews.com",
"categories": [
"general",
"politics"
],
"locale": "us"
},
{
"uuid": "c91f9501-b02c-4d5b-82ed-0378a93b0ace",
"title": "Manifesto reveals motive behind Islamic Center of San Diego shooting",
"description": "Caleb Vasquez and Cain Clark accused of killing three people outside the San Diego mosque were allegedly motivated by racial and ethnic hatred.",
"keywords": "Metro, US News, antisemitism, california, exclusive, islamophobia, mass shootings, muslims, san diego",
"snippet": "See more of our coverage in your search results.\n\nA shocking manifesto filled with racial and ethnic hatred linked to the teen terrorists who killed three peopl...",
"url": "https://nypost.com/2026/05/19/us-news/manifesto-reveals-motive-behind-islamic-center-of-san-diego-shooting/",
"image_url": "https://nypost.com/wp-content/uploads/sites/2/2026/05/128232543.jpg?quality=75&strip=all&w=1200",
"language": "en",
"published_at": "2026-05-19T21:35:38.000000Z",
"source": "nypost.com",
"categories": [
"general"
],
"locale": "us"
}
]
},
{
"uuid": "4c8655c9-f701-4353-bcd2-26ca8cb90040",
"title": "Rep. Thomas Massie ousted in Kentucky by Trump-backed Ed Gallrein: ‘A true American Patriot’",
"description": "The contest for Kentucky's 4th Congressional District will go down as the most expensive primary race in US history, with more than $32 million spent on political ads, according to the firm AdImpact.",
"keywords": "Politics, US News, donald trump, kentucky, midterm elections 2026, primaries, republicans, us house of representatives",
"snippet": "See more of our coverage in your search results.\n\nRep. Thomas Massie (R-Ky.) lost Tuesday night’s House primary to President Trump’s hand-picked challenger,...",
"url": "https://nypost.com/2026/05/19/us-news/rep-thomas-massie-ousted-in-kentucky-by-trump-backed-ed-gallrein/",
"image_url": "https://nypost.com/wp-content/uploads/sites/2/2026/05/128164627.jpg?quality=75&strip=all&w=1200",
"language": "en",
"published_at": "2026-05-19T23:55:42.000000Z",
"source": "nypost.com",
"categories": [
"general"
],
"locale": "us",
"similar": [
{
"uuid": "5dde028b-5910-4eac-bc38-e3d00e8b6f87",
"title": "Trump-endorsed Ed Gallrein unseats Rep. Thomas Massie in Kentucky GOP primary",
"description": "Former Navy SEAL Ed Gallrein has won the Republican primary in Kentucky’s 4th Congressional District over Rep. Thomas Massie.",
"keywords": "",
"snippet": "Former Navy SEAL Ed Gallrein has won the Republican primary in Kentucky’s 4th Congressional District over Rep. Thomas Massie, NBC News projects, notching anot...",
"url": "https://www.nbcnews.com/politics/2026-election/kentucky-house-district-4-winners-primary-election-gallrein-massie-rcna345010",
"image_url": "https://media-cldnry.s-nbcnews.com/image/upload/t_nbcnews-fp-1200-630,f_auto,q_auto:best/rockcms/2026-05/260513-Rep-94cf2a.jpg",
"language": "en",
"published_at": "2026-05-19T23:48:36.000000Z",
"source": "nbcnews.com",
"categories": [
"general",
"politics"
],
"locale": "us"
},
{
"uuid": "dd2d529f-8227-4901-a4de-2d399e54577a",
"title": "Ed Gallrein beats Rep. Thomas Massie in Kentucky primary, NBC News projects",
"description": "Trump-backed Republican candidate Ed Gallrein beats Rep. Thomas Massie in the primary for Kentucky's 4th Congressional District. Former Navy SEAL Gallrein has been a vocal supporter of President Trump, and was aided by an extraordinary advertising blitz fueled largely by pro-Trump and pro-Israel groups.",
"keywords": "",
"snippet": "Trump-backed Republican candidate Ed Gallrein beats Rep. Thomas Massie in the primary for Kentucky's 4th Congressional District. Former Navy SEAL Gallrein has b...",
"url": "https://www.nbcnews.com/now/video/ed-gallrein-beats-rep-thomas-massie-in-kentucky-primary-nbc-news-projects-263614021808",
"image_url": "https://media-cldnry.s-nbcnews.com/image/upload/t_nbcnews-fp-1200-630,f_auto,q_auto:best/mpx/2704722219/2026_05/1779235345676_now_brk_gallrein_kentucky_260519_S3_1920x1080-lzh6ql.jpg",
"language": "en",
"published_at": "2026-05-20T00:02:52.000000Z",
"source": "nbcnews.com",
"categories": [
"politics",
"general"
],
"locale": "us"
},
{
"uuid": "14bcadf2-48bb-492e-abf4-b0a2ba5b4105",
"title": "Kentucky primaries results: Massie ousted by Trump-backed Gallrein",
"description": "Republican Rep. Thomas Massie will lose his reelection bid to Ed Gallrein, who was backed by President Donald Trump, ABC News projects.",
"keywords": "",
"snippet": "The race was the most expensive U.S. House primary in history.\n\nRep. Thomas Massie in Washington Sept. 17, 2025 and Republican congressional candidate for Kentu...",
"url": "https://abcnews.com/Politics/kentucky-2026-live-primary-election-results/story?id=132581024",
"image_url": "https://i.abcnewsfe.com/a/d67d3b2f-6f1d-4152-ab70-55e800566ca1/massie-Gallrein-ap-gmh-260513_1778679101777_hpMain_16x9.jpg?w=1600",
"language": "en",
"published_at": "2026-05-20T00:16:03.000000Z",
"source": "abcnews.go.com",
"categories": [
"general"
],
"locale": "us"
},
{
"uuid": "6b8c78b3-95fb-4226-9ef9-db6d64b0288d",
"title": "Rep. Thomas Massie loses Kentucky House GOP primary to Ed Gallrein, CBS News projects",
"description": "CBS News projects that Rep. Thomas Massie has lost Kentucky's House primary to former Navy SEAL Ed Gallrein, the latest Republican incumbent to fall to a Trump-backed candidate. CBS News' Ed O'Keefe and Anthony Salvanto have the latest.",
"keywords": "Republicans, Voting, Israel, Politics, Election, Kentucky, U.S. House of Representatives, Jeffrey Epstein",
"snippet": "Rep. Thomas Massie loses Kentucky House GOP primary to Ed Gallrein, CBS News projects CBS News projects that Rep. Thomas Massie has lost Kentucky's House primar...",
"url": "https://www.cbsnews.com/video/thomas-massie-loses-kentucky-house-gop-primary-cbs-news-projects/",
"image_url": "https://assets3.cbsnewsstatic.com/hub/i/r/2026/05/20/c797fe7d-1d2a-4170-a511-84402235a2af/thumbnail/1200x630/e82ef883f13f312706a6f7452f906b4f/cbsn-fusion-thomas-massie-loses-kentucky-house-gop-primary-cbs-news-projects-thumbnail.jpg",
"language": "en",
"published_at": "2026-05-20T00:12:28.000000Z",
"source": "cbsnews.com",
"categories": [
"general",
"politics"
],
"locale": "us"
},
{
"uuid": "f74dd14a-41df-455c-b7e8-3b1145aac965",
"title": "Massie concedes Kentucky House primary to Gallrein: 'We've been honorable'",
"description": "Kentucky Rep. Thomas Massie thanked his supporters and announced that he has called Navy veteran Ed Gallrein to concede the Republican House primary. Massie described the race as \"the most expensive congressional primary ever in the 250-year history of this country.\"",
"keywords": "",
"snippet": "Kentucky Rep. Thomas Massie thanked his supporters and announced that he has called Navy veteran Ed Gallrein to concede the Republican House primary. Massie des...",
"url": "https://www.nbcnews.com/video/massie-concedes-kentucky-house-primary-to-gallrein-263613509954",
"image_url": "https://media-cldnry.s-nbcnews.com/image/upload/t_nbcnews-fp-1200-630,f_auto,q_auto:best/mpx/2704722219/2026_05/1779238229392_now_brk_massie_concedes_gallrein_260519_S3_1920x1080-bm05qw.jpg",
"language": "en",
"published_at": "2026-05-20T00:50:38.000000Z",
"source": "nbcnews.com",
"categories": [
"politics",
"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,keywordsDefault: 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: 2026-05-20T03:59:17 |
2026-05-20T03:59 |
2026-05-20T03 |
2026-05-20 |
2026-05 |
2026
|
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: 2026-05-20T03:59:17 |
2026-05-20T03:59 |
2026-05-20T03 |
2026-05-20 |
2026-05 |
2026
|
published_on |
false | Find all articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2026-05-20
|
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": 1626566,
"returned": 10,
"limit": 10,
"page": 1
},
"data": [
{
"uuid": "07da8f58-3c1f-4c9e-a556-9137ed81163d",
"title": "Mercedes’ electric AMG GT 4-door coupe can go 0-60 in 2 seconds",
"description": "Mercedes announced the new AMG GT 4-door coupe with a 0-60 acceleration time of 2 seconds.",
"keywords": "",
"snippet": "is transportation editor with 10+ years of experience who covers EVs, public transportation, and aviation. His work has appeared in The New York Daily News and ...",
"url": "https://www.theverge.com/news/934037/mercedes-amg-gt-four-door-coupe-ev-specs",
"image_url": "https://platform.theverge.com/wp-content/uploads/sites/2/2026/05/pre-media_26c0129_001.jpg?quality=90&strip=all&crop=0%2C10.732984293194%2C100%2C78.534031413613&w=1200",
"language": "en",
"published_at": "2026-05-20T03:46:46.000000Z",
"source": "theverge.com",
"categories": [
"tech"
],
"relevance_score": null,
"locale": "us"
},
{
"uuid": "f1a0a9f7-094a-46ac-a9d7-62d37328d997",
"title": "Democrat Jon Ossoff skates as Georgia GOP Senate primary drags on to runoff election",
"description": "The Georgia Republican Senate primary will head to runoff election after no candidate secured the 50% of the vote necessary to advance Tuesday.",
"keywords": "Politics, US News, donald trump, georgia, jon ossoff, midterm elections 2026, primaries, republicans, senate",
"snippet": "See more of our coverage in your search results.\n\nThe Georgia Republican Senate primary will be settled in a runoff next month after no candidate secured a majo...",
"url": "https://nypost.com/2026/05/19/us-news/democrat-jon-ossoff-skates-as-georgia-gop-senate-primary-drags-on-to-runoff-election/",
"image_url": "https://nypost.com/wp-content/uploads/sites/2/2026/05/newspress-collage-lo409z2e4-1779154256862.jpg?quality=75&strip=all&1779139891&w=1200",
"language": "en",
"published_at": "2026-05-20T03:32:33.000000Z",
"source": "nypost.com",
"categories": [
"general"
],
"relevance_score": null,
"locale": "us"
},
{
"uuid": "60a449d1-08fe-4741-a894-9910c906c972",
"title": "Longtime owner of NYC kosher bakery, 75, found shot to death along Queens shoreline",
"description": "Albert Itzkowitz, 75, was a prominent elderly member of the Queens Jewish community and longtime bakery owner, according to Yeshiva World News.",
"keywords": "Metro, US News, deaths, flushing, investigations, queens, shootings",
"snippet": "See more of our coverage in your search results.\n\nA prominent elderly member of the Jewish community and longtime bakery owner was found shot to death along a Q...",
"url": "https://nypost.com/2026/05/19/us-news/longtime-owner-of-nyc-kosher-bakery-75-found-shot-to-death-along-queens-shoreline/",
"image_url": "https://nypost.com/wp-content/uploads/sites/2/2026/05/Untitled-1-2026-05-19T230820.547.jpg?quality=75&strip=all&w=1200",
"language": "en",
"published_at": "2026-05-20T03:26:27.000000Z",
"source": "nypost.com",
"categories": [
"general"
],
"relevance_score": null,
"locale": "us"
},
{
"uuid": "b7bcc2a3-215c-42a0-895a-e2ef98d05565",
"title": "School board member who hugged teen and called her ‘hot’ is charged with assault",
"description": "The charge stems from an incident on April 2, when Keith Ervin hugged the girl, a student member of the board, and told her, “God, you’re hot.”",
"keywords": "",
"snippet": "A Tennessee school board member who hugged a teenage girl and called her “hot” at a public meeting last month has been charged with assault, court records s...",
"url": "https://www.nbcnews.com/news/us-news/school-board-member-hugged-teen-called-hot-charged-assault-rcna346023",
"image_url": "https://media-cldnry.s-nbcnews.com/image/upload/t_nbcnews-fp-1200-630,f_auto,q_auto:best/rockcms/2026-04/260408-keith-ervin-ew-547p-194552.jpg",
"language": "en",
"published_at": "2026-05-20T03:26:24.000000Z",
"source": "nbcnews.com",
"categories": [
"general",
"politics"
],
"relevance_score": null,
"locale": "us"
},
{
"uuid": "959d84de-47a2-41e4-abc6-a3471b41da58",
"title": "‘In The City’ Premiere Episode Addresses ‘Summer House’ Scandal As The Bravoverse Expands",
"description": "Bravo extended the Summer House universe with one of the most seamless transitions into a spinoff series since The Real Housewives of Beverly Hills and Vanderpu...",
"keywords": "",
"snippet": "SPOILER ALERT: This post contains details about the Summer House Season 10 finale and the In the City Season 1 premiere.\n\nBravo extended the Summer House univer...",
"url": "https://deadline.com/2026/05/in-the-city-premiere-summer-house-scandal-bravo-1236916477/",
"image_url": "https://deadline.com/wp-content/uploads/2026/05/in-the-city-amanda-batula-kyle-cooke.jpg?w=1024",
"language": "en",
"published_at": "2026-05-20T03:25:18.000000Z",
"source": "deadline.com",
"categories": [
"entertainment"
],
"relevance_score": null,
"locale": "us"
},
{
"uuid": "f0019a6c-f38b-469f-b667-ca9c84eeef3e",
"title": "Jones talks November face-off with Tuberville for Alabama governor",
"description": "Democratic Sen. Doug Jones spoke with NBC News’ Hallie Jackson and Kristen Welker about his upcoming rematch with Republican Sen. Tommy Tuberville in the Alab...",
"keywords": "",
"snippet": "Democratic Sen. Doug Jones spoke with NBC News’ Hallie Jackson and Kristen Welker about his upcoming rematch with Republican Sen. Tommy Tuberville in the Alab...",
"url": "https://www.nbcnews.com/now/video/jones-talks-november-face-off-with-tuberville-for-alabama-governor-263619653957",
"image_url": "https://media-cldnry.s-nbcnews.com/image/upload/t_nbcnews-fp-1200-630,f_auto,q_auto:best/mpx/2704722219/2026_05/1779247092502_now_brk_jones_tuberville_faceoff_alabama_governor_260519_S3_1920x1080-ox9571.jpg",
"language": "en",
"published_at": "2026-05-20T03:18:20.000000Z",
"source": "nbcnews.com",
"categories": [
"politics",
"general"
],
"relevance_score": null,
"locale": "us"
},
{
"uuid": "883672d4-b337-4b0b-82fb-81dd9d30949d",
"title": "Civil war declared as Chad Bianco torches Republican gubernatorial rival Steve Hilton, despite lagging in the polls",
"description": "Riverside County Sheriff Chad Bianco is torching Republican rival Steve Hilton's campaign as a “full-blown lie” and claims he's been “bought and paid for?...",
"keywords": "Metro, US News, Politics, california, elections, gavin newsom, republicans, Steve Hilton",
"snippet": "See more of our coverage in your search results.\n\nA bitter GOP civil war is erupting in California’s governor race with Riverside County Sheriff Chad Bianco t...",
"url": "https://nypost.com/2026/05/19/us-news/chad-bianco-torches-republican-gubernatorial-rival-steve-hilton/",
"image_url": "https://nypost.com/wp-content/uploads/sites/2/2026/05/128264393.jpg?quality=75&strip=all&w=1200",
"language": "en",
"published_at": "2026-05-20T03:14:15.000000Z",
"source": "nypost.com",
"categories": [
"general"
],
"relevance_score": null,
"locale": "us"
},
{
"uuid": "158be6db-fd5a-4b7e-8b15-4b241a45467b",
"title": "Trump-backed Rep. Barry Moore heads to a runoff in Alabama GOP Senate primary",
"description": "NBC News projects Moore didn’t clear the 50% threshold to advance to the general election. His runoff opponent remains unclear.",
"keywords": "",
"snippet": "Rep. Barry Moore advanced Tuesday to a Republican Senate primary runoff in Alabama as two rivals battled for the second spot in the race, NBC News projects.\n\nSu...",
"url": "https://www.nbcnews.com/politics/2026-election/alabama-senate-election-winners-primary-race-barry-moore-rcna345003",
"image_url": "https://media-cldnry.s-nbcnews.com/image/upload/t_nbcnews-fp-1200-630,f_auto,q_auto:best/rockcms/2026-05/260513-Rep-Barry-Moore-vsb-1842-f76670.jpg",
"language": "en",
"published_at": "2026-05-20T03:11:28.000000Z",
"source": "nbcnews.com",
"categories": [
"general",
"politics"
],
"relevance_score": null,
"locale": "us"
},
{
"uuid": "022888e4-d90e-4033-b6f7-1a0e39d4e451",
"title": "Firefighters union boss wins hotly-contested Dem primary in a key Pennsylvania swing district",
"description": "Pennsylvania's 7th District chose its Democratic nominee in a hotly-contested primary featuring firefighters union boss Bob Brooks, endorsed by Gov. Josh Shapir...",
"keywords": "bernie sanders, democrats elections, primary results, pennsylvania, republicans, politics",
"snippet": "NEW You can now listen to Fox News articles!\n\nOne of the nation’s most narrowly divided swing congressional districts chose its Democratic nominee Tuesday eve...",
"url": "https://www.foxnews.com/politics/union-boss-declared-hotly-contested-democratic-primary-key-pennsylvania-district",
"image_url": "https://static.foxnews.com/foxnews.com/content/uploads/2026/05/ryan-mackenzie-at-mount-airy-casino-lodge.jpg",
"language": "en",
"published_at": "2026-05-20T03:02:41.000000Z",
"source": "foxnews.com",
"categories": [
"general",
"politics"
],
"relevance_score": null,
"locale": "us"
},
{
"uuid": "c48578b0-fb63-4056-b538-bd495371d696",
"title": "Welcome to Plathville’s Lydia Confirms She and Zac Didn’t Wait a Week to Have Sex After Wedding",
"description": "Lydia Plath opens up about her intimacy timeline with husband Zac Wyse on 'Welcome to Plathville' and when they had sex",
"keywords": "",
"snippet": "Welcome to Plathville’s Lydia Plath and Zac Wyse were vocal about saving their first kiss for their wedding day — so how long did they wait to have sex?\n\nDu...",
"url": "https://www.usmagazine.com/entertainment/news/welcome-to-plathvilles-lydia-talks-sex-timeline-with-husband/",
"image_url": "https://www.usmagazine.com/wp-content/uploads/2026/05/Welcome-to-Plathvilles-Lydia-Confirms-She-and-Zac-Didnt-Wait-a-Week-to-Have-Sex-After-Wedding.jpg?crop=0px%2C311px%2C1500px%2C787px&resize=1200%2C630&quality=40&strip=all",
"language": "en",
"published_at": "2026-05-20T03:01:56.000000Z",
"source": "usmagazine.com",
"categories": [
"entertainment",
"general"
],
"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,keywordsDefault: 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: 2026-05-20T03:59:17 |
2026-05-20T03:59 |
2026-05-20T03 |
2026-05-20 |
2026-05 |
2026
|
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: 2026-05-20T03:59:17 |
2026-05-20T03:59 |
2026-05-20T03 |
2026-05-20 |
2026-05 |
2026
|
published_on |
false | Find all articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2026-05-20
|
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": 54023093,
"returned": 10,
"limit": 10,
"page": 1
},
"data": [
{
"uuid": "a86ffd41-c3a1-4a01-9a13-49b0da354df0",
"title": "Brunson ties it late as Knicks force overtime in Game 1 vs. Cavaliers",
"description": "",
"keywords": "",
"snippet": "Brunson ties it late as Knicks force overtime in Game 1 vs. Cavaliers\n\nJalen Brunson ties Game 1 at 101-101 with a clutch bucket late in the fourth quarter befo...",
"url": "https://www.sportsnet.ca/nba/video/brunson-ties-it-late-as-knicks-force-overtime-in-game-1-vs-cavaliers/",
"image_url": "https://www.sportsnet.ca/sn_favicon.ico",
"language": "en",
"published_at": "2026-05-20T03:59:30.000000Z",
"source": "sportsnet.ca",
"categories": [
"sports"
],
"relevance_score": null
},
{
"uuid": "08f7b360-2b38-44b2-9452-1a42073ea03e",
"title": "글로벌 최대 비트코인 ATM 업체 파산보호 신청 - 경향게임스",
"description": "글로벌 최대 규모 가상화폐 자동입출금기(이하 ATM) 운용사이자 미국 나스닥 상장사인 비트코인디포(Bitcoin Depot)가 챕터11 ...",
"keywords": "",
"snippet": "글로벌 최대 규모 가상화폐 자동입출금기(이하 ATM) 운용사이자 미국 나스닥 상장사인 비트코인디포(Bitcoin Depot)가 챕터11 ...",
"url": "https://www.khgames.co.kr/news/articleView.html?idxno=304498",
"image_url": "https://cdn.khgames.co.kr/news/photo/202605/304498_307893_5315.jpg",
"language": "ko",
"published_at": "2026-05-20T03:54:50.000000Z",
"source": "khgames.co.kr",
"categories": [],
"relevance_score": null
},
{
"uuid": "1bfa3338-1703-4093-9014-bff5a04f89d3",
"title": "Breaking down Blue Jays’ ninth-inning comeback attempt vs. Yankees",
"description": "",
"keywords": "",
"snippet": "Jamie Campbell and Caleb Joseph discuss the Blue Jays’ string of bad luck, particularly in the ninth inning, where they set themselves up for a comeback, but ...",
"url": "https://www.sportsnet.ca/mlb/video/breaking-down-blue-jays-ninth-inning-comeback-attempt-vs-yankees/",
"image_url": "https://www.sportsnet.ca/sn_favicon.ico",
"language": "en",
"published_at": "2026-05-20T03:54:18.000000Z",
"source": "sportsnet.ca",
"categories": [
"sports"
],
"relevance_score": null
},
{
"uuid": "87698f36-01bf-48a3-94a5-e428ef5cccef",
"title": "Hello Kitty dostaje pełny metraż. Poznajcie szczegóły filmu Warner Bros.",
"description": "New Line Cinema i Warner Bros. Pictures Animation ogłosiły kinowy debiut w Hollywood postaci Hello Kitty. Studia biorą się za realizację animacji, której ...",
"keywords": "Hello Kitty dostaje pełny metraż. Poznajcie szczegóły filmu Warner Bros.",
"snippet": "New Line Cinema i Warner Bros. Pictures Animation ogłosiły kinowy debiut w Hollywood postaci Hello Kitty. Studia biorą się za realizację animacji, której ...",
"url": "https://fdb.pl/wiadomosci/59290-hello-kitty-dostaje-pelny-metraz-poznajcie-szczegoly-filmu-warner-bros",
"image_url": "https://v1.fdbimg.pl/crop?height=658&noprofile=true&quality=80&sign=HnffN9Wpb-alhsB71MM5mFoE7nSvI6lhnuCdOEOUqD4&stripmeta=true&type=webp&url=https%3A%2F%2Fi11.fdbimg.pl%2Fi%2Fb%2Ft%2Fy%2Fbty0p1b0hsrxjy546l3u9yvb9r35&width=1160",
"language": "pl",
"published_at": "2026-05-20T03:54:10.000000Z",
"source": "fdb.pl",
"categories": [],
"relevance_score": null
},
{
"uuid": "14f9ceb4-47e2-4e05-bf48-79b51f3df371",
"title": "ABC zamawia nowy spin-off serialu \"Chirurdzy\"",
"description": "W ABC powstaje nowy spin-off flagowego serialu Chirurdzy. Stacja zamówiła niezatytułowany na razie projekt osadzony w ramach tej popularnej serii.",
"keywords": "ABC zamawia nowy spin-off serialu",
"snippet": "ABC zamawia nowy spin-off serialu \"Chirurdzy\" 0\n\nW ABC powstaje nowy spin-off flagowego serialu Chirurdzy. Stacja zamówiła niezatytułowany na razie projekt o...",
"url": "https://fdb.pl/wiadomosci/59291-abc-zamawia-nowy-spin-off-serialu-chirurdzy",
"image_url": "https://v1.fdbimg.pl/crop?height=649&noprofile=true&quality=80&sign=IfyaPmdX1t9FcDEEPF0UZx87InwUDaIB89loyhTp9nE&stripmeta=true&type=webp&url=https%3A%2F%2Fi11.fdbimg.pl%2Fi%2Ft%2F3%2F5%2Ft35w3f5znjwuqh75vcrle4geb8gp&width=996",
"language": "pl",
"published_at": "2026-05-20T03:54:10.000000Z",
"source": "fdb.pl",
"categories": [],
"relevance_score": null
},
{
"uuid": "95454be9-2eb6-4ac4-86d7-7070d87b9ab7",
"title": "Téléchargez les sous-titres de la release « Mary.and.Max.2009.DVDRip.XviD-TheWretched » sur SubSynchro",
"description": "Voici la liste des fichiers pour le film « Mary et Max » adaptés pour la release « Mary.and.Max.2009.DVDRip.XviD-TheWretched »",
"keywords": "Mary, and, Max, 2009, DVDRip, XviD, TheWretched",
"snippet": "Ajouté par SubSynchro\n\nAjoute le 20-05-2026 01:51:36\n\nImporté de OpenSubtitles\n\nFormat : SRT\n\nItalique : Non\n\nTaille : 78,6Ko\n\nTelechargement : 1\n\nAjouter cet...",
"url": "https://www.subsynchro.com/2009/mary-and-max/mary-and-max-2009-dvdrip-xvid-thewretched/fichier-2962.html",
"image_url": "https://www.subsynchro.com/img/vignettes/2009/mary-et-max.jpg",
"language": "fr",
"published_at": "2026-05-20T03:51:36.000000Z",
"source": "subsynchro.com",
"categories": [],
"relevance_score": null
},
{
"uuid": "b861296b-48a9-4e8b-808c-0aa153fb5b08",
"title": "Nach Kabeldiebstahl - weiterhin Einschränkungen bei S-Bahn",
"description": "Nach einem Kabeldiebstahl am Baumschulenweg bleibt der S-Bahn-Verkehr in Berlin gestört. Auf mehreren Linien kommt es zu Verspätungen und geänderten Fahrplä...",
"keywords": "Kabeldiebstahl, Baumschulenweg, Berlin, Einschränkung, Schöneweide",
"snippet": "Es kommt es weiterhin zu Verspätungen und Einschränkungen bei der S-Bahn. (Symbolbild)\n\nEs kommt es weiterhin zu Verspätungen und Einschränkungen bei der S-...",
"url": "https://web.de/magazine/regio/berlin/kabeldiebstahl-einschraenkungen-s-bahn-42290248",
"image_url": "https://i0.web.de/image/250/42290250,pd=1,f=opengraph/einschraenkungen-s-bahn.jpg",
"language": "de",
"published_at": "2026-05-20T03:50:09.000000Z",
"source": "web.de",
"categories": [
"general"
],
"relevance_score": null
},
{
"uuid": "c6d582f4-6411-4e03-b6f4-984da7284c31",
"title": "Jones, Jackson Advance to GOP Runoff for Ga. Governor",
"description": "Lt. Gov. Burt Jones and healthcare billionaire Rick Jackson have advanced to the June 16 Republican runoff for Georgia governor, extending a bruising campaign b...",
"keywords": "Georgia, Election 2026, Brad Raffensperger, Keisha Lance Bottoms",
"snippet": "Lt. Gov. Burt Jones and healthcare billionaire Rick Jackson have advanced to the June 16 Republican runoff for Georgia governor, extending a bruising campaign b...",
"url": "https://www.newser.com/story/389470/jones-jackson-advance-to-gop-runoff-for-ga-governor.html",
"image_url": "https://img1-azrcdn.newser.com/image/1686096-12-20260519214957.jpeg",
"language": "en",
"published_at": "2026-05-20T03:49:57.000000Z",
"source": "newser.com",
"categories": [
"general",
"politics"
],
"relevance_score": null
},
{
"uuid": "972056a1-33d4-4872-ae32-076d59a27a70",
"title": "Apresentador dispara tiro de fuzil ao vivo em TV no Irã como 'treinamento'",
"description": "Apresentador efetuou disparo dentro do estúdio da televisão estatal iraniana, em iniciativa do governo que busca ensinar cidadãos a manejarem armas de fogo",
"keywords": "",
"snippet": "A demonstração na TV aconteceu em meio a oficinas espalhadas pela capital Teerã, e que têm o mesmo objetivo. Em uma praça da cidade, um integrante da Guard...",
"url": "https://noticias.uol.com.br/internacional/ultimas-noticias/2026/05/19/apresentador-ira-fuzil-estudio.ghtm",
"image_url": "https://conteudo.imguol.com.br/c/noticias/8a/2026/05/19/apresentador-do-ira-dispara-tiro-de-fuzil-ao-vivo-na-tv-durante-treinamento-do-exercito-1779225054514_v2_615x300.png",
"language": "pt",
"published_at": "2026-05-20T03:49:24.000000Z",
"source": "uol.com.br",
"categories": [
"tech",
"science"
],
"relevance_score": null
},
{
"uuid": "bc76d1ac-041e-4efe-9407-9b4fb92bf9ac",
"title": "食べたメロンの種をまいてみたら、2キロの大玉メロンができた！",
"description": "こんにちは、のりんごです。今回はスーパーで買ったメロンから種を取って育てる方法について紹介します。本来メロ?...",
"keywords": "",
"snippet": "こんにちは、のりんごです。今回はスーパーで買ったメロンから種を取って育てる方法について紹介します。本来メロ?...",
"url": "https://agri.mynavi.jp/2026_05_20_506608/",
"image_url": "https://agri.mynavi.jp/wp-content/uploads/2026/05/add7c73d27337be7d7f03cbf3b763bf3.jpg",
"language": "ja",
"published_at": "2026-05-20T03:48:52.000000Z",
"source": "agri.mynavi.jp",
"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: 2026-05-20T03:59:17 |
2026-05-20T03:59 |
2026-05-20T03 |
2026-05-20 |
2026-05 |
2026
|
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: 2026-05-20T03:59:17 |
2026-05-20T03:59 |
2026-05-20T03 |
2026-05-20 |
2026-05 |
2026
|
published_on |
false | Find all articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2026-05-20
|
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%20%7C%20gbp
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%20%2B%20gbp
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%20%2B%20gbp%20-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%20%2B%20%28usd%20%7C%20gbp%29%20-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%20%2B%20%28usd%20%7C%20gbp%29%20-cad&language=en&categories=business%2Ctech&exclude_categories=travel&published_after=2026-05-13
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();