Documentation

Sign up for free!

Get instant access to the API with your free API token. No billing details required!

Sign up now

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-04-18
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": "f04aa1b4-cc9e-4caa-ae32-a14ef03779c4",
                "title": "Biden warned Israel against attacking Israel",
                "description": "In his latest gaffe, Joe Biden describes how he’d warned Israel against attacking itself, urging the Jewish state not to attack its own city",
                "keywords": "",
                "snippet": "In his latest gaffe, the US leader described how he told the Jewish state not to attack the city of Haifa\n\nUS President Joe Biden told an interviewer that he’...",
                "url": "https://www.rt.com/news/596190-biden-israel-attack-gaffe/",
                "image_url": "https://mf.b37mrtl.ru/files/2024.04/article/66210ca585f540752f471f4b.jpg",
                "language": "en",
                "published_at": "2024-04-18T12:13:09.000000Z",
                "source": "rt.com",
                "categories": [
                    "general",
                    "politics"
                ],
                "locale": "us",
                "similar": [
                    {
                        "uuid": "02bc9295-e39b-42ad-a538-46a08b111127",
                        "title": "Trump's Manhattan trial should stay off-limits for Biden",
                        "description": "Joe Biden has stayed silent on Donald Trump being on trial in New York despite how a conviction on the felony charges could affect the 2024 election.",
                        "keywords": "",
                        "snippet": "Former President Donald Trump isn’t exactly known for having a sense of generosity. There’s one area in which he’s been extremely giving, however: providi...",
                        "url": "https://www.msnbc.com/opinion/msnbc-opinion/trump-manhattan-trial-biden-comment-rcna148201",
                        "image_url": "https://media-cldnry.s-nbcnews.com/image/upload/t_nbcnews-fp-1200-630,f_auto,q_auto:best/rockcms/2024-04/240417-donald-trump-joe-biden-vl-344p-49e9c7.jpg",
                        "language": "en",
                        "published_at": "2024-04-18T10:00:00.000000Z",
                        "source": "msnbc.com",
                        "categories": [
                            "general",
                            "politics"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "d0a092ef-bd39-4ecc-81c1-134ef7ac00dd",
                        "title": "It’s Time for Biden to Press for a Regional Cease-Fire With Teeth",
                        "description": "Israel and Iran have flexed their muscles. But all this must stop here and now. Time to lead, Joe.",
                        "keywords": "",
                        "snippet": "Iranians, though, didn’t want to start a war—rather, they wanted to draw a marker in the sand. They wanted to make sure that the Israelis understood that th...",
                        "url": "https://newrepublic.com/article/180761/biden-israel-iran-regional-ceasefire",
                        "image_url": "https://images.newrepublic.com/747c46bdd423d82cd989f0cefc84381ac91337c7.jpeg?w=1200&h=630&crop=faces&fit=crop&fm=jpg",
                        "language": "en",
                        "published_at": "2024-04-18T10:00:00.000000Z",
                        "source": "newrepublic.com",
                        "categories": [
                            "general",
                            "politics",
                            "entertainment"
                        ],
                        "locale": "us"
                    }
                ]
            },
            {
                "uuid": "8748c6a6-18af-4e2c-be0c-08c6ac726476",
                "title": "Live updates: Trump New York hush money criminal trial",
                "description": "Jury selection will continue Thursday in former President Donald Trump's hush money criminal trial. Follow here for the latest live news updates.",
                "keywords": "politics, Live updates: Trump New York hush money criminal trial",
                "snippet": "Former President Donald Trump sits beside his lawyer Todd Blanche on the second day of jury selection in his criminal trial in Manhattan Criminal Court in New Y...",
                "url": "https://www.cnn.com/politics/live-news/trump-hush-money-trial-04-18-24/index.html",
                "image_url": "https://cdn.cnn.com/cnnnext/dam/assets/240415171845-trump-trial-super-tease.jpg",
                "language": "en",
                "published_at": "2024-04-18T11:53:41.000000Z",
                "source": "cnn.com",
                "categories": [
                    "general"
                ],
                "locale": "us",
                "similar": [
                    {
                        "uuid": "91b04162-b444-42f9-8102-b70302d99f7c",
                        "title": "Polish president meets with Trump in New York City amid criminal trial",
                        "description": "Former President Donald Trump met with Polish President Andrzej Duda at Trump Tower in New York City, New York on Wednesday during an off-day of his criminal trial.",
                        "keywords": "",
                        "snippet": "Former President Donald Trump continues to meet with foreign leaders, even as his criminal trial is underway in New York.\n\nTrump met with Polish President Andrz...",
                        "url": "https://www.foxnews.com/politics/polish-president-meets-trump-new-york-city-criminal-trial",
                        "image_url": "https://static.foxnews.com/foxnews.com/content/uploads/2024/04/GettyImages-2149039899-scaled-e1713435741831.jpg",
                        "language": "en",
                        "published_at": "2024-04-18T11:05:17.000000Z",
                        "source": "foxnews.com",
                        "categories": [
                            "general",
                            "politics"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "c11aefd6-4c9d-4661-ad02-c70ce1b4ff56",
                        "title": "Live updates Jury selection to continue in Trump hush money trial",
                        "description": "Jury selection in Donald Trump’s hush money trial in New York is scheduled to continue Thursday. Five more jurors and six alternates need to be selected.",
                        "keywords": "",
                        "snippet": "Potential jurors’ identities are being kept secret, though the judge is allowing them to provide some personal details in court. Here is what we know about th...",
                        "url": "https://www.washingtonpost.com/politics/2024/04/18/trump-hush-money-trial-live-updates/",
                        "image_url": "https://www.washingtonpost.com/wp-apps/imrs.php?src=https://arc-anglerfish-washpost-prod-washpost.s3.amazonaws.com/public/K2LMBQXXIVUJWDYSKB24TUVLW4.JPG&w=1440",
                        "language": "en",
                        "published_at": "2024-04-18T12:44:55.000000Z",
                        "source": "washingtonpost.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,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-04-18T13:45:13 | 2024-04-18T13:45 | 2024-04-18T13 | 2024-04-18 | 2024-04 | 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-04-18T13:45:13 | 2024-04-18T13:45 | 2024-04-18T13 | 2024-04-18 | 2024-04 | 2024
published_on false Find all articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2024-04-18
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": 1017427,
        "returned": 10,
        "limit": 10,
        "page": 1
    },
    "data": [
        {
            "uuid": "679e40de-847a-437c-a72e-2bd17c97e837",
            "title": "Motorola's plan to sell smartphones overseas includes wood and fake leather",
            "description": "Motorola is hedging its bets on AI-infused software features to attract users",
            "keywords": "Motorola, LG, Motorola Edge, Comparison of smartphones, Samsung, Qualcomm, Hospitality, Recreation, Technology, Internet, Phablets, The Motorola, Motorola Mobility, Quartz",
            "snippet": "Motorola has announced its new family of flagships, the Edge 50 series. The series features three new models, from premium to mid-range, available in various fi...",
            "url": "https://qz.com/motorola-wood-fake-leather-smartphone-sales-1851418863",
            "image_url": "https://i.kinja-img.com/image/upload/c_fill,h_675,pg_1,q_80,w_1200/cd32450104e012970d390660737293c5.png",
            "language": "en",
            "published_at": "2024-04-18T13:33:59.000000Z",
            "source": "qz.com",
            "categories": [
                "general",
                "business",
                "tech",
                "entertainment"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "1a8d2256-3a8e-40b6-896a-e23cff62b3ef",
            "title": "Disneyland is spending almost $2 billion on a huge expansion",
            "description": "The $1.9 billion expansion plan will take decades to finish",
            "keywords": "Disneyland, Disney, Entertainment, Culture, Disneyland Resort, Disney California Adventure, Walt Disney Imagineering, Happiest Homecoming on Earth, Shanghai Disney Resort, Disney Experiences, Tokyo DisneySea, Tron, The Walt Disney Company, THE WALT DISNEY COMPANY, Bob Iger, Walt Disney Parks and Resorts, James Cameron, Quartz",
            "snippet": "Disneyland Forward, the Walt Disney Company’s initiative to expand its original theme park, just got the go-ahead from the Anaheim City Council. Deadline repo...",
            "url": "https://qz.com/disneyland-expansion-approved-anaheim-avatar-1851418843",
            "image_url": "https://i.kinja-img.com/image/upload/c_fill,h_675,pg_1,q_80,w_1200/f920e865bdb7ec3d78a414bcf90214ff.png",
            "language": "en",
            "published_at": "2024-04-18T13:30:26.000000Z",
            "source": "qz.com",
            "categories": [
                "general",
                "business",
                "tech",
                "entertainment"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "d139c0f5-4a23-4d62-b6e8-2feae8a7d98e",
            "title": "Removing PFAS from public water systems will cost billions and take time – here are ways to filter out some harmful ‘forever chemicals’ at home",
            "description": "Filtering out PFAS is only the first step. These ‘forever chemicals’ still have to be destroyed, and there are many questions about how to do that safely.",
            "keywords": "",
            "snippet": "Chemists invented PFAS in the 1930s to make life easier: Nonstick pans, waterproof clothing, grease-resistant food packaging and stain-resistant carpet were all...",
            "url": "https://theconversation.com/removing-pfas-from-public-water-systems-will-cost-billions-and-take-time-here-are-ways-to-filter-out-some-harmful-forever-chemicals-at-home-227670",
            "image_url": "https://images.theconversation.com/files/588157/original/file-20240416-22-dxssqu.jpg?ixlib=rb-4.1.0&rect=10%2C1314%2C3631%2C1813&q=45&auto=format&w=1356&h=668&fit=crop",
            "language": "en",
            "published_at": "2024-04-18T13:23:43.000000Z",
            "source": "theconversation.com",
            "categories": [
                "general",
                "politics"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "eca9fbd1-8275-41d4-9328-f5aaec065684",
            "title": "Donald Trump Arrives For Third Day Of Hush Money Trial After Posting Attack On Potential Jurors",
            "description": "The former president posted Jesse Watters swipe at potential jurors in the case.",
            "keywords": "",
            "snippet": "Donald Trump arrived at a Manhattan courthouse this morning for the third day in his hush money trial, but there are new questions as to whether he will be admo...",
            "url": "https://deadline.com/2024/04/trump-hush-money-trial-jurors-1235888939/",
            "image_url": "https://deadline.com/wp-content/uploads/2024/04/GettyImages-2147900149.jpg?w=1024",
            "language": "en",
            "published_at": "2024-04-18T13:20:12.000000Z",
            "source": "deadline.com",
            "categories": [
                "entertainment"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "e40f905b-39d8-4c96-baf7-da6eaf75d1aa",
            "title": "Billionaire Kam Ghaffarian sets his sights on the stars with a range of space companies",
            "description": "Ghaffarian has been instrumental in ushering in the new space economy, with leadership roles at Intuitive Machines, Axiom Space, Quantum Space and X-Energy.",
            "keywords": "Energy, Intuitive Machines Inc, Technology, Breaking News: Technology, Transportation, Breaking News: Business, Space industry, Tesla Inc, Apple Inc, Amazon.com Inc, Alphabet Inc, Intuitive Machines Equity Warrants Exp 13th Feb 2028, Environment, Jeff Bezos, Space exploration, Science, business news",
            "snippet": "Kam Ghaffarian, co-founder and chairman of Axiom Space Inc., speaks during an interview at the company's headquarters in Houston, Texas, U.S., on Friday, Jan. 1...",
            "url": "https://www.cnbc.com/2024/04/18/kam-ghaffarian-sets-his-sights-on-the-stars-with-space-companies.html",
            "image_url": "https://image.cnbcfm.com/api/v1/image/107402702-1713377813681-gettyimages-1240584919-PRIVATE_SPACE_STATION.jpeg?v=1713377887&w=1920&h=1080",
            "language": "en",
            "published_at": "2024-04-18T13:18:28.000000Z",
            "source": "cnbc.com",
            "categories": [
                "general",
                "business"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "fbca5ee2-fe86-495c-bc15-571a712690b0",
            "title": "American Express, Interactive Brokers And More On CNBC’s ‘Final Trades’ - Interactive Brokers Gr (NASDAQ:IBKR), American Express (NYSE:AXP)",
            "description": "On CNBC’s",
            "keywords": "",
            "snippet": "Loading... Loading...\n\nOn CNBC’s \"Halftime Report Final Trades,\" Bryn Talkington of Requisite Capital Management named Pacer US Cash Cows 100 ETF COWZ, which ...",
            "url": "https://www.benzinga.com/trading-ideas/long-ideas/24/04/38312343/american-express-interactive-brokers-and-more-on-cnbcs-final-trades",
            "image_url": "https://cdn.benzinga.com/files/images/story/2024/04/18/american_express_amex.jpg?width=1200&height=800&fit=crop",
            "language": "en",
            "published_at": "2024-04-18T13:17:25.000000Z",
            "source": "benzinga.com",
            "categories": [
                "business"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "744c95f9-cdfc-4231-a26d-aac5bcc190ff",
            "title": "SEC Chair Gary Gensler Pulls Off Resignation Prank On X, Drawing Mixed Reactions From Crypto Community",
            "description": "The tone of the message led many to anticipate a resignation announcement, only to be surprised when Gensler concluded with,",
            "keywords": "",
            "snippet": "Loading... Loading...\n\nIn an unexpected twist on social media, Gary Gensler, the Chair of the U.S. Securities and Exchange Commission (SEC), set off a flurry of...",
            "url": "https://www.benzinga.com/markets/cryptocurrency/24/04/38314220/sec-chair-pulls-off-resignation-troll-on-x-but-crypto-community-isnt-so-amused",
            "image_url": "https://cdn.benzinga.com/files/images/story/2024/04/18/Photo-Created-with-an-image-from-Shutter.jpeg?width=1200&height=800&fit=crop",
            "language": "en",
            "published_at": "2024-04-18T13:15:10.000000Z",
            "source": "benzinga.com",
            "categories": [
                "business"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "39b23a7e-6162-4ea9-b3a2-c212b31d0bc7",
            "title": "We're making a small buy of this troubled cosmetics firm and upgrading our rating on the stock",
            "description": "The purchase increases the stock's weighting in the portfolio to 2.1% from 1.9%.",
            "keywords": "Breaking News: Markets, Markets, Investment strategy, Jim Cramer, Estee Lauder Companies Inc, business news",
            "snippet": "Shortly after the opening bell, we will be buying 50 shares of Estee Lauder at roughly $139. Following the trade, Jim Cramer's Charitable Trust will own 475 sha...",
            "url": "https://www.cnbc.com/2024/04/18/were-making-a-small-buy-of-this-troubled-cosmetics-firm-and-upgrading-our-rating-on-the-stock.html",
            "image_url": "https://image.cnbcfm.com/api/v1/image/106290834-1576083862662gettyimages-1186290115.jpeg?v=1713442668&w=1920&h=1080",
            "language": "en",
            "published_at": "2024-04-18T13:15:07.000000Z",
            "source": "cnbc.com",
            "categories": [
                "general",
                "business"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "bd30e094-8b19-4ff5-b9a0-8e5c72770c3d",
            "title": "Sen. Jack Reed Questions Merrick Garland On Cannabis Banking Bill's Broader Financial Regulations",
            "description": "Sen. Jack Reed (D-RI) raised concerns with Attorney General Merrick Garland regarding the Secure and Fair Enforcement (SAFER) Banking Act in a recent Senate A...",
            "keywords": "",
            "snippet": "Loading... Loading...\n\nSen. Jack Reed (D-RI) raised concerns with Attorney General Merrick Garland regarding the Secure and Fair Enforcement (SAFER) Banking Act...",
            "url": "https://www.benzinga.com/analyst-ratings/analyst-color/24/04/38305370/sen-jack-reed-questions-merrick-garland-on-cannabis-banking-bills-broader-financial",
            "image_url": "https://cdn.benzinga.com/files/images/story/2024/04/17/dalle_2024-04-17_21.01.42_-_.jpeg?width=1200&height=800&fit=crop",
            "language": "en",
            "published_at": "2024-04-18T13:15:01.000000Z",
            "source": "benzinga.com",
            "categories": [
                "business"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "83e5292a-a127-428f-a6db-9fc3ec0c3865",
            "title": "How To Earn $500 A Month From Ford Stock Ahead Of Q1 Earnings Report - Ford Motor (NYSE:F)",
            "description": "Ford Motor Company (NYSE: F) is set to release earnings results for its first quarter on April 24.",
            "keywords": "",
            "snippet": "Loading... Loading...\n\nFord Motor Company F is set to release earnings results for its first quarter on April 24.\n\nAnalysts expect the Dearborn, Michigan-based ...",
            "url": "https://www.benzinga.com/news/earnings/24/04/38312420/how-to-earn-500-a-month-from-ford-stock-ahead-of-q1-earnings-report",
            "image_url": "https://cdn.benzinga.com/files/images/story/2024/04/18/ford.jpg?width=1200&height=800&fit=crop",
            "language": "en",
            "published_at": "2024-04-18T13:12:35.000000Z",
            "source": "benzinga.com",
            "categories": [
                "business"
            ],
            "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-04-18T13:45:13 | 2024-04-18T13:45 | 2024-04-18T13 | 2024-04-18 | 2024-04 | 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-04-18T13:45:13 | 2024-04-18T13:45 | 2024-04-18T13 | 2024-04-18 | 2024-04 | 2024
published_on false Find all articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2024-04-18
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": 49882015,
        "returned": 10,
        "limit": 10,
        "page": 1
    },
    "data": [
        {
            "uuid": "241ce513-c75c-4e9d-95d5-3d0442d49659",
            "title": "에코앤드림, 2025년 1월 새만금 공장 준공 목표",
            "description": "에코앤드림이 전구체 생산능력 증설을 추진한다. 2025년까지 전구체 생산능력을 연간 3만5000톤으로 확대할 계획이다.전구...",
            "keywords": "에코앤드림, 전구체, 양극재, 배터리, 새만금공장",
            "snippet": "에코앤드림 관계자 \"투자금 조달 문제 없어\"\n\n사업 확장에 따른 채용 진행 중\n\n(사진=에코앤드림)\n\n에코앤드림이 전구체 ?...",
            "url": "https://www.thelec.kr/news/articleView.html?idxno=27288",
            "image_url": "https://cdn.thelec.kr/news/thumbnail/202404/27288_25252_1952_v150.jpg",
            "language": "ko",
            "published_at": "2024-04-18T13:45:43.000000Z",
            "source": "thelec.kr",
            "categories": [
                "tech",
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "75c819ae-aa34-4d3b-b4c2-f428f5702a3c",
            "title": "[기자수첩]총선 그리고 아무도 없었다",
            "description": "제22대 국회의원 선거가 끝나면서 여의도에 입성할 300명이 확정됐다. 총선은 민심의 풍향계라고 하는 만큼 다양한 직종?...",
            "keywords": "",
            "snippet": "정원기 기자\n\n제22대 국회의원 선거가 끝나면서 여의도에 입성할 300명이 확정됐다. 총선은 민심의 풍향계라고 하는 만큼 ...",
            "url": "https://www.engdaily.com/news/articleView.html?idxno=17776",
            "image_url": "http://www.engdaily.com/news/thumbnail/202404/17776_13907_1045_v150.jpg",
            "language": "ko",
            "published_at": "2024-04-18T13:45:31.000000Z",
            "source": "engdaily.com",
            "categories": [
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "79563fcc-cbf6-4d73-8179-a9fafe928022",
            "title": "與",
            "description": "국민의힘이 더불어민주당의 추가경정예산(추경) 편성 요구에 포퓰리즘을 거두라고 비판했다.국민의힘 정희용 수석대변?...",
            "keywords": "",
            "snippet": "(서울=연합인포맥스) 한종화 기자 = 국민의힘이 더불어민주당의 추가경정예산(추경) 편성 요구에 포퓰리즘을 거두라고 ?...",
            "url": "https://news.einfomax.co.kr/news/articleView.html?idxno=4306354",
            "image_url": "https://cdn.news.einfomax.co.kr/news/thumbnail/202404/4306354_187947_462_v150.jpg",
            "language": "ko",
            "published_at": "2024-04-18T13:45:25.000000Z",
            "source": "news.einfomax.co.kr",
            "categories": [
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "c2abf396-84a7-4c65-a321-e997d162a944",
            "title": "余承东再访合肥 华为江汽“第四界”呼之欲出 前景如何",
            "description": "余承东再访合肥 华为江汽“第四界”呼之欲出 前景如何",
            "keywords": "华为, 电动车, 造车新势力, 余承东再访合肥 华为江汽“第四界”呼之欲出 前景如何, 快科技",
            "snippet": "余承东再访合肥 华为江汽“第四界”呼之欲出 前景如何\n\n在2024北京车展即将到来之际，余承东再次来到合肥，瞬间成为?...",
            "url": "https://news.mydrivers.com/1/975/975095.htm",
            "image_url": "https://img1.mydrivers.com/img/20240418/464b4c4aec1f4dc4a9fe365782054bb1.png",
            "language": "zh",
            "published_at": "2024-04-18T13:45:16.000000Z",
            "source": "news.mydrivers.com",
            "categories": [
                "tech",
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "bedd2ed5-aba0-404d-b40e-15a6e830af06",
            "title": "Italie entre ciel et mer - Le Latium - Regarder le documentaire complet",
            "description": "Deuxième région la plus peuplée d’Italie après la Lombardie, le Latium, qui entoure Rome, compte de nombreux joyaux, comme le romantique jardin de Ninfa a...",
            "keywords": "",
            "snippet": "Regarder Les mille facettes des Pyrénées Des ours et du sport 44 min Voir le programme\n\n44 min",
            "url": "https://www.arte.tv/fr/videos/107787-004-F/italie-entre-ciel-et-mer/",
            "image_url": "https://api-cdn.arte.tv/img/v2/image/sGBxujX3UheooT4QDZYvr7/1920x1080?type=TEXT&watermark=true",
            "language": "fr",
            "published_at": "2024-04-18T13:45:00.000000Z",
            "source": "arte.tv",
            "categories": [
                "entertainment"
            ],
            "relevance_score": null
        },
        {
            "uuid": "72e908e6-3aec-4d68-98fb-9efa20b77d84",
            "title": "新动力+世纪同款外观 别克GL8能否“混”水摸鱼",
            "description": "新动力+世纪同款外观 别克GL8能否“混”水摸鱼",
            "keywords": "MPV, 别克, 别克GL8, 新动力+世纪同款外观 别克GL8能否“混”水摸鱼, 快科技",
            "snippet": "新动力+世纪同款外观 别克GL8能否“混”水摸鱼\n\n众所周知，中高端商务MPV市场的首把交椅一直被别克GL8牢牢占据。即便是...",
            "url": "https://news.mydrivers.com/1/975/975094.htm",
            "image_url": "https://img1.mydrivers.com/img/20240418/1e4e9826123e45a2b7221cf41f0ac257.png",
            "language": "zh",
            "published_at": "2024-04-18T13:44:59.000000Z",
            "source": "news.mydrivers.com",
            "categories": [
                "tech",
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "5a253f0e-7985-43a3-896a-a508d0ea2c70",
            "title": "“AI 세계로 가는 거의 완벽한 출발점” 마이크로소프트 애저 AI 스튜디오 - Tech Review",
            "description": "현재 생성형 AI 기술 생태계에 가장 큰 영향력을 가진 기업은 단연 마이크로소프트다. 그리고 마이크로소프트의 AI 역량?...",
            "keywords": "",
            "snippet": "",
            "url": "https://www.itworld.co.kr/techlibrary/333939",
            "image_url": "https://files.itworld.co.kr/ITW_202404_02/ITW_TechReview_AzureAI_240418.640x480.jpg",
            "language": "ko",
            "published_at": "2024-04-18T13:44:54.000000Z",
            "source": "itworld.co.kr",
            "categories": [
                "tech"
            ],
            "relevance_score": null
        },
        {
            "uuid": "c37acb92-8517-47d1-b817-798ca1fc5f9b",
            "title": "Got2B Forges Distribution Partnership with Queen of New York",
            "description": "Reflects the hair care brand’s commitment to providing platforms for creativity and self-expression for members of the LGBTQIA+ and drag communities.",
            "keywords": "care products, cosmetics, fragrances, household products, natural ingredients, skin care, beauty, hair care, sun care, chemicals, anti-aging, ingredients, cleaning, personal care, Formula, formulation, hair, skin, toiletry, surfactant, polymer, wipes, cream, antiaging, preservative, emulsion, stability, testing, regulation, sunscreen, shampoo, color, pigment, acn",
            "snippet": "Got2B has forged a distribution partnership with “Queen of New York,” a new documentary about drag queen and LGBTQIA+ activist Marti Cummings.\n\nThe doc chro...",
            "url": "https://www.happi.com/contents/view_breaking-news/2024-04-18/got2b-forges-distribution-partnership-with-queen-o-622107/",
            "image_url": "https://images.rodpub.com/images/304/790_main.jpg",
            "language": "en",
            "published_at": "2024-04-18T13:44:29.000000Z",
            "source": "happi.com",
            "categories": [
                "entertainment"
            ],
            "relevance_score": null
        },
        {
            "uuid": "ea3176e2-03fc-49e9-8ea7-7e0ef58f472d",
            "title": "苏峻“上车”iCAR，互联网思维与奇瑞大厂互相赋能",
            "description": "。",
            "keywords": "互联网思维, 与奇瑞大厂, 最新消息, 科技资讯挖掘, 高效读科技, 科技猎",
            "snippet": "我是创始人李岩：很抱歉！给自己产品做个广告，点击进来看看。\n\n如今的新能源 汽车 领域,似乎上演与智能 手机 类似的...",
            "url": "http://www.kejilie.com/ikanchai/article/vuQVjy.html",
            "image_url": "http://www.kejilie.com/img/logom.png",
            "language": "zh",
            "published_at": "2024-04-18T13:44:28.000000Z",
            "source": "kejilie.com",
            "categories": [],
            "relevance_score": null
        },
        {
            "uuid": "2c98a4fc-57dc-4a1f-b39e-1fbb43bbfcb1",
            "title": "惠达卫浴科技实力再显，首篇学术论文亮相国际陶瓷顶刊",
            "description": "。",
            "keywords": "亮相国际, 科技实力, 最新消息, 科技资讯挖掘, 高效读科技, 科技猎",
            "snippet": "在全球卫浴行业的激烈竞争中，惠达卫浴与河北工业大学合作的卫生陶瓷烧结技术项目研究取得了显著成果。凭借前瞻性?...",
            "url": "http://www.kejilie.com/ikanchai/article/FFjUNj.html",
            "image_url": "http://www.kejilie.com/img/logom.png",
            "language": "zh",
            "published_at": "2024-04-18T13:44:25.000000Z",
            "source": "kejilie.com",
            "categories": [],
            "relevance_score": null
        }
    ]
}

Similar News Available on: All plans

Endpoint

            
                GET https://api.thenewsapi.com/v1/news/similar/uuid HTTP/1.1

Use this endpoint to find similar stories to a specific article based on its UUID.

If you have issues with your requests, please ensure your GET parameters are URL-encoded.

All text data returned is UTF-8.

All dates are in UTC (GMT).

HTTP GET Parameters

name required description
api_token true Your API token which can be found on your account dashboard.
categories false Comma separated list of categories to include.
Supported categories: general | science | sports | business | health | entertainment | tech | politics | food | travel
Example: business,tech
exclude_categories false Comma separated list of categories to exclude.
domains false Comma separated list of domains to include. List of domains can be obtained through our Sources endpoint, found further down this page.
exclude_domains false Comma separated list of domains to exclude
source_ids false Comma separated list of source_ids to include. List of source_ids can be obtained through our Sources endpoint, found further down this page.
exclude_source_ids false Comma separated list of source_ids to exclude.
language false Comma separated list of languages to include. Default is all.
Click here for a list of supported languages.
Examples: en,es (English + Spanish)
published_before false Find all articles published before the specified date. Supported formats include: Y-m-d\TH:i:s | Y-m-d\TH:i | Y-m-d\TH | Y-m-d | Y-m | Y.
Examples: 2024-04-18T13:45:13 | 2024-04-18T13:45 | 2024-04-18T13 | 2024-04-18 | 2024-04 | 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-04-18T13:45:13 | 2024-04-18T13:45 | 2024-04-18T13 | 2024-04-18 | 2024-04 | 2024
published_on false Find all articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2024-04-18
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-04-11

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.