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!

If you require full article content or to extract article data from live links, check out articlextractor API .

To perform analysis on any text from our API, check out NLP-API.com for powerful Natural Language Processing tools.

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: 2023-06-09
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": "acfe145c-2525-40be-9626-65dd15e1e7d1",
                "title": "Trump struggles to pitch a coherent defense after docs case indictment",
                "description": "Donald Trump had plenty of time to come up with talking points about his federal criminal indictment. He apparently couldn't think of much of anything.",
                "keywords": "",
                "snippet": "It seems like ages ago, but the story first reached the public on Feb. 7, 2022 — a full 16 months ago. The Washington Post reported that the National Archives...",
                "url": "https://www.msnbc.com/rachel-maddow-show/maddowblog/trump-struggles-pitch-coherent-defense-docs-case-indictment-rcna88516",
                "image_url": "https://media-cldnry.s-nbcnews.com/image/upload/t_nbcnews-fp-1200-630,f_auto,q_auto:best/rockcms/2023-01/230127-donald-trump-cs-bb27ac.jpg",
                "language": "en",
                "published_at": "2023-06-09T12:00:18.000000Z",
                "source": "msnbc.com",
                "categories": [
                    "general",
                    "politics"
                ],
                "locale": "us",
                "similar": [
                    {
                        "uuid": "9571bafe-c812-4e7c-a091-08b0cfca7548",
                        "title": "Trump tests ‘crime doesn’t pay’ adage with post-indictment appeals",
                        "description": "If there’s one thing Donald Trump and his team know how to do, it’s separate people who trust him from their money — even after an indictment.",
                        "keywords": "",
                        "snippet": "The Wall Street Journal reported a couple of weeks ago that special counsel Jack Smith’s investigation into Donald Trump’s classified documents scandal was ...",
                        "url": "https://www.msnbc.com/rachel-maddow-show/maddowblog/trump-tests-crime-doesnt-pay-adage-post-indictment-appeals-rcna88531",
                        "image_url": "https://media-cldnry.s-nbcnews.com/image/upload/t_nbcnews-fp-1200-630,f_auto,q_auto:best/rockcms/2023-05/230501-donald-trump-jm-1610-5f7cec.jpg",
                        "language": "en",
                        "published_at": "2023-06-09T13:22:36.000000Z",
                        "source": "msnbc.com",
                        "categories": [
                            "general",
                            "politics"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "f56d1d08-5322-4356-8cad-288520a80f3a",
                        "title": "Trump federal indictment unsealed in classified documents probe",
                        "description": "The special counsel investigating former President Donald Trump unsealed the federal indictment and revealed more details about the charges.",
                        "keywords": "",
                        "snippet": "The indictment comes in the special counsel's classified documents case.\n\nFederal prosecutors unsealed the indictment Friday against former President Donald Tru...",
                        "url": "https://abcnews.go.com/US/trump-federal-indictment-unsealed-classified-documents-probe/story?id=99963920",
                        "image_url": "https://s.abcnews.com/images/Politics/midterms-election-big-picture-mar-a-lago-fbi-03-sh-llr-220901_1662079309830_hpMain_2_16x9_992.jpg",
                        "language": "en",
                        "published_at": "2023-06-09T17:45:53.000000Z",
                        "source": "abcnews.go.com",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "27061216-a2eb-4493-b111-fd6593641f96",
                        "title": "Read the full text of the Trump indictment in classified documents case",
                        "description": "The second indictment against President Donald Trump was released Friday, he was charged with seven counts and is set to appear in court in Miami on Tuesday. Read the full document here.",
                        "keywords": "",
                        "snippet": "More on the Trump classified documents indictment\n\nThe latest: Former president Donald Trump says he has been indicted in connection with the discovery of hundr...",
                        "url": "https://www.washingtonpost.com/national-security/2023/06/09/indictment-document-trump-classified-documents-pdf/",
                        "image_url": "https://www.washingtonpost.com/resizer/2CjPNwqvXHPS_2RpuRTKY-p3eVo=/1484x0/www.washingtonpost.com/pb/resources/img/twp-social-share.png",
                        "language": "en",
                        "published_at": "2023-06-09T17:53:10.000000Z",
                        "source": "washingtonpost.com",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "8812fddf-1a75-4a56-817d-685980d6e06f",
                        "title": "Federal indictment against former President Trump unsealed",
                        "description": "Former President Donald Trump unlawfully kept hundreds of classified government documents at his Mar-a-Lago estate after leaving office -- including papers detailing America's conventional and nuclear weapons programs, potential weak points in US defenses, and plans to respond to a foreign attack, federal prosecutors charged Friday",
                        "keywords": "News, donald trump, justice department, trump indictment",
                        "snippet": "Former President Donald Trump unlawfully kept hundreds of classified government documents at his Mar-a-Lago estate after leaving office — including papers det...",
                        "url": "https://nypost.com/2023/06/09/federal-indictment-against-former-president-trump-unsealed/",
                        "image_url": "https://nypost.com/wp-content/uploads/sites/2/2023/06/donald-trump-indictment-charges-comp.jpg?quality=75&strip=all&w=1024",
                        "language": "en",
                        "published_at": "2023-06-09T17:53:23.000000Z",
                        "source": "nypost.com",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "80984528-8b73-464d-b6ac-620925701511",
                        "title": "Trump could have to wear an ankle monitor following indictment, former prosecutor says",
                        "description": "Following his indictment on charges of mishandling classified documents, Donald Trump could be forced to wear an ankle monitor while awaiting trial, a former federal prosecutor said.",
                        "keywords": "",
                        "snippet": "That is a “calculus based on whether or not he is a flight risk or danger to the community,” she said. Vance said Trump does not qualify as either “in the...",
                        "url": "https://www.bostonglobe.com/2023/06/09/nation/trump-could-have-wear-an-ankle-monitor-following-indictment-former-prosecutor-says/?camp=bg:brief:rss:feedly&rss_id=feedly_rss_brief",
                        "image_url": "https://bostonglobe-prod.cdn.arcpublishing.com/resizer/68Qmux0RWe2oL_X5EZvSZ9ahfhs=/506x0/cloudfront-us-east-1.images.arcpublishing.com/bostonglobe/W6OZLUGZKOLNE7B6QYTFQZDMZA.jpg",
                        "language": "en",
                        "published_at": "2023-06-09T17:32:23.000000Z",
                        "source": "bostonglobe.com",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    }
                ]
            },
            {
                "uuid": "86416a72-52ab-4273-ac8e-fec1a6059fab",
                "title": "Top Dutch court rules on Crimean gold treasures",
                "description": "The Supreme Court of the Netherlands has ordered a Scythian gold collection to be transferred to Kiev instead of museums in Crimea",
                "keywords": "",
                "snippet": "The Supreme Court of the Netherlands has ordered a borrowed Scythian collection to be sent to Kiev\n\nA collection of Scythian gold artifacts borrowed from Crimea...",
                "url": "https://www.rt.com/news/577794-netherlands-crimean-gold-ukraine/",
                "image_url": "https://mf.b37mrtl.ru/files/2023.06/article/64834fc185f54040004e864d.jpg",
                "language": "en",
                "published_at": "2023-06-09T17:15:40.000000Z",
                "source": "rt.com",
                "categories": [
                    "general",
                    "politics"
                ],
                "locale": "us",
                "similar": [
                    {
                        "uuid": "11efe53e-a724-499b-b3c2-95f886e1d2fe",
                        "title": "Court ruling on Black political power in Alabama could affect maps in other states",
                        "description": "A major Supreme Court decision in an Alabama redistricting case could provide a roadmap for other gerrymandering challenges. There are similar challenges to maps elsewhere in the South.",
                        "keywords": "",
                        "snippet": "Court ruling on Black political power in Alabama could affect maps in other states\n\nEnlarge this image toggle caption Patrick Semansky/AP Patrick Semansky/AP\n\nM...",
                        "url": "https://www.npr.org/2023/06/09/1181211850/alabama-redistricting-supreme-court-ruling-reaction",
                        "image_url": "https://media.npr.org/assets/img/2023/06/08/ap23159531310201_wide-b5919494615ff1535a7c6c9dee5d4e64e428024e-s1400-c100.jpg",
                        "language": "en",
                        "published_at": "2023-06-09T09:00:55.000000Z",
                        "source": "npr.org",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "fb27e562-b29e-460d-8e1e-b6c8dc3833ac",
                        "title": "Supreme Court rules in favor of Black voters in Alabama and protects landmark Voting Rights Act",
                        "description": "At a time when state legislatures are enacting laws that restrict who, when and where people can vote, the US Supreme Court ruled to protect voting rights.",
                        "keywords": "",
                        "snippet": "In a surprising ruling on June 8, 2023, the conservative leaning U.S. Supreme Court threw out Republican-drawn congressional districts in Alabama that a lower c...",
                        "url": "https://theconversation.com/supreme-court-rules-in-favor-of-black-voters-in-alabama-and-protects-landmark-voting-rights-act-207389",
                        "image_url": "https://images.theconversation.com/files/531014/original/file-20230608-29-ocxu6c.jpg?ixlib=rb-1.1.0&rect=108%2C233%2C5451%2C2725&q=45&auto=format&w=1356&h=668&fit=crop",
                        "language": "en",
                        "published_at": "2023-06-09T12:51:07.000000Z",
                        "source": "theconversation.com",
                        "categories": [
                            "general",
                            "politics"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "68d9073c-5dd9-4639-80c5-066e94df0204",
                        "title": "Supreme Surprise: Court Upholds Voting Rights Act, Strikes Down Alabama’s Racially Gerrymandered Maps",
                        "description": "In a surprise 5-4 decision Tuesday, the U.S. Supreme Court rejected a racially gerrymandered voting map in Alabama, upholding a key plank of the Voting Rights Act that the conservative majority has spent years whittling away at. Chief Justice John Roberts and Justice Brett Kavanaugh sided with the court’s liberal justices in finding that Alabama’s Republican-drawn congressional districts unlawfully disadvantage Black voters by diluting their voting power, a violation of Section 2 of the Voting Rights Act banning voting practices that discriminate based on race and color. The court ordered Alabama’s Legislature to redraw the map. For more on the decision and the state of voting rights across the country, we are joined by three guests: Khadidah Stone is a named plaintiff in the case and works for the civic engagement organization Alabama Forward; Tish Gotell Faulks is legal director at the ACLU of Alabama; and Davin Rosborough is a senior staff attorney with the ACLU Voting Rights Project who helped  represent the plaintiffs.",
                        "keywords": "",
                        "snippet": "In a surprise 5-4 decision Tuesday, the U.S. Supreme Court rejected a racially gerrymandered voting map in Alabama, upholding a key plank of the Voting Rights A...",
                        "url": "https://www.democracynow.org/2023/6/9/scotus_alabama_gerrymandering",
                        "image_url": "https://www.democracynow.org/images/story/15/67715/full_hd/seg2-scotus.jpg",
                        "language": "en",
                        "published_at": "2023-06-09T12:29:09.000000Z",
                        "source": "democracynow.org",
                        "categories": [
                            "general",
                            "politics"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "fd346003-e827-49e9-9fa1-c3d1f952f076",
                        "title": "Missouri Supreme Court declines to halt August execution of man convicted of killing child",
                        "description": "The Missouri Supreme Court has turned aside an appeal by a man scheduled to be executed in August for killing a 6-year-old girl",
                        "keywords": "Legal proceedings, Crime, Homicide, Courts, U.S. news, General news",
                        "snippet": "The Missouri Supreme Court has turned aside an appeal by a man scheduled to be executed in August for killing a 6-year-old girl\n\nThe Missouri Supreme Court has ...",
                        "url": "https://abcnews.go.com/US/wireStory/missouri-supreme-court-declines-halt-august-execution-man-99961648",
                        "image_url": "https://s.abcnews.com/images/US/abc_news_default_2000x2000_update_16x9_992.jpg",
                        "language": "en",
                        "published_at": "2023-06-09T14:46:37.000000Z",
                        "source": "abcnews.go.com",
                        "categories": [
                            "general",
                            "politics"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "7879e9d8-803c-4d81-9cb9-f313209ec6b0",
                        "title": "Family members co-signed bond for George Santos, court filing says",
                        "description": "The co-signers on a $500,000 bond connected to Republican Rep. George Santos’ federal indictment are family members, his lawyer said in a new court filing, though their names will remain unknown to the public while an appeals process plays out.",
                        "keywords": "domestic alerts, domestic-us politics, george santos, iab-law, iab-politics, international alerts, international-us politics, law and legal system, political figures - us",
                        "snippet": "CNN —\n\nThe co-signers on a $500,000 bond connected to Republican Rep. George Santos’ federal indictment are family members, his lawyer said in a new court f...",
                        "url": "https://www.cnn.com/2023/06/09/politics/george-santos-bond/index.html",
                        "image_url": "https://media.cnn.com/api/v1/images/stellar/prod/230606145238-george-santos-052023.jpg?c=16x9&q=w_800,c_fill",
                        "language": "en",
                        "published_at": "2023-06-09T16:41:13.000000Z",
                        "source": "cnn.com",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    }
                ]
            }
        ],
        "business": ...,
        "sports": ...,
        "tech": ...,
        "science": ...,
        "health": ...
    }
}

Top Stories Available on: All plans

Endpoint

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

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

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

All text data returned is UTF-8.

All dates are in UTC (GMT).

HTTP GET Parameters

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

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

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

For more advanced query examples, see our API Examples section.

When using special characters (+, -, |, ", *, ()) you MUST URL-encode this parameter.
search_fields false Comma separated list of fields to apply the search parameter to.
Supported fields: title | description | keywords | main_text
Example: title,description,keywords
Default: title,main_text
locale false Comma separated list of country codes to include in the result set. Default is all countries. Click here for a list of supported countries.
Example: us,ca (US + Canada).
categories false Comma separated list of categories to include.
Supported categories: general | science | sports | business | health | entertainment | tech | politics | food | travel
Example: business,tech
exclude_categories false Comma separated list of categories to exclude.
domains false Comma separated list of domains to include. List of domains can be obtained through our Sources endpoint, found further down this page.
exclude_domains false Comma separated list of domains to exclude
source_ids false Comma separated list of source_ids to include. List of source_ids can be obtained through our Sources endpoint, found further down this page.
exclude_source_ids false Comma separated list of source_ids to exclude.
language false Comma separated list of languages to include. Default is all.
Click here for a list of supported languages.
Examples: en,es (English + Spanish)
published_before false Find all articles published before the specified date. Supported formats include: Y-m-d\TH:i:s | Y-m-d\TH:i | Y-m-d\TH | Y-m-d | Y-m | Y.
Examples: 2023-06-09T18:40:26 | 2023-06-09T18:40 | 2023-06-09T18 | 2023-06-09 | 2023-06 | 2023
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: 2023-06-09T18:40:26 | 2023-06-09T18:40 | 2023-06-09T18 | 2023-06-09 | 2023-06 | 2023
published_on false Find all articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2023-06-09
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": 695688,
        "returned": 10,
        "limit": 10,
        "page": 1
    },
    "data": [
        {
            "uuid": "fb6d2a47-f2e1-4f1e-8975-885012d5ff17",
            "title": "Blue Jays cut pitcher Anthony Bass after latest anti-LGBTQ comments",
            "description": "The Toronto Blue Jays cut pitcher Anthony Bass on Friday, one day after the right-handed reliever said he didn’t think an anti-LGBTQ social media post he shar...",
            "keywords": "",
            "snippet": "TORONTO — The Toronto Blue Jays cut pitcher Anthony Bass on Friday, one day after the right-handed reliever said he didn’t think an anti-LGBTQ social media ...",
            "url": "https://www.nbcnews.com/nbc-out/out-news/blue-jays-cut-pitcher-anthony-bass-latest-anti-lgbtq-comments-rcna88605",
            "image_url": "https://media-cldnry.s-nbcnews.com/image/upload/t_nbcnews-fp-1200-630,f_auto,q_auto:best/rockcms/2023-06/230609-bluejays-sj-206p-beb1fd.jpg",
            "language": "en",
            "published_at": "2023-06-09T18:14:23.000000Z",
            "source": "nbcnews.com",
            "categories": [
                "general",
                "politics"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "5e46ff18-5b43-499c-adaf-ab1468750aca",
            "title": "Did someone do you a favor? How to say thank you.",
            "description": "As you get older, nice people will fix things and do favors for you. How do you accept their kindness with grace?",
            "keywords": "article_normal, manners, thankyou, gratitude, Health Care, Leisure/Arts, Labor/Personnel Issues, Corporate/Industrial News, Political/General News, Living/Lifestyle, Personal Finance, Retirement Planning, Advice, Content Types, Factiva Filters, C&E Industry News Filter, labor, personnel issues, corporate, industrial news, political, general news, living, lifestyle, personal finance, retirement planning, advice, content types, factiva filters, c&e industry news filter, health care, leisure, arts",
            "snippet": "Older people often get help from family, friends and strangers. From rides to the doctor to neighborly check-ins during a heat wave, seniors may feel grateful f...",
            "url": "https://www.marketwatch.com/story/did-someone-do-you-a-favor-how-to-say-thank-you-9482cde",
            "image_url": "https://images.mktw.net/im-797173/horizontal",
            "language": "en",
            "published_at": "2023-06-09T18:10:00.000000Z",
            "source": "marketwatch.com",
            "categories": [
                "business",
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "1715f40a-20ed-4515-9f65-daac12d020e1",
            "title": "Tatcha Flash Sale Alert: Get $400 Worth of Skincare Products for $140",
            "description": "Get the Rice Polish, Serum Stick, Ageless Eye Cream and Ageless Enriching Renewal Cream at an unbeatable price today only.",
            "keywords": "",
            "snippet": "We independently selected these deals and products because we love them, and we think you might like them at these prices. E! has affiliate relationships, so we...",
            "url": "https://www.eonline.com/news/1376796/tatcha-flash-sale-alert:-get-over-dollar400-worth-of-amazing-skincare-products-for-dollar140?cmpid=rss-syndicate-genericrss-us-top_stories",
            "image_url": "https://akns-images.eonline.com/eol_images/Entire_Site/202359/rs_1200x1200-230609104842-1200-Tatcha-LT-060923.jpg?fit=around%7C1080:1080&output-quality=90&crop=1080:1080;center,top",
            "language": "en",
            "published_at": "2023-06-09T18:10:00.000000Z",
            "source": "eonline.com",
            "categories": [
                "entertainment",
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "0aba08ab-7ed9-41b1-8c7a-94bbae29d6b7",
            "title": "Blake Shelton Finally Congratulates Niall Horan on Voice Win",
            "description": "Watch Blake Shelton hilariously poke fun at The Voice's Niall Horan after the One Direction alum beat him to win season 23, Shelton's final season on the NBC si...",
            "keywords": "",
            "snippet": "Watch : Blake Shelton Tells Best Thing About The Voice For His Final Season\n\nBlake Shelton is finally delivering a long-awaited congratulations to fellow The Vo...",
            "url": "https://www.eonline.com/news/1376784/blake-shelton-finally-congratulates-lessigreaterthe-voicelessigreater-s-niall-horan-in-the-most-classic-blake-shelton-way?cmpid=rss-syndicate-genericrss-us-tv",
            "image_url": "https://akns-images.eonline.com/eol_images/Entire_Site/2023423/rs_1200x1200-230523174509-1200-blake-shelton-niall-horan.cm.52323.jpg?fit=around%7C1080:1080&output-quality=90&crop=1080:1080;center,top",
            "language": "en",
            "published_at": "2023-06-09T18:09:24.000000Z",
            "source": "eonline.com",
            "categories": [
                "entertainment"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "e1adf4f6-a6f6-4888-ba40-2d574336f584",
            "title": "Blake Shelton Finally Congratulates Niall Horan on Voice Win",
            "description": "Watch Blake Shelton hilariously poke fun at The Voice's Niall Horan after the One Direction alum beat him to win season 23, Shelton's final season on the NBC si...",
            "keywords": "",
            "snippet": "Watch : Blake Shelton Tells Best Thing About The Voice For His Final Season\n\nBlake Shelton is finally delivering a long-awaited congratulations to fellow The Vo...",
            "url": "https://www.eonline.com/news/1376784/blake-shelton-finally-congratulates-lessigreaterthe-voicelessigreater-s-niall-horan-in-the-most-classic-blake-shelton-way?cmpid=rss-syndicate-genericrss-us-top_stories",
            "image_url": "https://akns-images.eonline.com/eol_images/Entire_Site/2023423/rs_1200x1200-230523174509-1200-blake-shelton-niall-horan.cm.52323.jpg?fit=around%7C1080:1080&output-quality=90&crop=1080:1080;center,top",
            "language": "en",
            "published_at": "2023-06-09T18:09:24.000000Z",
            "source": "eonline.com",
            "categories": [
                "entertainment",
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "8a6ae99d-cc02-4eac-93e5-5f65559219b1",
            "title": "Walt Nauta’s indictment is a warning to 'Trump’s Mar-a-Lago mafia'",
            "description": "Special counsel Jack Smith has indicted former President Donald Trump and his aide Walt Nauta in the investigation of classified documents.",
            "keywords": "",
            "snippet": "When news broke Thursday that special counsel Jack Smith decided to indict former President Donald Trump over his classified documents scandal, one of the most ...",
            "url": "https://www.msnbc.com/opinion/msnbc-opinion/walt-nauta-indictment-trump-mar-a-lago-mafia-rcna88157",
            "image_url": "https://media-cldnry.s-nbcnews.com/image/upload/t_nbcnews-fp-1200-630,f_auto,q_auto:best/rockcms/2023-06/230609-walt-nauta-mn-1230-dd1e3c.jpg",
            "language": "en",
            "published_at": "2023-06-09T18:08:28.000000Z",
            "source": "msnbc.com",
            "categories": [
                "general",
                "politics"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "2d0e2587-e52c-4871-8d39-ac6de7ee4ae6",
            "title": "Margaret Josephs Reacts to Teresa Giudice's Shade About Her Looks",
            "description": "Margaret Josephs and Rachel Fuda weighed in on the 'RHONJ' season 13 reunion and why the show needs more 'positive energy' — exclusive",
            "keywords": "",
            "snippet": "Standing up for herself. The Real Housewives of New Jersey star Margaret Josephs has some thoughts on costar Teresa Giudice’s recent comment about her looks.\n...",
            "url": "https://www.usmagazine.com/entertainment/news/margaret-josephs-reacts-to-teresa-giudices-shade-about-her-looks/",
            "image_url": "https://www.usmagazine.com/wp-content/uploads/2023/06/Margaret-Josephs-Claps-Back-at-Teresa-Giudice.jpg?crop=0px%2C16px%2C2000px%2C1050px&resize=1200%2C630&quality=86&strip=all",
            "language": "en",
            "published_at": "2023-06-09T18:07:42.000000Z",
            "source": "usmagazine.com",
            "categories": [
                "entertainment",
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "09031eb5-6a53-451c-b30b-94cf677f0cf2",
            "title": "What in the World?",
            "description": "Test yourself on the week of June 3: Saudi Arabia announces oil cuts, Mexico holds an important state election, and a Ukrainian dam breaks.",
            "keywords": "",
            "snippet": "Over the last few years, the United States has moved to limit China’s technological rise. U.S.-led sanctions have imposed unprecedented limits on Beijing’s ...",
            "url": "https://foreignpolicy.com/2023/06/09/foreign-policy-news-quiz-saudi-arabia-oil-cuts-russia-ukraine-war/",
            "image_url": "https://foreignpolicy.com/wp-content/uploads/2023/06/Ukraine-dam-flood-dog-GettyImages-1258542687.jpg?w=1000",
            "language": "en",
            "published_at": "2023-06-09T18:06:00.000000Z",
            "source": "foreignpolicy.com",
            "categories": [
                "general",
                "politics"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "d0a62585-7053-423a-a0e1-11d46ff58209",
            "title": "MassGOP: New leader, same chaos and internal division",
            "description": "A Thursday evening meeting of the Republican State Committee devolved into some five hours of shouting matches and contentious debate.",
            "keywords": "",
            "snippet": "At a Thursday evening meeting of the Republican State Committee, a packed agenda devolved into some five hours of shouting matches and contentious debate, as th...",
            "url": "https://www.bostonglobe.com/2023/06/09/metro/massgop-chaos-and-division-continues-under-new-chair/?camp=bg:brief:rss:feedly&rss_id=feedly_rss_brief",
            "image_url": "https://bostonglobe-prod.cdn.arcpublishing.com/resizer/5cQFDj40Qxf7as0TfwbYn88Qq_w=/506x0/cloudfront-us-east-1.images.arcpublishing.com/bostonglobe/ISC7XWZOTAT3UPPMOVHYRCKKDE.jpg",
            "language": "en",
            "published_at": "2023-06-09T18:05:18.000000Z",
            "source": "bostonglobe.com",
            "categories": [
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "6b0a82bb-6709-4c90-86c4-b583c93e2bd2",
            "title": "My ex-husband died and I inherited his Roth IRA. Why am I being taxed on it?",
            "description": "You should have been taking RMD based on your life expectancy.",
            "keywords": "article_normal, roth, ira, rmd, spouse, Accounting/Consulting, Business/Consumer Services, Government Finance, Government Budget/Taxation, Direct Taxation, Economic News, Political/General News, Individual Retirement Accounts, Personal Finance, Retirement Planning, government finance, government budget, taxation, direct taxation, economic news, political, general news, individual retirement accounts, personal finance, retirement planning, accounting, consulting, business, consumer services",
            "snippet": "Dear Dan,\n\nMy ex-husband died in 2017. We had been divorced for over 40 years. I was still listed as the beneficiary. The Roth was started a very long time ago....",
            "url": "https://www.marketwatch.com/story/my-ex-husband-died-and-i-inherited-his-roth-ira-why-am-i-being-taxed-on-it-eeff183b",
            "image_url": "https://images.mktw.net/im-750417/social",
            "language": "en",
            "published_at": "2023-06-09T18:05:00.000000Z",
            "source": "marketwatch.com",
            "categories": [
                "business",
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        }
    ]
}

All News Available on: All plans

Endpoint

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

Use this endpoint to find all live and historical articles we collect. Filtering by language, category, source and publish date is also possible, as well as advanced searching on title and the main text of the article.

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

All text data returned is UTF-8.

All dates are in UTC (GMT).

HTTP GET Parameters

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

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

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

For more advanced query examples, see our API Examples section.

When using special characters (+, -, |, ", *, ()) you MUST URL-encode this parameter.
search_fields false Comma separated list of fields to apply the search parameter to.
Supported fields: title | description | keywords | main_text
Example: title,description,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: 2023-06-09T18:40:26 | 2023-06-09T18:40 | 2023-06-09T18 | 2023-06-09 | 2023-06 | 2023
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: 2023-06-09T18:40:26 | 2023-06-09T18:40 | 2023-06-09T18 | 2023-06-09 | 2023-06 | 2023
published_on false Find all articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2023-06-09
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": 59855261,
        "returned": 10,
        "limit": 10,
        "page": 1
    },
    "data": [
        {
            "uuid": "04bbe943-e27e-49d2-98c9-ec232cb5eb18",
            "title": "La Policía Nacional enseña a combatir los riesgos de internet a 600 escolares de la provincia",
            "description": "",
            "keywords": "",
            "snippet": "Teniendo en cuenta que hoy en día las nuevas tecnologías han cambiado nuestra forma de relacionarnos y comunicarnos con los demás, es normal que a los adu...",
            "url": "https://www.horajaen.com/2023/06/09/la-policia-nacional-ensena-a-combatir-los-riesgos-de-internet-a-600-escolares-de-la-provincia/",
            "image_url": "https://www.horajaen.com/wp-content/uploads/2023/06/PHOTO-1.jpg",
            "language": "es",
            "published_at": "2023-06-09T18:40:38.000000Z",
            "source": "horajaen.com",
            "categories": [
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "9f04a4f6-08ff-4cf7-8da4-04cf30d8c3bc",
            "title": "UP Govt To Organise International Trade Show In September",
            "description": "UP International Trade Show will be held from 21 to 25 September at India Expo Center and Mart, Greater Noida, , uttar pradesh, government",
            "keywords": ", uttar pradesh, government",
            "snippet": "Uttar Pradesh government will be organising an International Trade Show to showcase the state’s investment opportunities and the state’s goal towards achiev...",
            "url": "https://www.businessworld.in/article/UP-Govt-To-Organise-International-Trade-Show-In-September-/09-06-2023-479939/",
            "image_url": "https://www.businessworld.in/article/UP-Govt-To-Organise-International-Trade-Show-In-September-/09-06-2023-479939/1686316224_bcAhow_1223.jpg",
            "language": "en",
            "published_at": "2023-06-09T18:40:36.000000Z",
            "source": "businessworld.in",
            "categories": [
                "business",
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "1f1c142a-d445-49d3-8fd5-78502ebced51",
            "title": "김희재 팬 ‘희랑별’, 희재 생일기념 1736만원 기부",
            "description": "K-팝 트로트 부문 가수 김희재의 공식 팬클럽 ‘희랑별’이 김희재의 생일을 기념해 1736만여 원을 사랑의열매 사회복지?...",
            "keywords": "헤럴드경제, 헤경, heraldcorp, 경제지, 신문, 뉴스, 보도, 속보, 정치, 경제, 사회, 국제, 문화, 사설, 컬럼, News, Newspaper, Korea, South Korea, Rep.Korea",
            "snippet": "사랑의열매에..3년간 1억 1613만원\n\n[헤럴드경제=함영훈 기자] K-팝 트로트 부문 가수 김희재의 공식 팬클럽 ‘희랑별’이 ?...",
            "url": "https://biz.heraldcorp.com/view.php?ud=20230609000599",
            "image_url": "https://res.heraldm.com/content/image/2023/06/09/20230609000602_p.jpg",
            "language": "ko",
            "published_at": "2023-06-09T18:40:06.000000Z",
            "source": "biz.heraldcorp.com",
            "categories": [
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "1619148f-f51c-4757-9cac-89bfa85bee61",
            "title": "\"Il cavallo e la torre\"",
            "description": "Ospite il Cardinale Mauro Gambetti",
            "keywords": "",
            "snippet": "",
            "url": "https://www.rai.it/ufficiostampa/assets/template/us-articolo.html?ssiPath=/articoli/2023/06/Il-cavallo-e-la-torre-f051e341-1162-4b21-8626-0f64f58d4b28-ssi.html",
            "image_url": "https://www.rai.it/ufficiostampa/assets/images/favicon.png",
            "language": "it",
            "published_at": "2023-06-09T18:40:00.000000Z",
            "source": "rai.it",
            "categories": [
                "business"
            ],
            "relevance_score": null
        },
        {
            "uuid": "cb487cc1-a00c-43d4-8ee1-5260ff19d892",
            "title": "Euro-Stoxx50 : la marge de sécurité s'amenuise avant 4.350",
            "description": "Euro-Stoxx50 aligne 4 séance à l'horizontal vers 4.290 et la marge de sécurité s'amenuise avant 4.250.Mais déjà sous 4.260, la situation deviendrait d -  ...",
            "keywords": "",
            "snippet": "(CercleFinance.com) - Euro-Stoxx50 aligne 4 séance à l'horizontal vers 4.290 et la marge de sécurité s'amenuise avant 4.250.\n\nMais déjà sous 4.260, la sit...",
            "url": "https://www.abcbourse.com/marches/euro-stoxx50-la-marge-de-securite-s-amenuise-avant-4350_597590",
            "image_url": "https://www.abcbourse.com/apple-icon.png",
            "language": "fr",
            "published_at": "2023-06-09T18:40:00.000000Z",
            "source": "abcbourse.com",
            "categories": [
                "business"
            ],
            "relevance_score": null
        },
        {
            "uuid": "e09254ab-2697-43ff-8d48-6b35a59182f6",
            "title": "#PlaybyPlay Podcast: Electronic Arts (NasdaqGS: $EA) Renews Partnership with CONMEBOL and EA Sports, and Vail Resorts (NYSE: $MTN) Posts Q3 Results",
            "description": "",
            "keywords": "",
            "snippet": "Vancouver, Kelowna and Delta, BC - June 9, 2023 (Investorideas.com Newswire) Investorideas.com, a global investor news source issues today's edition of Play by ...",
            "url": "https://www.investorideas.com/news/2023/play-by-play/06091EA-MTN.asp",
            "image_url": "http://www.investorideas.com/images/sports-stocks.gif",
            "language": "en",
            "published_at": "2023-06-09T18:40:00.000000Z",
            "source": "investorideas.com",
            "categories": [
                "business"
            ],
            "relevance_score": null
        },
        {
            "uuid": "23590fd1-2b7b-41b4-a021-f422cdbf4351",
            "title": "订单已达150万台 特斯拉首台电动皮卡Cybertruck将于9月开启交付",
            "description": "订单已达150万台 特斯拉首台电动皮卡Cybertruck将于9月开启交付",
            "keywords": "特斯拉, 新能源汽车, Cybertruck, 订单已达150万台 特斯拉首台电动皮卡Cybertruck将于9月开启交付, 快科技",
            "snippet": "订单已达150万台 特斯拉首台电动皮卡Cybertruck将于9月开启交付\n\n快科技6月9日消息，据海外媒体报道，自2019年11月22日发布?...",
            "url": "https://news.mydrivers.com/1/915/915651.htm",
            "image_url": "https://img1.mydrivers.com/img/20230609/2243ca670a044a29a6987cc6b286a2bd.png",
            "language": "zh",
            "published_at": "2023-06-09T18:39:54.000000Z",
            "source": "news.mydrivers.com",
            "categories": [
                "tech",
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "d23b00ea-09b7-4d9e-a8f7-3c369b28c057",
            "title": "강도사고시, 코로나 확진자도 응시 가능하다",
            "description": "올해 일반 강도사고시는 코로나19 확진자와 유증상자, 격리대상자도 시험에 응시할 수 있다. 확진자 등은 별도 시험장에?...",
            "keywords": "",
            "snippet": "올해 일반 강도사고시는 코로나19 확진자와 유증상자, 격리대상자도 시험에 응시할 수 있다. 확진자 등은 별도 시험장에?...",
            "url": "http://www.kidok.com/news/articleView.html?idxno=300619",
            "image_url": "https://cdn.kidok.com/news/thumbnail/202306/300619_80598_3944_v150.jpg",
            "language": "ko",
            "published_at": "2023-06-09T18:39:53.000000Z",
            "source": "kidok.com",
            "categories": [],
            "relevance_score": null
        },
        {
            "uuid": "9438f275-6750-4427-823f-478dbd9c328b",
            "title": "Julian Assange perde apelação contra extradição para os EUA",
            "description": "Assange perdeu sua última tentativa de lutar contra a extradição do Reino Unido para os Estados Unidos, mas renovará seu recurso.",
            "keywords": "",
            "snippet": "O fundador do WikiLeaks, Julian Assange, perdeu sua última tentativa de lutar contra a extradição do Reino Unido para os Estados Unidos, onde é procurado po...",
            "url": "https://noticias.uol.com.br/ultimas-noticias/reuters/2023/06/09/julian-assange-perde-apelacao-contra-extradicao-aos-eua-e-renovara-recurso-na-proxima-semana.htm",
            "image_url": "https://conteudo.imguol.com.br/c/noticias/34/2017/11/14/19mai2017---fundador-do-wikileaks-julian-assange-1510679533979_v2_615x300.jpg",
            "language": "pt",
            "published_at": "2023-06-09T18:39:45.000000Z",
            "source": "uol.com.br",
            "categories": [
                "tech",
                "science"
            ],
            "relevance_score": null
        },
        {
            "uuid": "7b5b3c01-7c7d-4524-8a54-991f5757b84d",
            "title": "集微网",
            "description": "集微网，成立于2008年，经过近十年的发展，目前已经成为国内最知名的集成电路及手机行业门户网站。权威报道行业资讯...",
            "keywords": "集微网, 老杳吧, 芯人物, 芯视野, 芯调查, 集微拆评, 一句话点评, 专利解读",
            "snippet": "",
            "url": "https://m.laoyaoba.com/newinfo?id=864979",
            "image_url": "https://m.laoyaoba.com/static/img/logo.ico",
            "language": "zh",
            "published_at": "2023-06-09T18:39:43.000000Z",
            "source": "laoyaoba.com",
            "categories": [
                "tech"
            ],
            "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: 2023-06-09T18:40:26 | 2023-06-09T18:40 | 2023-06-09T18 | 2023-06-09 | 2023-06 | 2023
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: 2023-06-09T18:40:26 | 2023-06-09T18:40 | 2023-06-09T18 | 2023-06-09 | 2023-06 | 2023
published_on false Find all articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2023-06-09
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=2023-06-02

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.