Getting Started

Introduction

Our API was developed to provide global news from thousands of sources with exceptional response times. On average we add over 1 million articles weekly, so you will never be short of content. Even better, it is completely free!

To get started simply sign up and use your API token in any of the available API endpoints documented below for instant access.

If you have any questions or concerns, feel free to contact us.

Authentication

As mentioned above, when you sign up for free you will find your API token on your dashboard. Simply add this to any of our API endpoints as a GET parameter to gain access. Examples of how this is done can be found below.

API Endpoints

Headlines Available on: Standard plan and above

Endpoint

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

Use this endpoint to find get the latest headlines by category along with similar articles, allowing you to create the perfect news aggregation page similar to Google News .

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

All text data returned is UTF-8.

All dates are in UTC (GMT).

HTTP GET Parameters

name required description
api_token true Your API token which can be found on your account dashboard.
locale false Comma separated list of country codes to include in the result set. Default is 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: 2021-12-02
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": "afe4534c-91d4-4b38-b030-df40898f840a",
                "title": "Four takeaways from the Supreme Court arguments on abortion",
                "description": "A conservative Supreme Court built up significantly by former president Donald Trump is considering whether a 15-week ban on most abortions in Mississippi should be upheld.",
                "keywords": "",
                "snippet": "The justices are expected to rule sometime this summer, but the oral arguments usually provide some clues about how the justices view the case.\n\nA conservative ...",
                "url": "https://www.bostonglobe.com/2021/12/01/nation/four-takeaways-supreme-court-arguments-abortion/?camp=bg:brief:rss:feedly&rss_id=feedly_rss_brief",
                "image_url": "https://bostonglobe-prod.cdn.arcpublishing.com/resizer/4sqM_dCK90_P_EHMxWiCQYWlZUU=/506x0/cloudfront-us-east-1.images.arcpublishing.com/bostonglobe/KYIWS2646YCQDPM5BUEWBUVIVM.jpg",
                "language": "en",
                "published_at": "2021-12-01T21:00:31.000000Z",
                "source": "bostonglobe.com",
                "categories": [
                    "general"
                ],
                "locale": "us",
                "similar": [
                    {
                        "uuid": "5734b974-9df9-40c6-9d6e-664333bf90ef",
                        "title": "Video Protests gather as Supreme Court considers historic abortion case",
                        "description": "Thousands gathered outside the Supreme Court on Wednesday as the court heard arguments in the most serious challenge to Roe vs. Wade in 30 years.",
                        "keywords": "",
                        "snippet": "Protests gather as Supreme Court considers historic abortion case Thousands gathered outside the Supreme Court on Wednesday as the court heard arguments in the ...",
                        "url": "https://abcnews.go.com/Politics/video/protests-gather-supreme-court-considers-historic-abortion-case-81500508",
                        "image_url": "https://s.abcnews.com/images/Politics/211201_vod_scotus_hpMain_16x9_608.jpg",
                        "language": "en",
                        "published_at": "2021-12-01T21:27:00.000000Z",
                        "source": "abcnews.go.com",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "70caa618-eb7b-4d63-9e36-b1b360844ced",
                        "title": "Supreme Court conservatives appear willing to gut abortion rights",
                        "description": "Conservative U.S. Supreme Court justices on Wednesday signaled a willingness to dramatically curtail abortion rights in America and perhaps overturn the landmark 1973 Roe v. Wade ruling that legalized the procedure nationwide as they indicated they would uphold a restrictive Republican-backed Mississippi law.",
                        "keywords": "NRLIN:OSCOTUS, MTVID, MTGFX, ADVO, CIV, CLJ, FERREP, GEN, GENHLT, HEA, HECA, HRGT, JUDIC, LAW, MEDST, NGO, POL, POTUS, PXP, SCOTUS, SOCI, WASH, WOM, WOMHEA, AMERS, US, USAMS, NAMER, LEGAL, REUTERS-LEGAL, TOPCMB, TOPNWS, NRLPA:OCIV, NRLPA:OAPP, NRLPA:OHLT, NRLPA:OPUB",
                        "snippet": "Summary Liberal justices warn against overturning precedents\n\nMississippi law bans abortion at 15 weeks of pregnancy\n\nBiden lawyer urges against \"contraction\" o...",
                        "url": "https://www.reuters.com/world/us/us-supreme-court-consider-rolling-back-abortion-rights-2021-12-01/",
                        "image_url": "https://www.reuters.com/resizer/PPtUQBO_55IQKCNEdtvVuJLEYw0=/1200x628/smart/filters:quality(80)/cloudfront-us-east-2.images.arcpublishing.com/reuters/2ZF2FYJOBRIXNBXDVP5XPIJE2U.jpg",
                        "language": "en",
                        "published_at": "2021-12-01T21:04:00.000000Z",
                        "source": "news.google.com",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "812bfb24-02b5-493b-b1e9-48fffb49af0c",
                        "title": "Kavanaugh Implied The Supreme Court Can Be “Neutral” On Abortion. That’s Ridiculous",
                        "description": "26 states have indicated they are ready to implement abortion bans.",
                        "keywords": "",
                        "snippet": "Fight disinformation. Get a daily recap of the facts that matter. Sign up for the free Mother Jones newsletter\n\nJustice Brett Kavanaugh used some startlingly di...",
                        "url": "https://www.motherjones.com/politics/2021/12/kavanaugh-implied-the-supreme-court-can-be-neutral-on-abortion-thats-ridiculous/",
                        "image_url": "https://www.motherjones.com/wp-content/uploads/2021/12/20211201-kavanaugh.jpeg?w=1200&h=630&crop=1",
                        "language": "en",
                        "published_at": "2021-12-01T22:17:20.000000Z",
                        "source": "motherjones.com",
                        "categories": [
                            "general",
                            "politics",
                            "entertainment"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "82cb81ab-7b47-4afb-8ef9-aee0dfebf570",
                        "title": "Takeaways from the historic Supreme Court arguments on abortion rights",
                        "description": "The Supreme Court heard oral arguments Wednesday on one of its most important cases in decades and considered the future of abortion rights in America.",
                        "keywords": "politics, Takeaways from the historic Supreme Court arguments on abortion rights - CNNPolitics",
                        "snippet": "(CNN) The Supreme Court heard oral arguments Wednesday on one of its most important cases in decades and considered the future of abortion rights in America.\n\nF...",
                        "url": "https://www.cnn.com/2021/12/01/politics/takeaways-supreme-court-abortion/index.html",
                        "image_url": "https://cdn.cnn.com/cnnnext/dam/assets/211201160248-09-supreme-court-abortion-1201-super-tease.jpg",
                        "language": "en",
                        "published_at": "2021-12-01T22:50:25.000000Z",
                        "source": "cnn.com",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "52dd26f8-35c7-4aff-97b3-a512c9d8b5e0",
                        "title": "Supreme Court Makes Clear the Unthinkable Is Here on Abortion",
                        "description": "For millions of Americans, the idea of losing abortion rights had been an abstract concept. Now, it’s a direct assault on our fundamental liberties.",
                        "keywords": "Supreme Court of the United States, Republican Party, Roe v. Wade, Abortion, Planned Parenthood v. Casey, Mississippi, Members Only, Opinion",
                        "snippet": "After a half century of abortion rights protected by the landmark 1973 case Roe v. Wade, the Supreme Court on Wednesday offered the clearest signs yet that the ...",
                        "url": "https://www.thedailybeast.com/supreme-court-makes-clear-the-unthinkable-is-here-on-abortion",
                        "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/v1638402294/211201-abortion-rights-tease-01_drvkir",
                        "language": "en",
                        "published_at": "2021-12-01T23:45:15.000000Z",
                        "source": "thedailybeast.com",
                        "categories": [
                            "general",
                            "politics"
                        ],
                        "locale": "us"
                    }
                ]
            },
            {
                "uuid": "ff4954ed-057e-41c2-bce7-6d472ab331f1",
                "title": "Chris Cuomo Breaks Silence on \"Embarrassing\" Suspension from CNN",
                "description": "Just one day after CNN announced that Chris Cuomo would be suspended from the network indefinitely, the prime time anchor is speaking out following the decision.",
                "keywords": "",
                "snippet": "Watch : Chris Cuomo Gives Update on 14-Year-Old Son's Coronavirus Recovery\n\nDespite calling his recent suspension \"embarrassing,\" CNN anchor Chris Cuomo says he...",
                "url": "https://www.eonline.com/news/1311723/chris-cuomo-breaks-silence-on-embarrassing-suspension-from-cnn?cmpid=rss-000000-rssfeed-365-topstories&utm_source=eonline&utm_medium=rssfeeds&utm_campaign=rss_topstories",
                "image_url": "https://akns-images.eonline.com/eol_images/Entire_Site/2021824/rs_1200x1200-210924074614-1200-chris_cuomo-gj.jpg?fit=around%7C1080:1080&output-quality=90&crop=1080:1080;center,top",
                "language": "en",
                "published_at": "2021-12-01T19:24:00.000000Z",
                "source": "eonline.com",
                "categories": [
                    "entertainment",
                    "general"
                ],
                "locale": "us",
                "similar": [
                    {
                        "uuid": "7e785a8e-4261-4712-8c90-0fa7778d979d",
                        "title": "CNN's Chris Cuomo wasn't all about 'facts first.' He was about 'lies first'",
                        "description": "On Nov. 29, thousands of pages of evidence emerged from the investigation of New York Attorney General Letitia James into ex-Gov. Andrew Cuomo. Once again, it underlined that Chris Cuomo didn't have a line of media ethics that he wouldn't cross.",
                        "keywords": "",
                        "snippet": "NEW You can now listen to Fox News articles!\n\nCNN's dramatic and insurmountable conflict of interest of using Chris Cuomo as a \"news anchor\" just keeps getting ...",
                        "url": "https://www.foxnews.com/opinion/cnn-chris-cuomo-facts-first-lies",
                        "image_url": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/854081161001/c19e2a38-53f9-47ae-90fa-8a11ee3e5044/5cc5603b-4d5a-4a9b-bad3-6defe96f5878/1280x720/match/image.jpg",
                        "language": "en",
                        "published_at": "2021-12-01T20:03:25.000000Z",
                        "source": "foxnews.com",
                        "categories": [
                            "general",
                            "politics"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "9b0f379b-7f98-4120-ba76-697017649e90",
                        "title": "Chris Cuomo’s suspension ‘challenging, divisive and troubling’ inside CNN, insiders say",
                        "description": "CNN's suspension of Chris Cuomo this week prompted a wide array of reactions from inside the struggling network as leadership must decide if the",
                        "keywords": "",
                        "snippet": "CNN's suspension of Chris Cuomo this week prompted a wide array of reactions from inside the struggling network as leadership must decide if the \"Cuomo Prime Ti...",
                        "url": "https://www.foxnews.com/media/chris-cuomo-suspension-challenging-divisive-and-troubling-cnn-insiders",
                        "image_url": "https://static.foxnews.com/foxnews.com/content/uploads/2021/11/Chris-Cuomo-sad.jpg",
                        "language": "en",
                        "published_at": "2021-12-01T21:08:09.000000Z",
                        "source": "foxnews.com",
                        "categories": [
                            "general",
                            "politics"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "9694a695-90a3-468a-9fab-9424bdce6510",
                        "title": "CNN spokesman on Stelter floating Cuomo returning within weeks: 'It’s all speculative'",
                        "description": "A CNN spokesman says Brian Stelter's insinuation Chris Cuomo could return to the airwaves in just weeks was “speculative” until the network's review of the anchor's actions was completed.",
                        "keywords": "",
                        "snippet": "A CNN spokesman said media correspondent Brian Stelter's statement Wednesday that Chris Cuomo could return to the airwaves in a matter of weeks was \"speculative...",
                        "url": "https://www.foxnews.com/media/cnn-spokesman-stelter-cuomo-speculative",
                        "image_url": "https://static.foxnews.com/foxnews.com/content/uploads/2021/03/ChrisCuomo-Cuomo-Stetler.jpg",
                        "language": "en",
                        "published_at": "2021-12-01T20:36:08.000000Z",
                        "source": "foxnews.com",
                        "categories": [
                            "general",
                            "politics"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "0f3e6292-100e-4c6e-8f18-d67b580a4496",
                        "title": "FLASHBACK: CNN's Brian Stelter claimed Chris Cuomo upheld journalistic 'boundaries' during Colbert interview",
                        "description": "The 'Reliable Sources' host suggested Cuomo could return as early as January",
                        "keywords": "",
                        "snippet": "CNN's leftwing media correspondent Brian Stelter once offered a staunch defense of his colleague Chris Cuomo, who has since been suspended over his involvement ...",
                        "url": "https://www.foxnews.com/media/cnn-brian-stelter-chris-cuomo-late-show-stephen-colbert",
                        "image_url": "https://static.foxnews.com/foxnews.com/content/uploads/2021/11/Brian-Stelter-Stephen-Colbert-interview-1.jpg",
                        "language": "en",
                        "published_at": "2021-12-01T22:48:24.000000Z",
                        "source": "foxnews.com",
                        "categories": [
                            "general",
                            "politics"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "401ef278-0ec7-41e6-8089-12992ab6df87",
                        "title": "Chris Cuomo says he's hurt and embarrassed about his suspension from CNN",
                        "description": "\"It hurts to even say it,\" the popular cable news anchor told listeners of his SiriusXM show on Wednesday. Cuomo has been suspended by CNN indefinitely, pending an evaluation by the network.",
                        "keywords": "",
                        "snippet": "Chris Cuomo says he's hurt and embarrassed about his suspension from CNN\n\nEnlarge this image toggle caption Evan Agostini/Evan Agostini/Invision/AP Evan Agostin...",
                        "url": "https://www.npr.org/2021/12/01/1060697321/chris-cuomo-says-hes-hurt-and-embarrassed-about-his-suspension-from-cnn",
                        "image_url": "https://media.npr.org/assets/img/2021/12/01/ap_18262559465993_wide-68c56dcf8e6c520f815bf1197dded753e9be07d9.jpg?s=1400",
                        "language": "en",
                        "published_at": "2021-12-02T01:58:35.000000Z",
                        "source": "npr.org",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    }
                ]
            }
        ],
        "business": ...,
        "sports": ...,
        "tech": ...,
        "science": ...,
        "health": ...
    }
}
            
        

Top Stories Available on: All plans

Endpoint

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

Use this endpoint to find live and historical top stories around the world or filter to get only top stories for specific countries. Filtering by language, category, source and publish date is also possible, as well as advanced searching on title and the main text of the article.

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

All text data returned is UTF-8.

All dates are in UTC (GMT).

HTTP GET Parameters

name required description
api_token true Your API token which can be found on your account dashboard.
search false Use the search as a basic search tool by entering regular search terms or it has more advanced usage to build search queries:
+ signifies AND operation
| signifies OR operation
- negates a single token
" wraps a number of tokens to signify a phrase for searching
* at the end of a term signifies a prefix query
( and ) signify precedence

To use one of these characters literally, escape it with a preceding backslash (\).

Example 1: forex + (usd | gbp) -cad (searches for forex articles which include usd or gbp but excludes cad)
Example 2: "Apple Inc" (searches for articles with exact matches for "Apple Inc")

For more advanced query examples, see our API Examples section.
locale false Comma separated list of country codes to include in the result set. Default is 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: 2021-12-02T07:18:11 | 2021-12-02T07:18 | 2021-12-02T07 | 2021-12-02 | 2021-12 | 2021
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: 2021-12-02T07:18:11 | 2021-12-02T07:18 | 2021-12-02T07 | 2021-12-02 | 2021-12 | 2021
published_on false Find all articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2021-12-02
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": 489619,
        "returned": 10,
        "limit": 10,
        "page": 1
    },
    "data": [
        {
            "uuid": "1d696483-801d-4730-96d5-89b4e921414e",
            "title": "Two Premier League matches hit by medical emergencies on same night",
            "description": "The Premier League match between Watford and Chelsea and the meeting between Southampton and Leicester both had to be halted due to medical emergencies in the c...",
            "keywords": "",
            "snippet": "The Premier League match between Watford and Chelsea and the meeting between Southampton and Leicester both had to be halted due to medical emergencies in the c...",
            "url": "https://www.rt.com/sport/541934-watford-chelsea-medical-emergency/",
            "image_url": "https://cdni.rt.com/files/2021.12/article/61a8693d85f5407eaa41298a.JPG",
            "language": "en",
            "published_at": "2021-12-02T06:45:27.000000Z",
            "source": "rt.com",
            "categories": [
                "general",
                "politics"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "70ece91a-093b-4fe0-a78f-a94521b3e943",
            "title": "NATO has been too successful at doing the wrong thing",
            "description": "NATO and Russia are facing off once again. At the center of the new cycle of mutual warnings and brinkmanship is Ukraine, which, despite being refused immediate...",
            "keywords": "",
            "snippet": "By Tarik Cyril Amar , a historian from Germany at Koç University in Istanbul working on Russia, Ukraine, and Eastern Europe, the history of World War II, the c...",
            "url": "https://www.rt.com/russia/541887-nato-warnings-brinkmanship-ukraine/",
            "image_url": "https://cdni.rt.com/files/2021.12/article/61a7c36885f5406daf214234.jpeg",
            "language": "en",
            "published_at": "2021-12-02T06:45:25.000000Z",
            "source": "rt.com",
            "categories": [
                "general",
                "politics"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "0705d1ca-e7f9-413c-a3dc-72148c8a42d3",
            "title": "Refugees on Belarus border can already claim asylum – EU",
            "description": "Migrants living in makeshift camps on the border between Belarus and the EU are permitted to claim asylum and seek safety within countries in the region, but no...",
            "keywords": "",
            "snippet": "Migrants living in makeshift camps on the border between Belarus and the EU are permitted to claim asylum and seek safety within countries in the region, but no...",
            "url": "https://www.rt.com/russia/541895-migrants-belarus-claim-asylum/",
            "image_url": "https://cdni.rt.com/files/2021.12/article/61a79c8320302769a5058e82.JPG",
            "language": "en",
            "published_at": "2021-12-02T06:43:16.000000Z",
            "source": "rt.com",
            "categories": [
                "general",
                "politics"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "c0f28ccd-97eb-491a-a4d2-5af0a0fa7076",
            "title": "ECB faces calls to be clearer on inflation after Fed's Powell drops 'transitory'",
            "description": "Fed's Powell tweaked his tone about inflation. Now, economists in Europe say the European Central Bank needs to do the same.",
            "keywords": "Inflation, Euro, EU, Christine Lagarde, European Central Bank, Federal Reserve System, Central banking, Jerome Powell, Prices, Jerome Powell, Politics, Europe News, business news",
            "snippet": "Federal Reserve Chairman Jerome Powell surprised market players earlier this week when tweaking his tone about inflation. Now, economists in Europe say the Euro...",
            "url": "https://www.cnbc.com/2021/12/02/powell-time-to-retire-transitory-what-it-means-for-the-ecb.html",
            "image_url": "https://image.cnbcfm.com/api/v1/image/106802159-1606304719321-gettyimages-1212003586-_loh5341_lohnes_2020031241032410.jpeg?v=1623246706",
            "language": "en",
            "published_at": "2021-12-02T06:35:38.000000Z",
            "source": "cnbc.com",
            "categories": [
                "general",
                "business"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "6050085e-d620-4d9c-b4fb-547d050b4562",
            "title": "Boris Johnson faces grilling over alleged 'boozy' Christmas parties last year",
            "description": "British Prime Minister Boris Johnson faced a grilling during the Prime Minister's Questions (PMQs) in the UK Parliament after a British newspaper reported claim...",
            "keywords": "world, Boris Johnson faces grilling over alleged 'boozy' Christmas parties last year  - CNN Video",
            "snippet": "British Prime Minister Boris Johnson faced a grilling during the Prime Minister's Questions (PMQs) in the UK Parliament after a British newspaper reported claim...",
            "url": "https://www.cnn.com/videos/world/2021/12/02/uk-boris-johnson-christmas-parties-pmq-tgb-intl-hnk-vpx.cnn",
            "image_url": "https://cdn.cnn.com/cnnnext/dam/assets/211202134746-screengrab-boris-johnson-super-tease.jpg",
            "language": "en",
            "published_at": "2021-12-02T06:20:43.000000Z",
            "source": "cnn.com",
            "categories": [
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "fc0d313e-a477-4f18-a0d0-25086fcfd057",
            "title": "Stephen Colbert and Jimmy Kimmel Go Off on Trump for Debating Biden With COVID",
            "description": "The late-night hosts called out Trump for endangering Biden—and Fox News for letting him use the “honor system” to get away with not showing a negative te...",
            "keywords": "Fox News, Donald J. Trump, Stephen Colbert, Joe Biden, Jimmy Kimmel, presidential debate, Jimmy Kimmel Live!, coronavirus, COVID-19, Amy Coney Barrett",
            "snippet": "As Stephen Colbert has explained to his Late Show audience before, he has spent almost all of 2021 trying his best not to talk about former President Donald Tru...",
            "url": "https://www.thedailybeast.com/stephen-colbert-and-jimmy-kimmel-go-off-on-trump-for-debating-biden-with-covid",
            "image_url": "https://img.thedailybeast.com/image/upload/c_crop,d_placeholder_euli9k,h_1436,w_2553,x_0,y_0/dpr_2.0/c_limit,w_740/fl_lossy,q_auto/v1638425216/LN_2_icpsx5",
            "language": "en",
            "published_at": "2021-12-02T06:07:37.000000Z",
            "source": "thedailybeast.com",
            "categories": [
                "general",
                "politics"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "6707c7d7-4711-4ed9-8a94-4112c503a7fc",
            "title": "Ingraham: Supreme Court could 'finally put Roe to rest', rips 'twisted logic' of Sotomayor",
            "description": "In her \"Ingraham Angle\" commentary, host Laura Ingraham said there is a decent potential for the conservative-majority U.S. Supreme Court to finally \"put Roe to...",
            "keywords": "",
            "snippet": "In her \"Ingraham Angle\" commentary on Wednesday, host Laura Ingraham said there is a decent potential for the conservative-majority U.S. Supreme Court to finall...",
            "url": "https://www.foxnews.com/media/ingraham-supreme-court-roe-twisted-logic-sotomayor",
            "image_url": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/694940094001/fef30aff-cfe4-46b8-a2df-1b3c6eb0f612/2b11e47c-d005-4a5c-a3a3-2ddf4965278b/1280x720/match/image.jpg",
            "language": "en",
            "published_at": "2021-12-02T06:01:01.000000Z",
            "source": "foxnews.com",
            "categories": [
                "general",
                "politics"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "12add701-0ed7-47d7-bb7a-a0ad0a496602",
            "title": "Teams commit to more than $1.4 billion in contracts in hours before MLB lockout",
            "description": "It’s the first time teams have combined to spend over $1 billion in a single day, and it came on the final day before the sport's first work stoppage since 19...",
            "keywords": "Mariners, Ray",
            "snippet": "Six nine-figure contracts were handed out, including two by the Texas Rangers — shortstop Corey Seager got $325 million over 10 years and infielder Marcus Sem...",
            "url": "https://www.bostonglobe.com/2021/12/02/sports/teams-commit-more-than-14-billion-contracts-hours-before-mlb-lockout/?camp=bg:brief:rss:feedly&rss_id=feedly_rss_brief",
            "image_url": "https://bostonglobe-prod.cdn.arcpublishing.com/resizer/gK4uWeEwW-7pcjlFzT8SW9a0FWY=/506x0/cloudfront-us-east-1.images.arcpublishing.com/bostonglobe/5V34ELZ4AEZBPHI6UPNBGIAOH4.jpg",
            "language": "en",
            "published_at": "2021-12-02T06:00:55.000000Z",
            "source": "bostonglobe.com",
            "categories": [
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "957a5daf-7c77-4c33-8c9c-a2d19a5eac06",
            "title": "FedEx driver dumped packages at least 6 times into Alabama ravine, sheriff says",
            "description": "23.9m members in the news community. The place for news articles about current events in the United States and the rest of the world. Discuss it all …",
            "keywords": "",
            "snippet": "The place for news articles about current events in the United States and the rest of the world. Discuss it all here.",
            "url": "https://www.reddit.com/r/news/comments/r6y9ii/fedex_driver_dumped_packages_at_least_6_times/",
            "image_url": "https://www.redditstatic.com/desktop2x/img/favicon/apple-icon-57x57.png",
            "language": "en",
            "published_at": "2021-12-02T05:55:03.000000Z",
            "source": "reddit.com",
            "categories": [
                "general",
                "politics"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "bda0c015-114d-45f7-946a-16241a5e9483",
            "title": "Major League Baseball Players Locked Out By Owners For First Time In 26 Years",
            "description": "Major League Baseball Players Locked Out By Owners For First Time In 26 Years",
            "keywords": "",
            "snippet": "For the first time in 26 years, Major League Baseball players have been locked out by owners after the two sides failed to reach a new collective bargaining agr...",
            "url": "https://deadline.com/2021/12/major-league-baseball-lockout-1234883359/",
            "image_url": "https://deadline.com/wp-content/uploads/2021/12/mlb-logo.png?w=305",
            "language": "en",
            "published_at": "2021-12-02T05:50:08.000000Z",
            "source": "deadline.com",
            "categories": [
                "entertainment"
            ],
            "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.
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: 2021-12-02T07:18:11 | 2021-12-02T07:18 | 2021-12-02T07 | 2021-12-02 | 2021-12 | 2021
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: 2021-12-02T07:18:11 | 2021-12-02T07:18 | 2021-12-02T07 | 2021-12-02 | 2021-12 | 2021
published_on false Find all articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2021-12-02
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": 67078985,
        "returned": 10,
        "limit": 10,
        "page": 1
    },
    "data": [
        {
            "uuid": "3eb6251d-a3e7-4ae1-bf52-b399b019bafe",
            "title": "安九铁路全线试运行:设计时速350公里 南昌至合肥时长减半",
            "description": "安九铁路全线试运行:设计时速350公里 南昌至合肥时长减半",
            "keywords": "高铁, 铁路, 安九铁路全线试运行:设计时速350公里 南昌至合肥时长减半, 快科技",
            "snippet": "安九铁路全线试运行:设计时速350公里 南昌至合肥时长减半\n\n12月1日,安庆至九江高铁进入全线运行试验阶段,预计2021年...",
            "url": "https://news.mydrivers.com/1/799/799967.htm",
            "image_url": "https://img1.mydrivers.com/img/20211202/9816b990a6364032af7dafaafffd6945.jpg",
            "language": "zh",
            "published_at": "2021-12-02T07:18:47.000000Z",
            "source": "news.mydrivers.com",
            "categories": [
                "tech",
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "d898d362-d703-4bb4-94d1-257da6b8a405",
            "title": "[뉴욕유가] OPEC 회의 앞두고 미국 오미크론 첫 확진에 하락",
            "description": "(뉴욕=연합뉴스) 정선영 연합인포맥스 특파원 = 유가는 석유수출국기구(OPEC) 플러스(+) 회의 결과를 앞두고 하락했다. 주?...",
            "keywords": "",
            "snippet": "본 기사는 인포맥스 금융정보 단말기에서 2시간 더 빠른 05시 18분에 서비스된 기사입니다.\n\n저작권자 © 연합인포맥스 무?...",
            "url": "https://news.einfomax.co.kr/news/articleView.html?idxno=4186672",
            "image_url": "http://news.einfomax.co.kr/image/logo/snslogo_20201007035704.jpg",
            "language": "ko",
            "published_at": "2021-12-02T07:18:20.000000Z",
            "source": "news.einfomax.co.kr",
            "categories": [
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "34db05e7-776e-4665-9c57-0f58a0046a73",
            "title": "재명이네 슈퍼 좋네요.. : 클리앙",
            "description": "집에서 정치얘길 많이하는데 관심 1도 없어 가끔 정치얘긴 하지말아야겄다 하는데.. 어제 재명이네 슈퍼 틀고 보니 셋째?...",
            "keywords": "",
            "snippet": "집에서 정치얘길 많이하는데 관심 1도 없어 가끔 정치얘긴 하지말아야겄다 하는데..\n\n어제 재명이네 슈퍼 틀고 보니 셋째...",
            "url": "https://www.clien.net/service/board/park/16737878",
            "image_url": "https://cdn.clien.net/web/api/file/F01/12294707/29666f40f964fa.jpg",
            "language": "ko",
            "published_at": "2021-12-02T07:17:27.000000Z",
            "source": "clien.net",
            "categories": [
                "tech"
            ],
            "relevance_score": null
        },
        {
            "uuid": "24be5258-d7ce-4fde-91fa-740e85f9947b",
            "title": "N. Korean leader presides over politburo meeting",
            "description": "SEOUL, Dec. 2 (Yonhap) -- North Korean leader Kim Jong-un has presided over a politburo se...",
            "keywords": "",
            "snippet": "During the session held the previous day, the North decided to hold a plenary meeting of the Central Committee of the party in late December, according to the K...",
            "url": "https://en.yna.co.kr/view/AEN20211202000300325",
            "image_url": "https://r.yna.co.kr/global/home/v01/img/yonhapnews_logo_600x325_en02.jpg",
            "language": "en",
            "published_at": "2021-12-02T07:17:21.000000Z",
            "source": "yna.co.kr",
            "categories": [
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "24ea16db-c438-46ac-9b3e-01c07c11f3af",
            "title": "Stres Çarkı Alternatifi XX Stres Oyuncağı",
            "description": "Stres atmayı oyuna çevirmek isteyenler için stres çarkı alternatifi 7 stres oyuncağını derledik.",
            "keywords": "",
            "snippet": "",
            "url": "https://www.webtekno.com/stres-carki-alternatifi-stres-oyuncaklari-h115502.html",
            "image_url": "https://cdn.webtekno.com/media/cache/content_detail_v2/article/115502/stres-carki-alternatifi-stres-oyuncaklari-1637771020.jpg",
            "language": "tr",
            "published_at": "2021-12-02T07:17:00.000000Z",
            "source": "webtekno.com",
            "categories": [
                "tech"
            ],
            "relevance_score": null
        },
        {
            "uuid": "fed7fa04-950d-43af-a412-10ccbc80147b",
            "title": "江苏:坚决拥护党中央对张敬华涉嫌严重违纪违法进行纪律审查和监察调查的决定-中新网",
            "description": "(记者 黄伟) 12月1日晚,省委书记吴政隆主持召开省委常委会会议,通报张敬华涉嫌严重违纪违法,目前正接受中央纪委国...",
            "keywords": "党中央, 党要管党, 违纪违法, 中央纪委, 拥护",
            "snippet": "坚决拥护党中央对张敬华涉嫌严重违纪违法进行纪律审查和监察调查的决定\n\n省委常委会召开会议 吴政隆主持\n\n本报讯 (记...",
            "url": "https://www.chinanews.com.cn/gn/2021/12-02/9620356.shtml",
            "image_url": "http://i2.chinanews.com/simg/tvmimg/2021/12-01/1617417_sm.jpg",
            "language": "zh",
            "published_at": "2021-12-02T07:16:32.000000Z",
            "source": "chinanews.com",
            "categories": [
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "93c71bd6-eade-4112-95a5-3dc38d4a090a",
            "title": "哈尔滨市发现1例本土新冠肺炎确诊病例-中新网",
            "description": "(记者 刘锡菊)12月2日,哈尔滨市应对新型冠状病毒感染肺炎疫情工作指挥部发布第40号公告:哈尔滨市发现1例本土新冠肺?...",
            "keywords": "足疗店, 阳性, 感染者, 旅游, 就诊",
            "snippet": "中新网哈尔滨12月2日电 (记者 刘锡菊)12月2日,哈尔滨市应对新型冠状病毒感染肺炎疫情工作指挥部发布第40号公告:哈尔?...",
            "url": "https://www.chinanews.com.cn/sh/2021/12-02/9620354.shtml",
            "image_url": "http://i2.chinanews.com/simg/tvmimg/2021/12-01/1617417_sm.jpg",
            "language": "zh",
            "published_at": "2021-12-02T07:15:32.000000Z",
            "source": "chinanews.com",
            "categories": [
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "5e6e6da1-1a43-42ac-83ca-3d34d818aed8",
            "title": "Focus Fonds : Barings Emerging Markets Local Debt",
            "description": "Une équipe chevronnée, un process stable et bien exécuté sont les principaux atouts de ce fonds.",
            "keywords": "ÉQUIPE DE GESTION, FCP, FONDS, FRAIS DE GESTION, MORNINGSTAR, NOTATION, PERFORMANCE, PROCESSUS D'INVESTISSEMENT, SICAV, SOCIÉTÉ DE GESTION",
            "snippet": "Le fonds Barings Emerging Markets Local Debt bénéficie d’une équipe de gestion expérimentée, a appliqué de manière cohérente un processus d'investisse...",
            "url": "https://www.morningstar.fr/fr/news/217187/focus-fonds--barings-emerging-markets-local-debt.aspx",
            "image_url": "https://euim.mstar.com/images/favicon.ico",
            "language": "en",
            "published_at": "2021-12-02T07:15:00.000000Z",
            "source": "morningstar.fr",
            "categories": [
                "business"
            ],
            "relevance_score": null
        },
        {
            "uuid": "bf41b5d1-5298-444c-b749-a89f89bb8d38",
            "title": "В Самарской области беременные вакцинируются от ковида",
            "description": "Новости Тольятти - В Самарской области беременные вакцинируются от ковида",
            "keywords": "Новости Тольятти - В Самарской области беременные вакцинируются от ковида",
            "snippet": "В Самарской области продолжается вакцинация от новой коронавирусной инфекции. Особое ?...",
            "url": "http://tltgorod.ru/news/theme-32/news-120508/",
            "image_url": "https://tltgorod.ru/favicon.ico",
            "language": "ru",
            "published_at": "2021-12-02T07:14:00.000000Z",
            "source": "tltgorod.ru",
            "categories": [
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "0a0b743b-11ce-48be-a8f0-17764d3a036e",
            "title": "Baldwin o tragedii na planie \"Rust\": Nie pociągnąłem za spust",
            "description": "Amerykański aktor i gwiazdor filmowy Alec Baldwin oświadczył w środę w wywiadzie dla telewizji ABC, że \"nie pociągnął za spust\" broni, która zabiła o...",
            "keywords": "",
            "snippet": "Nigdy nie wycelowałbym broni w nikogo i nie pociągnąłbym za spust. Nigdy - powiedział Baldwin w trwającej 80 minut rozmowie z dziennikarzem ABC George Ste...",
            "url": "https://film.dziennik.pl/news/artykuly/8304979,alec-baldwin-rust-bron-smierc-na-planie-halyna-hutchins.html",
            "image_url": "https://ocdn.eu/pulscms-transforms/1/E8UktkuTURBXy8wZTY3NmI5OS0xMTY3LTQ3NzUtOTQ4OC0zNmVjYzk4NWZhNDYuanBlZ5GTBc0EsM0CdA",
            "language": "pl",
            "published_at": "2021-12-02T07:13:44.000000Z",
            "source": "film.dziennik.pl",
            "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: 2021-12-02T07:18:11 | 2021-12-02T07:18 | 2021-12-02T07 | 2021-12-02 | 2021-12 | 2021
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: 2021-12-02T07:18:11 | 2021-12-02T07:18 | 2021-12-02T07 | 2021-12-02 | 2021-12 | 2021
published_on false Find all articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2021-12-02
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=2021-11-25
    

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.