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: 2022-10-04
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": "b879baf0-4754-4372-8125-746cccaef902",
                "title": "Supreme Court allows Dominion’s $1.3 billion defamation suit against Mike Lindell to go forward",
                "description": "Supreme Court allows Dominion’s $1.3 billion defamation suit against Mike Lindell to go forward",
                "keywords": "",
                "snippet": "Mike Lindell is facing a $1.3 billion defamation lawsuit from Dominion Voting Systems, and the far-right conspiracy theorist and MyPillow CEO has been trying to...",
                "url": "https://www.alternet.org/2022/10/supreme-court-refuses-to-dismiss-dominions-1-3-billion-defamation-suit-against-mike-lindell/",
                "image_url": "https://www.alternet.org/media-library/image.jpg?id=31855928&width=1200&height=600&coordinates=0%2C106%2C0%2C107",
                "language": "en",
                "published_at": "2022-10-03T17:13:43.000000Z",
                "source": "alternet.org",
                "categories": [
                    "general",
                    "politics"
                ],
                "locale": "us",
                "similar": [
                    {
                        "uuid": "051ec6e7-09c7-45fd-bd61-fcc10c848541",
                        "title": "This Supreme Court Will Decide the Fate of the Voting Rights Act",
                        "description": "A case before the Supreme Court directly challenges a key provision of the VRA that protects people of color from discrimination.",
                        "keywords": "Redistricting, Stacey Abrams, Voting Rights, Voting Rights Act",
                        "snippet": "Subscribe to The Nation Subscribe now for as little as $2 a month! Subscribe now for as little as $2 a month!\n\nGet The Nation’s Weekly Newsletter Fridays. The...",
                        "url": "https://www.thenation.com/article/society/supreme-court-voting-rights-act/",
                        "image_url": "https://www.thenation.com/wp-content/uploads/2022/10/GettyImages-1229068435.jpg",
                        "language": "en",
                        "published_at": "2022-10-03T16:30:28.000000Z",
                        "source": "thenation.com",
                        "categories": [
                            "general",
                            "politics"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "8f57b248-1d57-4066-adbf-d1d17b037900",
                        "title": "Supreme Court kicks off a new term with controversial cases – and a new justice",
                        "description": "Other than tighter-than-normal security, there was little sign at the Supreme Court of the fallout from its decision to overturn Roe v. Wade.",
                        "keywords": "",
                        "snippet": "Supreme Court kicks off a new term with controversial cases – and a new justice Associate Justice Ketanji Brown Jackson took part in her first oral argument, ...",
                        "url": "https://www.usatoday.com/story/news/politics/2022/10/03/supreme-court-ketanji-brown-jackson-new-term/8118090001/",
                        "image_url": "https://www.gannett-cdn.com/presto/2022/10/03/USAT/815900b4-5ea5-4fa8-a6aa-18631a3fde85-GTY_1430024936.jpg?auto=webp&crop=5833,3282,x0,y296&format=pjpg&width=1200",
                        "language": "en",
                        "published_at": "2022-10-03T19:07:16.000000Z",
                        "source": "usatoday.com",
                        "categories": [
                            "general",
                            "travel",
                            "sports"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "694ccbe0-a81f-4d50-821b-0d23cbc6a7c6",
                        "title": "Supreme Court opens starts new term by hearing case involving Clean Water Act",
                        "description": "The Supreme Court heard arguments Monday in a case involving the scope of the Clean Water Act. The justices also said they will hear arguments next year involving the Telecommunications Act.",
                        "keywords": "",
                        "snippet": "Supreme Court opens starts new term by hearing case involving Clean Water Act The Supreme Court heard arguments Monday in a case involving the scope of the Clea...",
                        "url": "https://www.npr.org/2022/10/03/1126626998/supreme-court-opens-starts-new-term-by-hearing-case-involving-clean-water-act",
                        "image_url": "https://media.npr.org/include/images/facebook-default-wide-s1400-c100.jpg",
                        "language": "en",
                        "published_at": "2022-10-03T20:05:06.000000Z",
                        "source": "npr.org",
                        "categories": [
                            "general",
                            "politics"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "47b44939-e790-4f67-ba0d-9317bfa9ab54",
                        "title": "Supreme Court welcomes the public again, and a new justice",
                        "description": "WASHINGTON — The Supreme Court began its new term Monday with a new justice on the bench, the public back in the courtroom, and a spirited debate in a case that pits environmental protections against property rights.",
                        "keywords": "Supreme Court, Opening Day",
                        "snippet": "Jackson, the court's first Black female justice, seemed to be generally aligned with the court's other liberal justices in favor of Justice Department arguments...",
                        "url": "https://www.bostonglobe.com/2022/10/03/nation/supreme-court-welcomes-public-again-new-justice/?camp=bg:brief:rss:feedly&rss_id=feedly_rss_brief",
                        "image_url": "https://www.bostonglobe.com/pf/resources/images/logo-bg.jpg?d=364",
                        "language": "en",
                        "published_at": "2022-10-03T21:31:39.000000Z",
                        "source": "bostonglobe.com",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "b3d718f6-dd4a-4edd-8e45-44330920f315",
                        "title": "In Supreme Court debut, Justice Jackson grills attorney challenging EPA power under Clean Water Act",
                        "description": "In her Supreme Court debut Monday, Justice Ketanji Brown Jackson asked numerous questions, grilling an attorney challenging the EPA's power under the Clean Water Act.",
                        "keywords": "",
                        "snippet": "After her investiture at the U.S. Supreme Court last week, Justice Ketanji Brown Jackson heralded her \"seat at the table\" and a desire to \"get to work.\"\n\nDuring...",
                        "url": "https://abcnews.go.com/Politics/supreme-court-debut-justice-jackson-grills-attorney-challenging/story?id=90922899",
                        "image_url": "https://s.abcnews.com/images/Politics/supreme-1-ap-er-221003_1664828206351_hpMain_16x9_992.jpg",
                        "language": "en",
                        "published_at": "2022-10-03T22:04:43.000000Z",
                        "source": "abcnews.go.com",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    }
                ]
            },
            {
                "uuid": "b26c1c1b-28fc-481b-a8b5-944e8fc6e7cf",
                "title": "Japan Issues Emergency Alert After North Korean Missile Launch",
                "description": "A missile launched by North Korea on Tuesday morning local time flew over the island of Hokkaido, triggering an emergency alert to 5 million residents.",
                "keywords": "",
                "snippet": "The 5 million residents of Hokkaido, Japan's second largest island, were warned on Tuesday morning local time to take shelter after North Korea launched a missi...",
                "url": "https://www.cnet.com/culture/japan-issues-emergency-alert-after-north-korean-missile-launch/#ftag=CAD590a51e",
                "image_url": "https://www.cnet.com/a/img/resize/300f2fd9d1149db509ff4240f8f12f0af2a37f05/hub/2022/10/03/284e4525-6aa6-4162-8389-cb45a2de1692/screen-shot-2022-10-04-at-10-27-19-am.png?auto=webp&fit=crop&height=630&width=1200",
                "language": "en",
                "published_at": "2022-10-03T23:51:00.000000Z",
                "source": "cnet.com",
                "categories": [
                    "tech",
                    "general"
                ],
                "locale": "us",
                "similar": [
                    {
                        "uuid": "83b7ec56-91a7-486e-9ffe-f4562be228ef",
                        "title": "Japan sent rare warning to residents to shelter from North Korean missile",
                        "description": "The latest launch comes after North Korea in late September fired off one of its biggest barrages of missiles in a week under leader Kim Jong Un.",
                        "keywords": "",
                        "snippet": "(Bloomberg) -- North Korea fired a missile over Japan for the first time since 2017, ratcheting up tensions to levels not seen in years.\n\nThe missile launched T...",
                        "url": "https://www.bostonglobe.com/2022/10/03/world/japan-sent-rare-warning-residents-shelter-north-korean-missile/?camp=bg:brief:rss:feedly&rss_id=feedly_rss_brief",
                        "image_url": "https://bostonglobe-prod.cdn.arcpublishing.com/resizer/XDSFkdqWIWk78j5CQW-yHxtDMM4=/506x0/cloudfront-us-east-1.images.arcpublishing.com/bostonglobe/ECGQUQH4EY2TUW2NFF4TSXFFPM.jpg",
                        "language": "en",
                        "published_at": "2022-10-03T23:30:25.000000Z",
                        "source": "bostonglobe.com",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "a05ee6bc-e4d1-4ba0-a076-32d58a9f66ea",
                        "title": "North Korea fires ballistic missile over Japan, residents warned to take cover",
                        "description": "North Korea fired a ballistic missile off its east coast on Tuesday, South Korea's Joint Chiefs of Staff and the Japanese coast guard said.",
                        "keywords": "News, asia, japan, missiles, north korea, pacific ocean, south korea",
                        "snippet": "SEOUL/TOKYO — North Korea fired a ballistic missile over Japan on Tuesday, prompting a warning for residents to take cover and a temporary suspension of train...",
                        "url": "https://nypost.com/2022/10/03/north-korea-fires-ballistic-missile-over-japan/",
                        "image_url": "https://nypost.com/wp-content/uploads/sites/2/2022/10/north-korea-missiles-056.jpg?quality=75&strip=all&w=1024",
                        "language": "en",
                        "published_at": "2022-10-03T23:25:34.000000Z",
                        "source": "nypost.com",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "ec31968c-cafc-4171-acfd-db8c1c7b4879",
                        "title": "Japan Sends Emergency Alert After North Korean Missile Launch",
                        "description": "A missile launched by North Korea Tuesday morning local time flew over the island of Hokkaido, triggering an emergency alert to 5 million residents.",
                        "keywords": "",
                        "snippet": "The 5 million residents of Hokkaido, Japan's second largest island, were warned on Tuesday morning local time to take shelter after North Korea launched a missi...",
                        "url": "https://www.cnet.com/culture/japan-sends-emergency-alert-after-north-korean-missile-launch/#ftag=CAD590a51e",
                        "image_url": "https://www.cnet.com/a/img/resize/300f2fd9d1149db509ff4240f8f12f0af2a37f05/hub/2022/10/03/284e4525-6aa6-4162-8389-cb45a2de1692/screen-shot-2022-10-04-at-10-27-19-am.png?auto=webp&fit=crop&height=630&width=1200",
                        "language": "en",
                        "published_at": "2022-10-03T23:51:00.000000Z",
                        "source": "cnet.com",
                        "categories": [
                            "tech",
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "bf49f97b-31c1-4dbe-b88e-a4fba438409b",
                        "title": "North Korea fires a ballistic missile over Japan",
                        "description": "The Japanese prime minister's office said at least one missile fired from North Korea flew over Japan and was believed to have landed in the Pacific Ocean.",
                        "keywords": "",
                        "snippet": "North Korea fires a ballistic missile over Japan\n\nEnlarge this image toggle caption Kyodo News via AP Kyodo News via AP\n\nSEOUL, South Korea — North Korea on T...",
                        "url": "https://www.npr.org/2022/10/03/1126660435/north-korea-ballistic-missile-japan",
                        "image_url": "https://media.npr.org/assets/img/2022/10/03/ap22276838455788_wide-870294c277ccd88be772ecd4ad8aca32ad69fc06-s1400-c100.jpg",
                        "language": "en",
                        "published_at": "2022-10-04T00:10:46.000000Z",
                        "source": "npr.org",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "9cf53e7a-d312-4a45-8595-5ce8b893ee96",
                        "title": "North Korea sends missile soaring over Japan",
                        "description": "Japanese authorities issued an alert to residents in some regions to evacuate to buildings nearby.",
                        "keywords": "",
                        "snippet": "Japanese authorities issued a “J-alert” to residents in northeastern regions to evacuate to buildings nearby, the first such alert since 2017. Trains were t...",
                        "url": "https://www.politico.com/news/2022/10/03/north-korea-sends-missile-soaring-over-japan-00060167",
                        "image_url": "https://static.politico.com/b6/c3/95b076cf4a8a923dabdd624e2bf8/https-delivery.gettyimages.com/downloads/1035459584",
                        "language": "en",
                        "published_at": "2022-10-04T01:00:40.000000Z",
                        "source": "politico.com",
                        "categories": [
                            "politics",
                            "general"
                        ],
                        "locale": "us"
                    }
                ]
            }
        ],
        "business": ...,
        "sports": ...,
        "tech": ...,
        "science": ...,
        "health": ...
    }
}
            
        

Top Stories Available on: All plans

Endpoint

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

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

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

All text data returned is UTF-8.

All dates are in UTC (GMT).

HTTP GET Parameters

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

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

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

For more advanced query examples, see our API Examples section.
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: 2022-10-04T04:16:04 | 2022-10-04T04:16 | 2022-10-04T04 | 2022-10-04 | 2022-10 | 2022
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: 2022-10-04T04:16:04 | 2022-10-04T04:16 | 2022-10-04T04 | 2022-10-04 | 2022-10 | 2022
published_on false Find all articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2022-10-04
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": 483664,
        "returned": 10,
        "limit": 10,
        "page": 1
    },
    "data": [
        {
            "uuid": "fff75b4e-825e-45e1-847a-edb74ab1eead",
            "title": "Today in History: October 4, Soviets launch Sputnik",
            "description": "",
            "keywords": "Crime, Violent crime, Shootings, Law and order, Legal proceedings, Sentencing, General news, War and unrest, Lung disease, Coronavirus, Health, Diseases and conditions, Infectious diseases, National governments, National courts, Government and politics, ",
            "snippet": "Today in History: October 4, Soviets launch Sputnik\n\nToday in History\n\nToday is Tuesday, Oct. 4, the 277th day of 2022. There are 88 days left in the year.\n\nTod...",
            "url": "https://abcnews.go.com/US/wireStory/today-history-october-soviets-launch-sputnik-90955884",
            "image_url": "https://s.abcnews.com/images/US/abc_news_default_2000x2000_update_16x9_992.jpg",
            "language": "en",
            "published_at": "2022-10-04T04:00:27.000000Z",
            "source": "abcnews.go.com",
            "categories": [
                "general",
                "politics"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "7bc3b310-a703-4c3d-8d00-ed7cba36b01c",
            "title": "Indonesia police chief, others removed over soccer disaster : news",
            "description": "25.3m 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/xv2s9o/indonesia_police_chief_others_removed_over_soccer/",
            "image_url": "https://external-preview.redd.it/C8NWsO8vJ5bQPqgmZkoCo2LvZXIWlH4pId5xZ2Q69xM.jpg?auto=webp&s=7971ec0a141b0e4afa4c45f0e3cbca73248bf31b",
            "language": "en",
            "published_at": "2022-10-04T03:55:13.000000Z",
            "source": "reddit.com",
            "categories": [
                "general",
                "politics"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "197ec6f8-5e28-4764-9f08-eef431f89dbd",
            "title": "The Try Guys 'deeply hurt' following Ned Fulmer scandal, exit: 'We're losing a friend'",
            "description": "The Try Guys are trying their hand at a YouTube apology video.\\u00a0Eugene, Keith and Zach spoke out about how \\",
            "keywords": "",
            "snippet": "The Try Guys 'deeply hurt' following Ned Fulmer scandal, exit: 'We're losing a friend'\n\nShow Caption Hide Caption The Try Guys talk about their new book and the...",
            "url": "https://www.usatoday.com/story/entertainment/celebrities/2022/10/03/try-guys-speak-out-ned-fulmer-drama/8173536001/",
            "image_url": "https://www.gannett-cdn.com/presto/2022/09/27/USAT/3bd324e7-3a7c-475a-b2a3-c083f785b7bc-XXX_HGS_9456.jpg?auto=webp&crop=8255,4644,x0,y0&format=pjpg&width=1200",
            "language": "en",
            "published_at": "2022-10-04T03:48:16.000000Z",
            "source": "usatoday.com",
            "categories": [
                "general",
                "travel",
                "sports"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "24c6b1b8-15c9-4818-93be-c5b62ce7b04d",
            "title": "Trump's racist comment on Elaine Chao, McConnell's wife, draws criticism from the right",
            "description": "Sen. Rick Scott avoided calling out Trump directly, instead responding vaguely: \\",
            "keywords": "",
            "snippet": "Trump's racist comment on Elaine Chao, McConnell's wife, draws criticism from the right\n\nShow Caption Hide Caption What the New York attorney general lawsuit co...",
            "url": "https://www.usatoday.com/story/news/politics/2022/10/03/trumps-comments-elaine-chao-mitch-mcconnell-draw-fierce-criticism/8166330001/",
            "image_url": "https://www.gannett-cdn.com/presto/2022/09/28/NAAS/c2702eb8-c791-4ff0-a8f0-53e3dd3f21e2-Young_column_1002.jpg?auto=webp&crop=2812,1582,x0,y0&format=pjpg&width=1200",
            "language": "en",
            "published_at": "2022-10-04T03:43:10.000000Z",
            "source": "usatoday.com",
            "categories": [
                "general",
                "travel",
                "sports"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "27f49fd1-6b48-4d9d-80ad-a6e444b56476",
            "title": "A Birthday Inspired by a 1996 Movie About Death",
            "description": "New York City is a beach town, and in the fall it is a haunted beach town.",
            "keywords": "friend Meredith, Lizzie’s newsletter here.Kaitlyn, movie theaters, 35th birthday, jaunty little tune, mere days, mast of a sailboat, friend Martín, Courtesy of Kaitlyn Tiffany, photogenic ways, surge of new supernatural romances, young couple, minutes of travel time, elaborate birthday parties, 37th Birthday, Peter Gallagher, lots of others.And, sound of loud barking noises, mi mi mi mi mi.Lizzie, birthday-weekend office hours, Honk-Shoo Era, oversize button-down shirts, fun-loving husband, Kaitlyn, bus ride, family’s Nantucket beach house, New York Times, Rockaway Beach Surf Club, own 37th birthday, mild conversation, thought experiment, Michelle Pfeiffer, first half of the trailer, most efficient part of our commute, public transit, Perfect Storm, blog post, little wooden stool, off-kilter rom-com premise, Cousin Vinny, long-sleeve shirt, dead wife, free shuttle bus, dress code, Courtesy of Lizzie Plaugic, strong vibes of Leland Palmer, plot twist, wise little glance, part of the A train line, Boston University",
            "snippet": "Sign up for Kaitlyn and Lizzie’s newsletter here.\n\nKaitlyn: According to the 2016 book Love in the Afterlife: Underground Religion at the Movies, the late 198...",
            "url": "https://www.theatlantic.com/newsletters/archive/2022/10/rockaways-birthday-michelle-pfeiffer-new-york/671613/",
            "image_url": "https://cdn.theatlantic.com/thumbor/ovqdESyprGtLGGKto1TTjYfwNjU=/0x204:4792x2700/1200x625/media/img/mt/2022/09/Famous_People_Rockaway/original.jpg",
            "language": "en",
            "published_at": "2022-10-04T03:40:03.000000Z",
            "source": "theatlantic.com",
            "categories": [
                "general",
                "entertainment",
                "politics"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "e3758bce-d687-4c99-b056-0e739b69fdab",
            "title": "The Next Presidential Election Is Happening Right Now in the States",
            "description": "State-legislature elections could decide the fate of democracy.",
            "keywords": "state legislatures, new legislative map, state capitals, city commissioner, Republican election deniers, Kristen McDonald Rivet, Bay City, level of national attention, first run, National groups, Democrats ralliedDemocrats, outcome of the presidential election, State Senate, modern times, legislative power, presidential elections, Joe Biden, Thirty-Fifth District, overall political environment, GOP wave, Capitol Hill, national importance, legislative candidate, year, Democrats, earlier era of U.S. history, independent redistricting commission, congressional elections, past decade, control of state legislatures, legislative chambers, single chamber, Democratic operatives, ratification of the Seventeenth Amendment, tax rates, majority, Mariah Hill, Michigan, tri-cities of Saginaw, hives of legislative activity, school funding, McDonald Rivet, party.If Michigan, Michigan Senate Democrats, majority-making seat, little inkling, comparison.The urgency, state, votes, New Hampshire.Read",
            "snippet": "Kristen McDonald Rivet let out a big, slightly rueful laugh. “I was underestimating the level of national attention this race was going to get,” she told me...",
            "url": "https://www.theatlantic.com/politics/archive/2022/10/republican-midterm-state-elections-2022-michigan/671633/",
            "image_url": "https://cdn.theatlantic.com/thumbor/1hexKyBMOIfVSavika7dVftu3Ac=/0x102:4792x2598/1200x625/media/img/mt/2022/10/important_overlooked_races/original.jpg",
            "language": "en",
            "published_at": "2022-10-04T03:40:03.000000Z",
            "source": "theatlantic.com",
            "categories": [
                "general",
                "entertainment",
                "politics"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "eb789775-5c20-48a7-9703-6c42d6dbc7d6",
            "title": "Ian Urbina Wins 2022 Michael Kelly Award for Story in The New Yorker About the Secret Prisons That Keep Migrants Out of Europe",
            "description": "The Atlantic covers news, politics, culture, technology, health, and more, through its articles, podcasts, videos, and flagship magazine.",
            "keywords": "Ian Urbina, editor of The Atlantic, staff writer, David G. Bradley, news organizations, Urbina’s investigation, Washington Post, National Journal, United States, George Polk Award, Libyan detention centers, African migrants, publications of Atlantic Media, executive editor of NewsGuard, Michael Kelly Award, Pulitzer Prize, shadow immigration system, victims of child sex, Afghan family’s gradual rapprochement, former assistant editor, High Country News, award, Jessica Contrera, previous Michael Kelly Award winner, European shores, Leah Sottile, James Warren, deadly consequences, Ena Alvarado, finalists, Andrew Quilty, Adam Harris, Harper’s Magazine, Michael Kelly’s own life, judges, Cullen Murphy, Taliban.Five judges, commendation, journalist, Bradley, winner, Europe, list of the past winners, way, magazines, tragedies, danger, migrants, homelessness, prize",
            "snippet": "Ian Urbina is the winner of the 19th annual Michael Kelly Award for his story “The Invisible Wall,” published by The New Yorker in partnership with the Outl...",
            "url": "https://www.theatlantic.com/press-releases/archive/2022/10/ian-urbina-wins-2022-michael-kelly-award/671592/",
            "image_url": "https://cdn.theatlantic.com/static/theatlantic/img/lacroix-default-thumbnail.png",
            "language": "en",
            "published_at": "2022-10-04T03:40:03.000000Z",
            "source": "theatlantic.com",
            "categories": [
                "general",
                "entertainment",
                "politics"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "f2dddc8a-9f18-4cb1-8c7b-8b2adda45664",
            "title": "Trump, Putin, and the Assault of Anarchy",
            "description": "We must refuse to get used to it all.",
            "keywords": "first time, Widening GyreI, Russian President Vladimir Putin, last week’s nuclear warnings, biggest stories of the day, Donald Trump’s bizarre statement, canals of Cape Coral, Read Scott McIntyre, widening gyre, favorite books, front-runner, time of hope, American president, Hurricane Irma, Senate Minority Leader Mitch McConnell, W. B. Yeats, greater danger, Tim Alberta, Second Coming, admirer Trump, new ideas, nice visit, former president, Republican presidential nomination, human drama, conspiracy theories, Ross Perot, night, colleague Anne Applebaum, quick stand-alone, threat of Trump, Dead man, democracy itself.And, daily crossword.P.S.My colleagues, early warning sign of our incipient post, Conor Friedersdorf, Florida’s Gulf Coast, larger story, good measure, part of a normal day, Stewart Rhodes, low-lying, public demonstrations, DEATH WISH, high alert, nuclear weapons, Russian officials, time of important choices, fellow citizens, soccer stadium",
            "snippet": "This is an edition of The Atlantic Daily, a newsletter that guides you through the biggest stories of the day, helps you discover new ideas, and recommends the ...",
            "url": "https://www.theatlantic.com/newsletters/archive/2022/10/trump-putin-and-the-assault-of-anarchy/671641/",
            "image_url": "https://cdn.theatlantic.com/thumbor/HByi4op36dswFxWnCYO8wlYdYd8=/0x33:4889x2579/1200x625/media/img/mt/2022/10/GettyImages_1152460422-1/original.jpg",
            "language": "en",
            "published_at": "2022-10-04T03:40:03.000000Z",
            "source": "theatlantic.com",
            "categories": [
                "general",
                "entertainment",
                "politics"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "dafaf849-c310-4028-bf0f-da63066133df",
            "title": "Dynamic Deebo Samuel keeps 49ers rolling over rival Rams",
            "description": "San Francisco used a relentless defense to slow down coach Sean McVay's offense and got enough big plays for the win, the biggest a 57-yard touchdown from Samue...",
            "keywords": "Rams, 49ers",
            "snippet": "The Rams (2-2) won the matchup that meant most in last season's NFC championship game on the way to a Super Bowl title, but this meeting looked more like their ...",
            "url": "https://www.bostonglobe.com/2022/10/03/sports/dynamic-deebo-samuel-keeps-49ers-rolling-over-rival-rams/?camp=bg:brief:rss:feedly&rss_id=feedly_rss_brief",
            "image_url": "https://bostonglobe-prod.cdn.arcpublishing.com/resizer/z2gpshtlSdVeGEvUdieH9GcTP-A=/506x0/cloudfront-us-east-1.images.arcpublishing.com/bostonglobe/SBY4YQNQPGRGFTFXLJWIYOZG6Y.jpg",
            "language": "en",
            "published_at": "2022-10-04T03:35:58.000000Z",
            "source": "bostonglobe.com",
            "categories": [
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "130145dc-1734-4c7e-b0fb-3458452283ac",
            "title": "Video Driver spots bald eagle in Minnesota neighborhood",
            "description": "A woman pulled over to get a rare glimpse of a bald eagle. The stunning bird didn't seem to mind.",
            "keywords": "",
            "snippet": "Driver spots bald eagle in Minnesota neighborhood A woman pulled over to get a rare glimpse of a bald eagle. The stunning bird didn't seem to mind.",
            "url": "https://abcnews.go.com/US/video/driver-spots-bald-eagle-minnesota-neighborhood-90955658",
            "image_url": "https://s.abcnews.com/images/US/221003_abc_social_eagle_hpMain_16x9_608.jpg",
            "language": "en",
            "published_at": "2022-10-04T03:33:09.000000Z",
            "source": "abcnews.go.com",
            "categories": [
                "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.
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: 2022-10-04T04:16:04 | 2022-10-04T04:16 | 2022-10-04T04 | 2022-10-04 | 2022-10 | 2022
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: 2022-10-04T04:16:04 | 2022-10-04T04:16 | 2022-10-04T04 | 2022-10-04 | 2022-10 | 2022
published_on false Find all articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2022-10-04
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": 66397943,
        "returned": 10,
        "limit": 10,
        "page": 1
    },
    "data": [
        {
            "uuid": "8e652ebc-bd45-460c-8b23-500612318c7c",
            "title": "承蒙吴祚来先生的指点,现推出《致人民子弟兵的公开信》极简版。 希望在中华民族的命运抉择之关键时刻,人民子弟兵在人民军队、党卫军、习家军之间,做出正确的选择! #图片, page 1",
            "description": "承蒙吴祚来先生的指点,现推出《致人民子弟兵的公开信》极简版。\n希望在中华民族的命运抉择之关键时刻,人民子弟兵...",
            "keywords": "",
            "snippet": "",
            "url": "https://Lvv2.com/t/4310843",
            "image_url": "https://pbs.twimg.com/media/FeKw5hfWQAMEv8M.png",
            "language": "zh",
            "published_at": "2022-10-04T04:14:11.000000Z",
            "source": "Lvv2.com",
            "categories": [],
            "relevance_score": null
        },
        {
            "uuid": "f03e3456-3acb-4b97-8606-43b8a2a202cb",
            "title": "Oficiais de Justiça em greve",
            "description": "Os oficiais de justiça vão estar em greve nos tribunais judiciais de Lisboa, Porto e Ponta Delgada, esta terça-feira, entre as 9h00 e as 12h30, por questões...",
            "keywords": "RTP, Notícias, RTP Notícias",
            "snippet": "A greve, convocada pelo Sindicato dos Oficiais de Justiça (SOJ), decorrerá também na quinta-feira durante o período da tarde (13h30-17h00) nos núcleos judi...",
            "url": "https://www.rtp.pt/noticias/pais/oficiais-de-justica-em-greve_n1437302",
            "image_url": "https://cdn-images.rtp.pt/icm/noticias/images/9c/9c084d43119f092239e424145af3fd32?w=860&q=90&rect=0,6,850,466&auto=format",
            "language": "pt",
            "published_at": "2022-10-04T04:13:46.000000Z",
            "source": "rtp.pt",
            "categories": [
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "cf01b9a7-f01a-420b-b8bc-3342b17ba8ff",
            "title": "Deebo Samuel, 49ers roll over Rams, forge four-way NFC West tie",
            "description": "The 49ers used some critical big plays on offense and a defense that kept the Rams out of the end zone en route to a victory.",
            "keywords": "NFL, event, San Francisco 49ers, Los Angeles Rams",
            "snippet": "SANTA CLARA, Calif. -- In their two losses this season, the San Francisco 49ers' defense just needed a little help from the offense. On Monday night against the...",
            "url": "https://www.espn.com/nfl/story/_/id/34719962/deebo-samuel-49ers-forge-four-way-tie-nfc-west-handle-depleted-rams-monday-night-football",
            "image_url": "https://a1.espncdn.com/combiner/i?img=%2Fphoto%2F2022%2F1004%2Fr1070692_1296x729_16%2D9.jpg",
            "language": "en",
            "published_at": "2022-10-04T04:13:12.000000Z",
            "source": "espn.com",
            "categories": [
                "sports"
            ],
            "relevance_score": null
        },
        {
            "uuid": "60bc648b-2f7f-475f-9a48-5b696ec17322",
            "title": "好多披萨呀!饼门!",
            "description": "好多披萨呀!饼门!",
            "keywords": "",
            "snippet": "",
            "url": "https://Lvv2.com/t/4310842",
            "image_url": "https://pbs.twimg.com/media/FeKsdVfUAAAlnD7.jpg",
            "language": "zh",
            "published_at": "2022-10-04T04:12:22.000000Z",
            "source": "Lvv2.com",
            "categories": [],
            "relevance_score": null
        },
        {
            "uuid": "8ee338d0-d08f-4a8c-a465-c35cab611f6f",
            "title": "MLB Roundup: Pujols hits home run No. 703, passes Ruth on all-time RBI list",
            "description": "Albert Pujols hit his 703rd home run Monday night, breaking a tie with Babe Ruth for second place in career RBIs, but the St. Louis Cardinals lost to Pittsburgh...",
            "keywords": "",
            "snippet": "PITTSBURGH (AP) — Albert Pujols hit his 703rd home run Monday night, breaking a tie with Babe Ruth for second place in career RBIs, but the St. Louis Cardinal...",
            "url": "https://www.sportsnet.ca/mlb/article/mlb-roundup-pujols-hits-home-run-no-703-passes-ruth-on-all-time-rbi-list/",
            "image_url": "https://www.sportsnet.ca/wp-content/uploads/2022/09/Pujols-6-1040x572.jpg",
            "language": "en",
            "published_at": "2022-10-04T04:12:21.000000Z",
            "source": "sportsnet.ca",
            "categories": [
                "sports"
            ],
            "relevance_score": null
        },
        {
            "uuid": "f1f6a909-1dc5-4459-bafc-d17a4af8798f",
            "title": "Herschel Walker paid for girlfriend’s abortion, report says",
            "description": "DUNWOODY, Ga. (AP) — Herschel Walker, who has vehemently opposed abortion rights as the Republican nominee for U.S. Senate in Georgia, paid for an abo...",
            "keywords": "international, politics, CP_international, CP_politics, FEED_automated, FEEDPROVIDER_CP, United States, georgia, dunwoody, smg_us, CP_URGENCY_4",
            "snippet": "DUNWOODY, Ga. (AP) — Herschel Walker, who has vehemently opposed abortion rights as the Republican nominee for U.S. Senate in Georgia, paid for an abortion fo...",
            "url": "https://www.thestar.com/news/world/us/2022/10/03/herschel-walker-paid-for-girlfriends-abortion-report-says.html",
            "image_url": "https://images.thestar.com/3E-aUEhKubDq0KuVmlYTwLfuAm8=/1280x1024/smart/filters:cb(1664855651626):format(webp)/https://www.thestar.com/content/dam/thestar/news/world/us/2022/10/03/herschel-walker-paid-for-girlfriends-abortion-report-says/20221003231012-633ba4890e4c200aa597b8e7jpeg.jpg",
            "language": "en",
            "published_at": "2022-10-04T04:12:16.000000Z",
            "source": "thestar.com",
            "categories": [
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "edafdd36-cecc-4be2-8cca-f709923dfeb1",
            "title": "The Outer Worlds: Spacer's Choice Rated for PS5, Xbox Series X",
            "description": "The Outer Worlds: Spacer’s Choice Edition has been rated for the PlayStation 5, Xbox Series X|S, and PC [...]",
            "keywords": "The Outer Worlds: Spacer's Choice Rated for PS5, Xbox Series X|S, and PC",
            "snippet": "The Outer Worlds: Spacer's Choice Rated for PS5, Xbox Series X|S, and PC - News\n\n/ 145 Views\n\nby, posted 46 minutes ago\n\nThe Outer Worlds: Spacer’s Choice Edi...",
            "url": "https://www.vgchartz.com/article/455070/the-outer-worlds-spacers-choice-rated-for-ps5-xbox-series-xs-and-pc/",
            "image_url": "https://www.vgchartz.com/articles_media/images/the-outer-worlds-spacers-choice-rated-for-ps5-xbox-series-xs-and-pc-716715_condensed.jpg",
            "language": "en",
            "published_at": "2022-10-04T04:12:15.000000Z",
            "source": "vgchartz.com",
            "categories": [
                "tech"
            ],
            "relevance_score": null
        },
        {
            "uuid": "f8af9adb-eb64-4f3a-b27a-9adb5a8664a6",
            "title": "Seen and Unseen: A Tesla robot and a box office blunder",
            "description": "Fox News contributor Raymond Arroyo has the latest on Elon Musk's new AI robot, New Orleans' mayor living rent-free and a gay rom-com that bombed at the box off...",
            "keywords": "",
            "snippet": "Log in to comment on videos and join in on the fun.",
            "url": "https://www.foxnews.com/video/6313219543112",
            "image_url": "https://a57.foxnews.com/cf-images.us-east-1.prod.boltdns.net/v1/static/694940094001/4a90c18c-ce31-4b91-a15a-2331076d68df/e71e8614-8dc5-4556-8524-371ec602cc4a/1280x720/match/1024/512/image.jpg?ve=1&tl=1",
            "language": "en",
            "published_at": "2022-10-04T04:09:20.000000Z",
            "source": "video.foxnews.com",
            "categories": [
                "general",
                "tech"
            ],
            "relevance_score": null
        },
        {
            "uuid": "f73ccb9e-5de4-45e6-870b-c9b410257292",
            "title": "Apple Cider Donut Cake",
            "description": "Soft, tender, and moist, this apple cider donut cake is packed full of spiced apple cider flavor and covered in crunchy cinnamon sugar.",
            "keywords": "apple, apple cake, apple cider, apple cider donut, apple cider donut cake, bundt cake, cake, cinnamon, fall cakes, fall desserts, no desserts, recipes",
            "snippet": "by registering, you agree to the terms of use",
            "url": "https://foodgawker.com/post/2022/10/03/1017267/",
            "image_url": "https://photo.foodgawker.com/wp-content/uploads/2022/10/3861554.jpg",
            "language": "en",
            "published_at": "2022-10-04T04:09:14.000000Z",
            "source": "foodgawker.com",
            "categories": [
                "food"
            ],
            "relevance_score": null
        },
        {
            "uuid": "e5c555f0-3728-4665-ac38-ec257f7c03a1",
            "title": "49ers use defence, Deebo Samuel to beat Rams 24-9",
            "description": "SANTA CLARA, Calif. (AP) — Deebo Samuel turned a short catch into an electric 57-yard touchdown, Talanoa Hufanga returned an interception for a score ...",
            "keywords": "international, sports, CP_international, FEED_automated, FEEDPROVIDER_CP, United States, California, santa clara, smg_us, CP_URGENCY_2",
            "snippet": "SANTA CLARA, Calif. (AP) — Deebo Samuel turned a short catch into an electric 57-yard touchdown, Talanoa Hufanga returned an interception for a score and the ...",
            "url": "https://www.thestar.com/news/world/us/2022/10/03/49ers-use-defence-deebo-samuel-to-beat-rams-24-9.html",
            "image_url": "https://images.thestar.com/LmYJFT_9dMKthhct6mb9z0Lldbg=/1280x1024/smart/filters:cb(1664853555902):format(webp)/https://www.thestar.com/content/dam/thestar/news/world/us/2022/10/03/49ers-use-defence-deebo-samuel-to-beat-rams-24-9/2022100323108-633ba3c013fbf01b6bcc7396jpeg.jpg",
            "language": "en",
            "published_at": "2022-10-04T04:09:09.000000Z",
            "source": "thestar.com",
            "categories": [
                "general"
            ],
            "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: 2022-10-04T04:16:04 | 2022-10-04T04:16 | 2022-10-04T04 | 2022-10-04 | 2022-10 | 2022
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: 2022-10-04T04:16:04 | 2022-10-04T04:16 | 2022-10-04T04 | 2022-10-04 | 2022-10 | 2022
published_on false Find all articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2022-10-04
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=2022-09-27
    

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.