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 extract article data from live links, check out articlextractor API .

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-05-29
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": "0db45905-b232-4405-ac6a-39325f512aa8",
                "title": "Morgan Spurlock's Ex-Wives Pay Tribute to Him After His Death",
                "description": "Morgan Spurlock’s ex-wives Sara Bernstein and Alex Jamieson paid tribute to the ‘Super Size Me’ filmmaker after his death at age 53",
                "keywords": "",
                "snippet": "Morgan Spurlock’s ex-wives are paying tribute to the Super Size Me filmmaker after he died from cancer complications at age 53 on Thursday, May 23.\n\nSara Bern...",
                "url": "https://www.usmagazine.com/celebrity-news/news/morgan-spurlocks-ex-wives-pay-tribute-to-him-after-his-death/",
                "image_url": "https://www.usmagazine.com/wp-content/uploads/2024/05/Morgan-Spurlock-Ex-Wives-Pay-Tribute-to-Him-After-His-Death-2.jpg?crop=0px%2C92px%2C1333px%2C700px&resize=1200%2C630&quality=86&strip=all",
                "language": "en",
                "published_at": "2024-05-28T19:10:24.000000Z",
                "source": "usmagazine.com",
                "categories": [
                    "entertainment",
                    "general"
                ],
                "locale": "us",
                "similar": [
                    {
                        "uuid": "2fdf92ed-ddfc-4eac-a853-f46c7095350b",
                        "title": "Sean Hayes Recalls Will and Grace Cast Receiving Death Threats",
                        "description": "Sean Hayes recalled the tumultuous time when the cast of ‘Will and Grace’ received death threats",
                        "keywords": "",
                        "snippet": "Sean Hayes recalled the tumultuous time when the cast of Will & Grace received death threats.\n\n“On the beginning of Will & Grace, we used to get death threats...",
                        "url": "https://www.usmagazine.com/entertainment/news/sean-hayes-recalls-will-and-grace-cast-receiving-death-threats/",
                        "image_url": "https://www.usmagazine.com/wp-content/uploads/2024/05/Feature-Sean-Hayes-Reveals-the-Cast-of-Will-and-Grace-Used-to-Receive-Death-Threats.jpg?crop=0px%2C21px%2C2000px%2C1051px&resize=1200%2C630&quality=86&strip=all",
                        "language": "en",
                        "published_at": "2024-05-28T18:23:11.000000Z",
                        "source": "usmagazine.com",
                        "categories": [
                            "entertainment",
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "6dd6dc8b-32c8-41dd-8ea4-7e3c2ca9290f",
                        "title": "Hilarie Burton Shares Rare Glimpse Into Life With Jeffrey Dean Morgan",
                        "description": "Hilarie Burton shared a romantic tribute to husband Jeffrey Dean Morgan to celebrate 15 years together, writing,",
                        "keywords": "",
                        "snippet": "Watch : Why Hilarie Burton Morgan Practices MAGIC Around Her Kids\n\nFifteen years ago Jeffrey Dean Morgan was able to make Hilarie Burton lie with him and just f...",
                        "url": "https://www.eonline.com/news/1402522/hilarie-burton-shares-rare-glimpse-into-family-life-with-jeffrey-dean-morgan-for-15-year-milestone?cmpid=rss-syndicate-genericrss-us-top_stories",
                        "image_url": "https://akns-images.eonline.com/eol_images/Entire_Site/2024428/cr_1200x1200-240528114439-GettyImages-2148219055.jpg?fit=around%7C1080:1080&output-quality=90&crop=1080:1080;center,top",
                        "language": "en",
                        "published_at": "2024-05-28T19:07:00.000000Z",
                        "source": "eonline.com",
                        "categories": [
                            "entertainment",
                            "general"
                        ],
                        "locale": "us"
                    }
                ]
            },
            {
                "uuid": "9b5749f7-8f2e-43e3-80cf-b8b3d8c841ff",
                "title": "NY v Trump: Prosecution says they have presented 'powerful evidence' against former president",
                "description": "New York prosecutors said presented the jury with their closing argument in the case against former President Trump Tuesday, saying that the case is “about a conspiracy and a cover-up,\" and maintained that they have presented “powerful evidence.\"",
                "keywords": "",
                "snippet": "New York prosecutors presented the jury with their closing argument in the case against former President Trump Tuesday, saying the case is \"about a conspiracy a...",
                "url": "https://www.foxnews.com/politics/ny-v-trump-prosecution-says-have-presented-powerful-evidence-against-former-president",
                "image_url": "https://static.foxnews.com/foxnews.com/content/uploads/2024/05/Trump-Speech-Photo-2.jpg",
                "language": "en",
                "published_at": "2024-05-29T00:24:06.000000Z",
                "source": "foxnews.com",
                "categories": [
                    "general",
                    "politics"
                ],
                "locale": "us",
                "similar": [
                    {
                        "uuid": "e2a71584-e7dc-4a4d-9e35-6a64c29c40bd",
                        "title": "Legal guru says prosecution fell 'way short' in Trump case, reasonable doubt is 'everywhere'",
                        "description": "A CNN guest legal expert said Tuesday that prosecutors failed to prove beyond a reasonable doubt that former President Trump is guilty of falsifying business records.",
                        "keywords": "",
                        "snippet": "Defense attorney Randy Zelin said Tuesday on CNN that prosecutors failed to prove beyond a reasonable doubt that former President Trump is guilty of falsifying ...",
                        "url": "https://www.foxnews.com/media/legal-guru-prosecution-fell-way-short-trump-case-reasonable-doubt-everywhere",
                        "image_url": "https://static.foxnews.com/foxnews.com/content/uploads/2024/05/CNN-Hush-money-trial.png",
                        "language": "en",
                        "published_at": "2024-05-28T20:32:01.000000Z",
                        "source": "foxnews.com",
                        "categories": [
                            "general",
                            "politics"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "75599800-e526-45ce-bc8a-3de0892ed389",
                        "title": "Dennis Quaid says 'weaponization of the justice system' pushed him to vote for 'a--hole' Trump",
                        "description": "Hollywood star Dennis Quaid, who recently portrayed Reagan, praised former President Trump, arguing that he genuinely is fighting for the American people.",
                        "keywords": "",
                        "snippet": "Dennis Quaid argued during a recent television interview that, rather than politics, it was the \"weaponization of the justice system\" and his policy record that...",
                        "url": "https://www.foxnews.com/media/dennis-quaid-says-weaponization-justice-system-pushed-him-vote-a-hole-trump",
                        "image_url": "https://static.foxnews.com/foxnews.com/content/uploads/2024/05/Dennis-Quaid-2.png",
                        "language": "en",
                        "published_at": "2024-05-28T23:13:37.000000Z",
                        "source": "foxnews.com",
                        "categories": [
                            "general",
                            "politics"
                        ],
                        "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-05-29T06:08:03 | 2024-05-29T06:08 | 2024-05-29T06 | 2024-05-29 | 2024-05 | 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-05-29T06:08:03 | 2024-05-29T06:08 | 2024-05-29T06 | 2024-05-29 | 2024-05 | 2024
published_on false Find all articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2024-05-29
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": 1045575,
        "returned": 10,
        "limit": 10,
        "page": 1
    },
    "data": [
        {
            "uuid": "e171d325-6bc0-43bd-abe0-d31a85b3c9ff",
            "title": "Sophia Smith says USWNT trusts new coach Emma Hayes",
            "description": "The directions called out by U.S. women's soccer coach Emma Hayes carried throughout the field as her team went through drills Tuesday in their first practice t...",
            "keywords": "",
            "snippet": "Gab Marcotti and Julien Laurens believe Emma Hayes had the perfect send off after Chelsea beat Manchester United and won their fifth WSL title in a row. (1:27)\n...",
            "url": "https://www.espn.com/soccer/story/_/id/40235964/sophia-smith-uswnt-coach-emma-hayes",
            "image_url": "https://a1.espncdn.com/combiner/i?img=%2Fphoto%2F2024%2F0430%2Fr1326612_1296x729_16%2D9.jpg",
            "language": "en",
            "published_at": "2024-05-29T05:50:32.000000Z",
            "source": "espn.com",
            "categories": [
                "sports",
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "65ea1354-1303-45ed-b834-6dbde484a4fd",
            "title": "Jurors could soon decide the fate of Idaho man charged in triple-murder case",
            "description": "Closing arguments are expected Wednesday in the case of an Idaho man accused of killing his wife and his girlfriend’s two youngest children",
            "keywords": "Fraud, Trials, Legal proceedings, Homicide, Juries, Crime, U.S. news, General news, Article, 110632475",
            "snippet": "Closing arguments are expected Wednesday in the case of an Idaho man accused of killing his wife and his girlfriend’s two youngest children\n\nBOISE, Idaho -- P...",
            "url": "https://abcnews.go.com/US/wireStory/jurors-decide-fate-idaho-man-charged-triple-murder-110632475",
            "image_url": "https://i.abcnewsfe.com/a/b2a81dc1-04ad-4175-96b7-c0231e7f0bae/wirestory_1f6832f009b61cd2627970af7dc1b6a3_16x9.jpg?w=1600",
            "language": "en",
            "published_at": "2024-05-29T05:34:26.000000Z",
            "source": "abcnews.go.com",
            "categories": [
                "general",
                "politics"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "dee29632-4055-4607-8ed4-b8dc969c84a1",
            "title": "'Shark Tank' star Kevin O'Leary said he wants to crowdfund buying TikTok",
            "description": "O'Leary said he wants to",
            "keywords": "",
            "snippet": "Kevin O'Leary said on Tuesday that he wants to crowdfund buying TikTok.\n\nThe move comes after US lawmakers agreed on a plan to ban Chinese-owned TikTok unless i...",
            "url": "https://www.businessinsider.com/kevin-oleary-crowdfund-tiktok-shark-tank-investor-accredited-campaign-valuation-2024-5",
            "image_url": "https://i.insider.com/6656a12c85e29ef64829bab3?width=1200&format=jpeg",
            "language": "en",
            "published_at": "2024-05-29T05:15:38.000000Z",
            "source": "businessinsider.com",
            "categories": [
                "business",
                "tech"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "2b824a72-f348-4a21-ba10-5f7aa2399597",
            "title": "Binance Gets Kudos From Gala Games For Help In $200M Hack Investigation",
            "description": "Gala Games (CRYPTO: GALA) expressed gratitude towards Binance (CRYPTO: BNB) for their assistance in identifying the perpetrator behind a recent hack, underscori...",
            "keywords": "",
            "snippet": "Loading... Loading...\n\nGala Games GALA/USD expressed gratitude towards Binance BNB/USD for their assistance in identifying the perpetrator behind a recent hack,...",
            "url": "https://www.benzinga.com/markets/cryptocurrency/24/05/39053788/binance-gets-kudos-from-gala-games-for-help-in-200m-hack-investigation",
            "image_url": "https://cdn.benzinga.com/files/images/story/2024/05/29/Binance-Photo-by-Iryna-Budanova-on-Shutt.jpeg?width=1200&height=800&fit=crop",
            "language": "en",
            "published_at": "2024-05-29T05:13:38.000000Z",
            "source": "benzinga.com",
            "categories": [
                "business"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "94d537a0-c746-4da5-90de-5a6c1aeb83d7",
            "title": "3 Women Speak Out About Sexual Assault Lawsuits Against Diddy",
            "description": "Three women have detailed the motivations behind their lawsuits against Sean ‘Diddy’ Combs",
            "keywords": "",
            "snippet": "Three women are speaking out about their sexual assault lawsuits against Sean ‘Diddy’ Combs for the first time.\n\nIn a report by Rolling Stone, published on ...",
            "url": "https://www.usmagazine.com/celebrity-news/news/3-women-speak-out-about-sexual-assault-lawsuits-against-diddy/",
            "image_url": "https://www.usmagazine.com/wp-content/uploads/2024/05/GettyImages-1641349666-Sean-Diddy-Combs-at-Invest-Fest.jpg?crop=0px%2C68px%2C1480px%2C777px&resize=1200%2C630&quality=86&strip=all",
            "language": "en",
            "published_at": "2024-05-29T05:07:53.000000Z",
            "source": "usmagazine.com",
            "categories": [
                "entertainment",
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "14bb7f57-41f0-4480-914d-c5dd502d707a",
            "title": "Wolfer Finance Launches a Token Sale on Akemona for a Greener Bitcoin",
            "description": "FREMONT, Calif., May 29, 2024 /PRNewswire/ -- Akemona, a leading funding portal and asset tokenization platform, announces the Wolfer Finance Corporation token ...",
            "keywords": "",
            "snippet": "Loading... Loading...\n\nFREMONT, Calif., May 29, 2024 /PRNewswire/ -- Akemona, a leading funding portal and asset tokenization platform, announces the Wolfer Fin...",
            "url": "https://www.benzinga.com/pressreleases/24/05/n39053716/wolfer-finance-launches-a-token-sale-on-akemona-for-a-greener-bitcoin",
            "image_url": "https://www.benzinga.com/next-assets/images/schema-image-default.png",
            "language": "en",
            "published_at": "2024-05-29T05:00:00.000000Z",
            "source": "benzinga.com",
            "categories": [
                "business"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "2c73db5b-ce2f-4975-805b-9a33e0144b40",
            "title": "Live updates: Israel-Hamas war in Gaza, deadly Rafah strike sparks global outcry",
            "description": "US President Joe Biden is not altering his policy toward Israel following an Israeli strike that killed more than 45 people in Rafah. Follow for live updates.",
            "keywords": "middleeast, Live updates: Israel-Hamas war in Gaza, deadly Rafah strike sparks global outcry",
            "snippet": "US-made munitions were used in a deadly Israeli strike on a camp for displaced Palestinians in Rafah, a CNN analysis of video from the scene and a review by exp...",
            "url": "https://www.cnn.com/middleeast/live-news/israel-hamas-war-gaza-news-05-29-24/index.html",
            "image_url": "https://cdn.cnn.com/cnnnext/dam/assets/240526184946-rafah-airstrike-052624-dle-card-super-tease.jpg",
            "language": "en",
            "published_at": "2024-05-29T04:38:05.000000Z",
            "source": "cnn.com",
            "categories": [
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "d688199b-109b-4133-8996-2da5ae5f738c",
            "title": "Mexico’s next president is likely a woman. But in some Indigenous villages, men have all the power",
            "description": "Seventy years ago, Mexican women won the right to vote, and today the country's on the verge of electing its first woman president.",
            "keywords": "Indigenous people, Mexico, Mexico government, General news, Global elections, AP Top News, i, Politics, Claudia Sheinbaum, Xochitl Galvez, World news",
            "snippet": "PLAN DE AYALA, Mexico (AP) — At 4:30 a.m., the girls and women begin to appear in the dark streets of this rural village of Tojolabal people in southern Mexic...",
            "url": "https://apnews.com/article/mexico-election-indigenous-women-activism-sheinbaum-galvez-8112a9da0bf2ddb564f20bd478da4d62",
            "image_url": "https://dims.apnews.com/dims4/default/3365d44/2147483647/strip/true/crop/4228x2378+0+220/resize/1440x810!/quality/90/?url=https%3A%2F%2Fassets.apnews.com%2F17%2F23%2F57cf1de0bc8f1b6cffbdf56e16bf%2Fae3efbf12f204b3b8c39169c1929818e",
            "language": "en",
            "published_at": "2024-05-29T04:23:01.000000Z",
            "source": "apnews.com",
            "categories": [
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "afdeb065-1a1c-4bf3-aec3-27158155feea",
            "title": "Caitlin Clark scores season-high 30 but Fever fall to Sparks",
            "description": "Indiana's Caitlin Clark on Tuesday night strung together her most complete game yet by scoring a season-best 30 points, dishing out 6 assists and grabbing 5 reb...",
            "keywords": "",
            "snippet": "Open Extended Reactions\n\nINDIANAPOLIS -- Caitlin Clark sees the progress -- even as the losses and frustration mount.\n\nOn Tuesday night, against the WNBA's only...",
            "url": "https://www.espn.com/wnba/story/_/id/40236974/caitlin-clark-scores-season-high-30-points-indiana-fever-lose-los-angeles-sparks",
            "image_url": "https://a.espncdn.com/combiner/i?img=%2Fphoto%2F2024%2F0529%2Fr1338975_1296x729_16%2D9.jpg",
            "language": "en",
            "published_at": "2024-05-29T04:16:31.000000Z",
            "source": "espn.com",
            "categories": [
                "sports",
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "5b31ad7f-e5a3-4fce-8b5c-e7471d84d5a8",
            "title": "Give Archie Panjabi an Emmy for ‘Under the Bridge’ Finale",
            "description": "The devastating series concludes with a sensational turn by the actress as the mother of a murdered teen.",
            "keywords": "Emmy Awards, Television, Hulu, TV/Movies",
            "snippet": "There are many things about Under the Bridge, Hulu’s devastating limited series that chronicles the period surrounding the brutal 1997 murder of Canadian teen...",
            "url": "https://www.thedailybeast.com/obsessed/under-the-bridge-finale-give-archie-panjabi-an-emmy",
            "image_url": "https://img.thedailybeast.com/image/upload/c_crop,d_placeholder_euli9k,h_1688,w_3000,x_0,y_0/dpr_2.0/c_limit,w_740/fl_lossy,q_auto/v1716930376/240528-under-the-bridge-tease_tpsmzu",
            "language": "en",
            "published_at": "2024-05-29T04:01:00.000000Z",
            "source": "thedailybeast.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-05-29T06:08:03 | 2024-05-29T06:08 | 2024-05-29T06 | 2024-05-29 | 2024-05 | 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-05-29T06:08:03 | 2024-05-29T06:08 | 2024-05-29T06 | 2024-05-29 | 2024-05 | 2024
published_on false Find all articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2024-05-29
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": 49454970,
        "returned": 10,
        "limit": 10,
        "page": 1
    },
    "data": [
        {
            "uuid": "7742e6f9-4be0-4a1c-a2b2-d3e7eb7e8f10",
            "title": "Powstał model zanieczyszczenia oceanów plastikiem",
            "description": "Ograniczenie zanieczyszczania plastikiem środowiska o 5 proc. rocznie ustabilizowałoby jego ilość na powierzchni oceanów. Jednak potrzeba bardziej radykaln...",
            "keywords": "",
            "snippet": "Oprócz widocznych, tworzących już wyspy plastikowych odpadków zaśmiecających oceany i morza, światowe wody coraz bardziej wypełnione są niewidocznymi n...",
            "url": "https://www.pb.pl/powstal-model-zanieczyszczenia-oceanow-plastikiem-1216976",
            "image_url": "https://images.pb.pl/filtered/00e84f8e-f639-4558-ac8c-d97619408e75/89cd7f96-c2a3-47cd-84fa-270759a438dd_og_1200_630.jpg",
            "language": "pl",
            "published_at": "2024-05-29T06:07:56.000000Z",
            "source": "pb.pl",
            "categories": [
                "business"
            ],
            "relevance_score": null
        },
        {
            "uuid": "e04cf99b-9af7-4b49-b2f8-e305474fb8c9",
            "title": "Prepare-se para receber o verão com sandálias coloridas nos pés",
            "description": "Há novidades no catálogo da Melissa.",
            "keywords": "noticias, nacional, internacional, economia, politica, desporto, fama, mundo, pais, futebol, tecnologia, cultura",
            "snippet": "Começou a fazer contagem decrescente para o verão? Tem de conhecer as novidades da Melissa. Porquê? Existem múltiplas opções coloridas e ideais para \"qual...",
            "url": "https://www.noticiasaominuto.com/lifestyle/2569849/prepare-se-para-receber-o-verao-com-sandalias-coloridas-nos-pes",
            "image_url": "https://media-manager.noticiasaominuto.com/1280/naom_6655a1371ee59.jpg?crop_params=eyJsYW5kc2NhcGUiOnsiY3JvcFdpZHRoIjoxOTIwLCJjcm9wSGVpZ2h0IjoxMDgwLCJjcm9wWCI6MCwiY3JvcFkiOjEwMzB9LCJwb3J0cmFpdCI6eyJjcm9wV2lkdGgiOjExNjMsImNyb3BIZWlnaHQiOjIwNjcsImNyb3BYIjozNTgsImNyb3BZIjo5OH19",
            "language": "pt",
            "published_at": "2024-05-29T06:06:49.000000Z",
            "source": "noticiasaominuto.com",
            "categories": [
                "entertainment"
            ],
            "relevance_score": null
        },
        {
            "uuid": "9988edf3-3808-4336-8590-b63324fdd817",
            "title": "미 펀드운용사 볼러틸리티 쉐어스, 레버리지 ETH ETF 6",
            "description": "미국 펀드 운용사 볼러틸리티 쉐어스(Volatility Shares)가 공식 웹사이트를 통해 레버리지 이더리움 ETF가 오는 6월 4일(현지?...",
            "keywords": "",
            "snippet": "",
            "url": "https://www.coinreaders.com/111786",
            "image_url": "https://www.coinreaders.com/data/coinreaders_com/banner/favicon.ico",
            "language": "ko",
            "published_at": "2024-05-29T06:06:29.000000Z",
            "source": "coinreaders.com",
            "categories": [],
            "relevance_score": null
        },
        {
            "uuid": "c1475692-85a9-4580-bd3b-ef9f426701f6",
            "title": "NY株反落、216ドル安 ナスダックは最高値|【西日本新聞me】",
            "description": "【ニューヨーク共同】連休明け28日のニューヨーク株式市場のダウ工業株30種平均は反落し、前週末比216・73ドル安...|?...",
            "keywords": "西日本新聞me, 西日本新聞, ニュース, 九州, 福岡",
            "snippet": "もうすぐ父の日。プレゼントやイベントごとについて教えてください!\n\n6月16日は「父の日」です。日ごろの感謝を伝?...",
            "url": "https://www.nishinippon.co.jp/item/o/1216699/",
            "image_url": "https://www.nishinippon.co.jp/uploads/image/1666214/sns_PN2024052901000190.-.-.CI0003.jpg",
            "language": "ja",
            "published_at": "2024-05-29T06:06:02.000000Z",
            "source": "nishinippon.co.jp",
            "categories": [],
            "relevance_score": null
        },
        {
            "uuid": "95da5d5c-ee8a-4fdf-b720-37b23be754f7",
            "title": "BusinessInfo.cz",
            "description": "Rozcestník ověřených informací z teritoria Macao, které exportéři potřebují pro úspěšný vstup na macajský zahraniční trh.",
            "keywords": "",
            "snippet": "",
            "url": "https://www.businessinfo.cz/navody/macao-souhrnna-teritorialni-informace/",
            "image_url": "https://storage.googleapis.com/businessinfo_cz/2021/01/925aee2d-macao-cina-shutterstock_1151228264-scaled.jpg",
            "language": "cs",
            "published_at": "2024-05-29T06:05:08.000000Z",
            "source": "businessinfo.cz",
            "categories": [
                "business"
            ],
            "relevance_score": null
        },
        {
            "uuid": "25d7aa2c-1d27-40d9-89a7-d6480929c657",
            "title": "П.С. Чиков. Пособие по сбору и заготовке лекарственных растений",
            "description": "",
            "keywords": "",
            "snippet": "",
            "url": "http://cwer.ru/node/563079/",
            "image_url": "http://cwer.ru/media/favicon.ico",
            "language": "ru",
            "published_at": "2024-05-29T06:05:00.000000Z",
            "source": "cwer.ru",
            "categories": [],
            "relevance_score": null
        },
        {
            "uuid": "7e02d018-3ba1-46b4-a988-49115a4ec153",
            "title": "В Самарской области уголовник подозревается в убийстве знакомого",
            "description": "Новости Тольятти - В Самарской области уголовник подозревается в убийстве знакомого",
            "keywords": "Новости Тольятти - В Самарской области уголовник подозревается в убийстве знакомого",
            "snippet": "18+\n\nСледственным отделом по городу Кинелю возбуждено уголовное дело в отношении ранее н...",
            "url": "https://tltgorod.ru/news/?theme=29&news=135823",
            "image_url": "https://tltgorod.ru/favicon.ico",
            "language": "ru",
            "published_at": "2024-05-29T06:05:00.000000Z",
            "source": "tltgorod.ru",
            "categories": [
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "d4838b19-3d3c-489b-9100-fa6ad84abf08",
            "title": "MLB Highlights: Blue Jays 7, White Sox 2",
            "description": "",
            "keywords": "",
            "snippet": "Sign in to Sportsnet\n\nSign In Sign Up\n\nFirst Name {* traditionalRegistration_firstName *} {* traditionalRegistration_firstName *} Last Name {* traditionalRegist...",
            "url": "https://www.sportsnet.ca/mlb/video/mlb-highlights-blue-jays-7-white-sox-2/",
            "image_url": "https://www.sportsnet.ca/sn_favicon.ico",
            "language": "en",
            "published_at": "2024-05-29T06:04:13.000000Z",
            "source": "sportsnet.ca",
            "categories": [
                "sports"
            ],
            "relevance_score": null
        },
        {
            "uuid": "d16bd172-6a8a-4195-8cb0-1f4a01369e72",
            "title": "사우디, 아람코 지분 최대 200억弗어치 매각 추진",
            "description": "사우디아라비아 정부가 국영 석유기업 아람코의 지분 가운데 최대 200억달러어치를 이번 주 매각한다.28일(현지시간) 외?...",
            "keywords": "",
            "snippet": "(뉴욕=연합인포맥스) 진정호 특파원 = 사우디아라비아 정부가 국영 석유기업 아람코의 지분 가운데 최대 200억달러어치를...",
            "url": "https://news.einfomax.co.kr/news/articleView.html?idxno=4311148",
            "image_url": "https://cdn.news.einfomax.co.kr/news/thumbnail/202405/4311148_192242_32_v150.jpg",
            "language": "ko",
            "published_at": "2024-05-29T06:02:16.000000Z",
            "source": "news.einfomax.co.kr",
            "categories": [
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "71ab2ed8-cb09-447d-8b3b-5799c8a34177",
            "title": "Q4 2024 S H Kelkar and Company Ltd Earnings Call Transcript",
            "description": "Refinitiv StreetEvents Event TranscriptE D I T E D   V E R S I O NSHKE.NS - S H Kelkar And Company LtdQ4 2024 S H Kelkar and Company Ltd Earnings CallMay 28, 20",
            "keywords": "GuruFocus, Article, News, GuruFocus Research, BOM:539450",
            "snippet": "\n\n\n\nRefinitiv StreetEvents Event Transcript\n\nE D I T E D V E R S I O N\n\n\n\nSHKE.NS - S H Kelkar And Company Ltd\n\nQ4 2024 S H Kelkar and Company Ltd Earnings Call...",
            "url": "https://www.gurufocus.com/news/2447321/q4-2024-s-h-kelkar-and-company-ltd-earnings-call-transcript",
            "image_url": "https://static.gurufocus.com/images/global_logo_twitter_card.png",
            "language": "en",
            "published_at": "2024-05-29T06:01:46.000000Z",
            "source": "gurufocus.com",
            "categories": [
                "business"
            ],
            "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-05-29T06:08:03 | 2024-05-29T06:08 | 2024-05-29T06 | 2024-05-29 | 2024-05 | 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-05-29T06:08:03 | 2024-05-29T06:08 | 2024-05-29T06 | 2024-05-29 | 2024-05 | 2024
published_on false Find all articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2024-05-29
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=2024-05-22
    

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();
    

More

Stock Market News APIs

We also provide a dedicated finance and stock market news and analysis API, perfect for financial apps. Check it out here: marketaux.com.