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 all countries. Click here for a list of supported countries.
Example: us,ca (US + Canada).
domains false Comma separated list of domains to include. List of domains can be obtained through our Sources endpoint, found further down this page.
exclude_domains false Comma separated list of domains to exclude
source_ids false Comma separated list of source_ids to include. List of source_ids can be obtained through our Sources endpoint, found further down this page.
exclude_source_ids false Comma separated list of source_ids to exclude.
language false Comma separated list of languages to include. Default is all.
Click here for a list of supported languages.
Examples: en,es (English + Spanish)
published_on false Find headlines for articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2024-07-25
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": "03647279-e042-4769-bdf6-aa05b0cd36be",
                "title": "Biden Claims U.S. ‘Not at War Anywhere in the World’",
                "description": "President Joe Biden claimed the United States is \"not at war anywhere in the world\" during his live address on Wednesday evening.",
                "keywords": "",
                "snippet": "President Joe Biden claimed that the United States is “not at war anywhere in the world” during his live address on Wednesday evening.\n\nBiden’s speech cam...",
                "url": "https://www.breitbart.com/politics/2024/07/24/biden-claims-united-states-not-war-anywhere-world/",
                "image_url": "https://media.breitbart.com/media/2024/07/53863208126_2c9f4faa9c_o-640x335.jpg",
                "language": "en",
                "published_at": "2024-07-25T01:33:19.000000Z",
                "source": "breitbart.com",
                "categories": [
                    "general",
                    "politics"
                ],
                "locale": "us",
                "similar": [
                    {
                        "uuid": "71b8444e-6ce0-4cb1-8d74-e8e3f2c498d6",
                        "title": "Biden isn't the first president to drop a reelection bid",
                        "description": "Biden dropping out from the 2024 presidential race was unique, but no without some historical parallels.",
                        "keywords": "Article, 112248267",
                        "snippet": "If 2024 has taught us anything, it's that no presidential election is ever the same. This year's contest featured the first major-party nomination of a former p...",
                        "url": "https://abcnews.go.com/538/biden-president-drop-reelection-bid/story?id=112248267",
                        "image_url": "https://i.abcnewsfe.com/a/c736e586-dfcf-454a-b972-b7acd8d2933a/538_Main_HistoricPresDropouts_v05_ag_1721851651274_hpMain_16x9.jpg?w=1600",
                        "language": "en",
                        "published_at": "2024-07-24T23:12:11.000000Z",
                        "source": "abcnews.go.com",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "324bdb9c-0924-4652-973c-2437c8a00257",
                        "title": "So what does Joe Biden do now?",
                        "description": "In an Oval Office speech, Biden said his farewells. But his job isn’t done yet.",
                        "keywords": "",
                        "snippet": "covers politics and society for Vox. She first joined Vox in 2019, and her work has also appeared in Politico, Washington Monthly, and the New Republic.\n\nPresid...",
                        "url": "https://www.vox.com/politics/362997/biden-speech-drop-out-election-harris",
                        "image_url": "https://platform.vox.com/wp-content/uploads/sites/2/2024/07/gettyimages-2162012636.jpg?quality=90&strip=all&crop=0%2C13.421503766366%2C100%2C73.156992467268&w=1200",
                        "language": "en",
                        "published_at": "2024-07-25T01:48:44.000000Z",
                        "source": "vox.com",
                        "categories": [
                            "general",
                            "politics",
                            "entertainment"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "ca177605-d355-4fcb-8978-3d80842813d5",
                        "title": "Biden should have given this speech a year ago",
                        "description": "President Joe Biden should have given this speech a year ago.",
                        "keywords": "",
                        "snippet": "This is the speech President Joe Biden should have given a year ago.\n\nIn a barely 10-minute address to the nation from behind the Resolute Desk Wednesday night,...",
                        "url": "https://www.msnbc.com/opinion/msnbc-opinion/biden-prime-time-speech-wednesday-rcna163345",
                        "image_url": "https://media-cldnry.s-nbcnews.com/image/upload/t_nbcnews-fp-1200-630,f_auto,q_auto:best/rockcms/2024-07/240724-joe-biden-ac-909p-233714.jpg",
                        "language": "en",
                        "published_at": "2024-07-25T02:23:16.000000Z",
                        "source": "msnbc.com",
                        "categories": [
                            "general",
                            "politics"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "3a494fbf-9659-487c-b8a1-5ccad5fd3bd4",
                        "title": "Jill Biden Thanks Biden Voters: 'Time to Put that Trust in Kamala'",
                        "description": "First lady Jill Biden thanked people who have supported her husband, President Joe Biden, for \"never\" wavering in their support.",
                        "keywords": "",
                        "snippet": "First lady Jill Biden thanked people who have supported her husband, President Joe Biden, for “never” wavering in their support, adding that it is time to p...",
                        "url": "https://www.breitbart.com/politics/2024/07/24/jill-biden-thanks-voters-joe-bidens-never-wavered-support-trust-kamala/",
                        "image_url": "https://media.breitbart.com/media/2024/07/jill-biden-waves-joe-biden-feb-2024-marine-1-wh-flickr-640x335.jpg",
                        "language": "en",
                        "published_at": "2024-07-25T03:35:12.000000Z",
                        "source": "breitbart.com",
                        "categories": [
                            "general",
                            "politics"
                        ],
                        "locale": "us"
                    }
                ]
            },
            {
                "uuid": "79400942-4ab1-46c3-8be0-7cacb790e844",
                "title": "Chelsea 2-2 Wrexham (Jul 24, 2024) Game Analysis",
                "description": "Expert recap and game analysis of the Chelsea vs. Wrexham Club Friendly game from July 24, 2024 on ESPN.",
                "keywords": "",
                "snippet": "Lesley Ugochukwu places a shot in the back of the net to tie the score for Chelsea at 2-2.\n\nLesley Ugochukwu's 82nd-minute equaliser salvaged a 2-2 draw for Che...",
                "url": "https://www.espn.com/soccer/report/_/gameId/700486",
                "image_url": "https://a.espncdn.com/combiner/i?img=/i/espn/misc_logos/500/soccer.png",
                "language": "en",
                "published_at": "2024-07-25T06:28:18.000000Z",
                "source": "espn.com",
                "categories": [
                    "sports",
                    "general"
                ],
                "locale": "us",
                "similar": [
                    {
                        "uuid": "f9802d3d-56a7-4b4b-af27-70c658fea232",
                        "title": "France U23 3-0 USA U23 (Jul 24, 2024) Game Analysis",
                        "description": "Expert recap and game analysis of the France U23 vs. United States U23 Men's Olympic Tournament game from July 24, 2024 on ESPN.",
                        "keywords": "",
                        "snippet": "Julien Laurens recaps the United States men's soccer team's 3-0 defeat in their opening game of group play at the Olympics.\n\nFrance beat the United States 3-0 t...",
                        "url": "https://www.espn.com/soccer/report/_/gameId/699808",
                        "image_url": "https://a.espncdn.com/combiner/i?img=/i/espn/misc_logos/500/soccer.png",
                        "language": "en",
                        "published_at": "2024-07-24T23:38:01.000000Z",
                        "source": "espn.com",
                        "categories": [
                            "sports",
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "c4be41eb-11ff-40cc-bbfa-2ba4357abed8",
                        "title": "Liga MX All-Stars 4-1 MLS All-Stars (Jul 24, 2024) Game Analysis",
                        "description": "Expert recap and game analysis of the Liga MX All-Stars vs. MLS All-Stars MLS game from July 24, 2024 on ESPN.",
                        "keywords": "",
                        "snippet": "Maximiliano Meza scores Liga MX's fourth goal of the night in a rout of the MLS All-Stars.\n\nJuan Brunetta and Maximiliano Meza scored a minute apart in the seco...",
                        "url": "https://www.espn.com/soccer/report/_/gameId/699799",
                        "image_url": "https://a.espncdn.com/combiner/i?img=/i/espn/misc_logos/500/soccer.png",
                        "language": "en",
                        "published_at": "2024-07-25T06:28:18.000000Z",
                        "source": "espn.com",
                        "categories": [
                            "sports",
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "089e6cfd-079c-48d4-b136-8951e8a74ff6",
                        "title": "Arsenal 1-1 Bournemouth (Jul 24, 2024) Game Analysis",
                        "description": "Expert recap and game analysis of the Arsenal vs. AFC Bournemouth Club Friendly game from July 24, 2024 on ESPN.",
                        "keywords": "",
                        "snippet": "Jakub Kiwior nets the penalty kick for Arsenal to seal the Gunners' victory over Bournemouth.\n\nArsenal began their preseason with a shootout win over Bournemout...",
                        "url": "https://www.espn.com/soccer/report/_/gameId/711285",
                        "image_url": "https://a.espncdn.com/combiner/i?img=/i/espn/misc_logos/500/soccer.png",
                        "language": "en",
                        "published_at": "2024-07-25T06:28:18.000000Z",
                        "source": "espn.com",
                        "categories": [
                            "sports",
                            "general"
                        ],
                        "locale": "us"
                    }
                ]
            }
        ],
        "business": ...,
        "sports": ...,
        "tech": ...,
        "science": ...,
        "health": ...
    }
}
            
        

Top Stories Available on: All plans

Endpoint

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

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

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

All text data returned is UTF-8.

All dates are in UTC (GMT).

HTTP GET Parameters

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

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

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

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

When using special characters (+, -, |, ", *, ()) you MUST URL-encode this parameter.
search_fields false Comma separated list of fields to apply the search parameter to.
Supported fields: title | description | keywords | main_text
Example: title,description,keywords
Default: title,main_text
locale false Comma separated list of country codes to include in the result set. Default is all countries. Click here for a list of supported countries.
Example: us,ca (US + Canada).
categories false Comma separated list of categories to include.
Supported categories: general | science | sports | business | health | entertainment | tech | politics | food | travel
Example: business,tech
exclude_categories false Comma separated list of categories to exclude.
domains false Comma separated list of domains to include. List of domains can be obtained through our Sources endpoint, found further down this page.
exclude_domains false Comma separated list of domains to exclude
source_ids false Comma separated list of source_ids to include. List of source_ids can be obtained through our Sources endpoint, found further down this page.
exclude_source_ids false Comma separated list of source_ids to exclude.
language false Comma separated list of languages to include. Default is all.
Click here for a list of supported languages.
Examples: en,es (English + Spanish)
published_before false Find all articles published before the specified date. Supported formats include: Y-m-d\TH:i:s | Y-m-d\TH:i | Y-m-d\TH | Y-m-d | Y-m | Y.
Examples: 2024-07-25T10:37:18 | 2024-07-25T10:37 | 2024-07-25T10 | 2024-07-25 | 2024-07 | 2024
published_after false Find all articles published after the specified date. Supported formats include: Y-m-d\TH:i:s | Y-m-d\TH:i | Y-m-d\TH | Y-m-d | Y-m | Y.
Examples: 2024-07-25T10:37:18 | 2024-07-25T10:37 | 2024-07-25T10 | 2024-07-25 | 2024-07 | 2024
published_on false Find all articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2024-07-25
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": 1067055,
        "returned": 10,
        "limit": 10,
        "page": 1
    },
    "data": [
        {
            "uuid": "9a91a423-e042-4826-bc16-add96db18bb7",
            "title": "Russia is banned from the Paris Olympics. Here’s what that means.",
            "description": "Russia is banned from the Paris Olympics, but its athletes aren’t. Instead, they’ll be competing as Individual Neutral Athletes, without their country’s f...",
            "keywords": "",
            "snippet": "Russia, traditionally an Olympic power, will have just a handful of athletes at this year’s Paris Games. Here’s what you need to know about Russia at this y...",
            "url": "https://www.washingtonpost.com/sports/olympics/2024/07/25/russia-paris-olympics-ban-flag-individual-neutral-athletes/",
            "image_url": "https://www.washingtonpost.com/wp-apps/imrs.php?src=https://arc-anglerfish-washpost-prod-washpost.s3.amazonaws.com/public/5XW5YPFEBEI63C2HTBR73KHESQ.jpg&w=1440",
            "language": "en",
            "published_at": "2024-07-25T10:16:38.000000Z",
            "source": "washingtonpost.com",
            "categories": [
                "general",
                "politics"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "431ce6fb-b852-4e79-b43e-2d0c707d3cf1",
            "title": "Who do you think Harris’s VP pick should be? Take our quiz.",
            "description": "Take this quiz and see which people you think Kamala Harris should pick to be the Democratic vice presidential nominee.",
            "keywords": "",
            "snippet": "Vice President Harris isn’t officially the 2024 Democratic nominee, but all signs point to her locking down the nomination, potentially as early as next week....",
            "url": "https://www.washingtonpost.com/elections/interactive/2024/harris-vp-pick-quiz-2024-election/",
            "image_url": "https://www.washingtonpost.com/wp-apps/imrs.php?src=https://arc-anglerfish-washpost-prod-washpost.s3.amazonaws.com/public/E4ZBLPTLCRCFZKISTQRW3JLWJ4.jpg&w=1200",
            "language": "en",
            "published_at": "2024-07-25T10:15:42.000000Z",
            "source": "washingtonpost.com",
            "categories": [
                "politics",
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "8af3f349-a0a9-4426-bb0f-d2a5ba6bcb0c",
            "title": "Cindy Crawford's Honest Reaction to Austin Butler’s Elvis Accent",
            "description": "Cindy Crawford shared her thoughts on Austin Butler’s Elvis accent, admitting she didn’t realize her daughter Kaia Gerber’s boyfriend was Californian",
            "keywords": "",
            "snippet": "Cindy Crawford is getting candid about Austin Butler’s Elvis Presley accent.\n\nThe supermodel was put in the hot seat on the Wednesday, July 24 episode of Watc...",
            "url": "https://www.usmagazine.com/celebrity-news/news/cindy-crawford-shares-her-honest-reaction-to-austin-butlers-never-ending-elvis-accent/",
            "image_url": "https://www.usmagazine.com/wp-content/uploads/2024/07/cindy.jpg?crop=0px%2C47px%2C1398px%2C734px&resize=1200%2C630&quality=86&strip=all",
            "language": "en",
            "published_at": "2024-07-25T10:14:05.000000Z",
            "source": "usmagazine.com",
            "categories": [
                "entertainment",
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "ef7e1ccc-40f9-4889-a9f0-3a485eb3b0d6",
            "title": "J.D. Vance has made it impossible for Trump to run away from Project 2025",
            "description": "He wrote the foreword for a new book by Project 2025’s architect — and has backed some of its most extreme ideas.",
            "keywords": "",
            "snippet": "is a senior politics correspondent at Vox, covering the White House, elections, and political scandals and investigations. He’s worked at Vox since the site?...",
            "url": "https://www.vox.com/politics/362917/jd-vance-project-2025-book-kevin-roberts-trump",
            "image_url": "https://platform.vox.com/wp-content/uploads/sites/2/2024/07/GettyImages-2163101562.jpg?quality=90&strip=all&crop=0%2C10.729513329196%2C100%2C78.540973341608&w=1200",
            "language": "en",
            "published_at": "2024-07-25T10:11:20.000000Z",
            "source": "vox.com",
            "categories": [
                "general",
                "politics",
                "entertainment"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "9af0684f-fc1f-4502-a584-d9dc3a43a869",
            "title": "Sky’s Zai Bennett Heading To BBC Studios To Run Production Arm",
            "description": "Zai Bennett is heading to BBC Studios to run the Strictly Come Dancing & Doctor Who producer.",
            "keywords": "",
            "snippet": "Sky MD Zai Bennett is heading to BBC Studios.\n\nThe Comcast-owned content chief will run BBC Studios Productions, a job that has been vacant for several months a...",
            "url": "https://deadline.com/2024/07/zai-bennett-sky-bbc-studios-1236021319/",
            "image_url": "https://deadline.com/wp-content/uploads/2024/07/Zai-Bennett.jpeg?w=1024",
            "language": "en",
            "published_at": "2024-07-25T10:09:55.000000Z",
            "source": "deadline.com",
            "categories": [
                "entertainment"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "d2ccc177-cb12-463a-98b0-cb02d3d9cd98",
            "title": "Melania Trump to release first memoir, will reveal stories and photos 'never before shared with the public'",
            "description": "Former first lady Melania Trump is set to release her first memoir that will include \"personal stories and family photos she has never before shared with the pu...",
            "keywords": "",
            "snippet": "Former first lady Melania Trump is releasing her first-ever memoir, revealing stories and photos \"never before shared with the public.\"\n\nThe memoir, set to be r...",
            "url": "https://www.foxnews.com/media/melania-trump-release-first-memoir-reveal-stories-photos-never-before-shared-public",
            "image_url": "https://static.foxnews.com/foxnews.com/content/uploads/2024/07/MelaniaTrump.jpg",
            "language": "en",
            "published_at": "2024-07-25T10:00:52.000000Z",
            "source": "foxnews.com",
            "categories": [
                "general",
                "politics"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "b6f7e7df-5658-47ff-969d-41edfb38aa77",
            "title": "In Vance’s ‘Hillbilly’ home, his story rings true — but not always his message",
            "description": "J. D. Vance shaped his image in his memoir, “Hillbilly Elegy,” about his roots in rural Kentucky. Many there question his theories about the White working c...",
            "keywords": "",
            "snippet": "JACKSON, Kentucky — Deep in a quiet mountain holler called Panbowl Branch, outside a decaying town of 2,000 in one of America’s poorest counties, sits a ram...",
            "url": "https://www.washingtonpost.com/nation/2024/07/25/jd-vance-hillbilly-elegy-jackson-kentucky/",
            "image_url": "https://www.washingtonpost.com/wp-apps/imrs.php?src=https://arc-anglerfish-washpost-prod-washpost.s3.amazonaws.com/public/QTOCFSIO77KDNMPP5JKZHKCXJA.JPG&w=1440",
            "language": "en",
            "published_at": "2024-07-25T10:00:36.000000Z",
            "source": "washingtonpost.com",
            "categories": [
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "20411b95-b4cd-4a97-9b4b-45dad5ade50f",
            "title": "Southwest to get rid of open seating, offer extra legroom in biggest shift in its history",
            "description": "Southwest is under pressure to drum up revenue from an oversupplied U.S. market and an activist investor.",
            "keywords": "American Airlines Group Inc, United Airlines Holdings Inc, Delta Air Lines Inc, Boeing Co, Southwest Airlines Co, Investment strategy, Airlines, Travel, Transportation, Aerospace and defense industry, Business, Life, Breaking News: Business, Markets, business news",
            "snippet": "Southwest Airlines is ending open seating and will offer extra legroom seats on its airplanes as mounting pressure on the carrier to increase revenue prompts th...",
            "url": "https://www.cnbc.com/2024/07/25/southwest-airlines-seat-assignments.html",
            "image_url": "https://image.cnbcfm.com/api/v1/image/107405249-17138953192024-02-08t232023z_123676527_rc2ly5atu2sj_rtrmadp_0_southwest-results.jpeg?v=1714045759&w=1920&h=1080",
            "language": "en",
            "published_at": "2024-07-25T10:00:20.000000Z",
            "source": "cnbc.com",
            "categories": [
                "general",
                "business"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "ad408e2a-02bc-491c-a242-9a8db8476a83",
            "title": "Make these 'can't-go-wrong' lobster rolls with family and friends this weekend: Try the easy recipe",
            "description": "Making lobster rolls is a lot more fun and even easier than you might think with this recipe by Holly Nilsson, which uses any part of the lobster because, in th...",
            "keywords": "",
            "snippet": "‘Tis the season for lobster rolls.\n\nAll the better if you’re making these tasty sandwiches with your loved ones, as claw-o-vores of all stripes love the pro...",
            "url": "https://www.foxnews.com/food-drink/make-cant-go-wrong-lobster-rolls-family-friends-weekend-easy-recipe",
            "image_url": "https://static.foxnews.com/foxnews.com/content/uploads/2024/07/lobster-roll-recipe-split.jpg",
            "language": "en",
            "published_at": "2024-07-25T10:00:03.000000Z",
            "source": "foxnews.com",
            "categories": [
                "general",
                "politics"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "5ac5e0ce-2709-4a28-9c6d-748ed4484646",
            "title": "Crossword: Slate’s daily puzzle for July 25, 2024.",
            "description": "Ready for some wordplay? Sharpen your skills with Slate’s puzzle for July 25, 2024.",
            "keywords": "",
            "snippet": "Thanks for signing up! You can manage your newsletter subscriptions at any time.\n\nWe encountered an issue signing you up. Please try again, or manage all your n...",
            "url": "https://slate.com/life/2024/07/crossword-slate-daily-puzzle-july-25-2024.html?via=rss",
            "image_url": "https://compote.slate.com/images/d9433e9f-08cc-4410-a18d-2a683f74753a.jpeg?crop=3000%2C2000%2Cx0%2Cy0&width=1560",
            "language": "en",
            "published_at": "2024-07-25T09:50:00.000000Z",
            "source": "slate.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.

When using special characters (+, -, |, ", *, ()) you MUST URL-encode this parameter.
search_fields false Comma separated list of fields to apply the search parameter to.
Supported fields: title | description | keywords | main_text
Example: title,description,keywords
Default: title,main_text
categories false Comma separated list of categories to include.
Supported categories: general | science | sports | business | health | entertainment | tech | politics | food | travel
Example: business,tech
exclude_categories false Comma separated list of categories to exclude.
domains false Comma separated list of domains to include. List of domains can be obtained through our Sources endpoint, found further down this page.
exclude_domains false Comma separated list of domains to exclude
source_ids false Comma separated list of source_ids to include. List of source_ids can be obtained through our Sources endpoint, found further down this page.
exclude_source_ids false Comma separated list of source_ids to exclude.
language false Comma separated list of languages to include. Default is all.
Click here for a list of supported languages.
Examples: en,es (English + Spanish)
published_before false Find all articles published before the specified date. Supported formats include: Y-m-d\TH:i:s | Y-m-d\TH:i | Y-m-d\TH | Y-m-d | Y-m | Y.
Examples: 2024-07-25T10:37:18 | 2024-07-25T10:37 | 2024-07-25T10 | 2024-07-25 | 2024-07 | 2024
published_after false Find all articles published after the specified date. Supported formats include: Y-m-d\TH:i:s | Y-m-d\TH:i | Y-m-d\TH | Y-m-d | Y-m | Y.
Examples: 2024-07-25T10:37:18 | 2024-07-25T10:37 | 2024-07-25T10 | 2024-07-25 | 2024-07 | 2024
published_on false Find all articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2024-07-25
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": 49141221,
        "returned": 10,
        "limit": 10,
        "page": 1
    },
    "data": [
        {
            "uuid": "c1cb773a-c81a-4f63-ac4c-ebc7eb89d1d5",
            "title": "LG엔솔, 2Q 영업익 1953억…전년대비 57.6% 감소",
            "description": "LG에너지솔루션은 2024년 2분기 연결기준 영업이익 1953억원을 기록했다고 25일 공시했다. 전년 동기대비 57.6% 감소했다. 매?...",
            "keywords": "실적, LG에너지솔루션",
            "snippet": "이 기사를 공유합니다",
            "url": "http://www.shinailbo.co.kr/news/articleView.html?idxno=1908119",
            "image_url": "http://www.shinailbo.co.kr/image/logo/snslogo_20210310015526.jpg",
            "language": "ko",
            "published_at": "2024-07-25T10:37:52.000000Z",
            "source": "shinailbo.co.kr",
            "categories": [],
            "relevance_score": null
        },
        {
            "uuid": "e6748274-334a-4588-8a06-59d24a8f1ba1",
            "title": "우리금융, 자립준비청년 관계맺기 지원 '우리사이' 2기 모집",
            "description": "우리금융미래재단은 자립준비청년을 지원하는 사회공헌사업 ‘우리사이’ 2기를 다음 달 30일까지 모집한다고 25일 밝혔...",
            "keywords": "",
            "snippet": "자립준비청년을 지원하는 사회공헌사업 ‘우리사이’ 1기 참여자들이 지난 6일 우리은행 본점에서 열린 1기 성과보고회?...",
            "url": "http://www.smedaily.co.kr/news/articleView.html?idxno=298554",
            "image_url": "https://cdn.smedaily.co.kr/news/thumbnail/202407/298554_235447_3715_v150.jpg",
            "language": "ko",
            "published_at": "2024-07-25T10:37:51.000000Z",
            "source": "smedaily.co.kr",
            "categories": [
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "14d85c40-8eba-43f8-afc9-33e5b3ec8d09",
            "title": "Editorial: Novel trends in cultured meat research",
            "description": "",
            "keywords": "",
            "snippet": "Article Dans Une Revue (Article De Synthèse) Frontiers in Nutrition Année : 2024\n\nMarie-Pierre Ellies-Oury\n\nChercher dans HAL\n\n(2, 3) , sghaier-chriki\n\nSghaie...",
            "url": "https://hal.inrae.fr/hal-04661724",
            "image_url": "https://hal.inrae.fr/assets/favicon/apple-touch-icon.png",
            "language": "fr",
            "published_at": "2024-07-25T10:37:45.000000Z",
            "source": "hal.archives-ouvertes.fr",
            "categories": [],
            "relevance_score": null
        },
        {
            "uuid": "a88683b0-1268-4531-a4aa-396d368a0fd1",
            "title": "美 연내 3회 인하 전망 재점화…매파 前 뉴욕 연은 총재의 깜짝 변신",
            "description": "미국 금리선물시장에서 연방준비제도(Fed·연준)가 연내 3회 금리를 내릴 수 있다는 전망이 다시 커졌다.24일(현지시간) 시...",
            "keywords": "",
            "snippet": "(서울=연합인포맥스) 문정현 기자 = 미국 금리선물시장에서 연방준비제도(Fed·연준)가 연내 3회 금리를 내릴 수 있다는 전...",
            "url": "https://news.einfomax.co.kr/news/articleView.html?idxno=4318502",
            "image_url": "https://cdn.news.einfomax.co.kr/news/thumbnail/202407/4318502_198847_381_v150.jpg",
            "language": "ko",
            "published_at": "2024-07-25T10:37:31.000000Z",
            "source": "news.einfomax.co.kr",
            "categories": [
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "2ca2fb03-537f-49f4-9674-62955f7f6009",
            "title": "詳訊:中國船在尖閣周邊連續航行天數止步215天",
            "description": "【共同社7月25日電】日本第11管區海上保安總部(那霸)24日稱,此前在尖閣諸島(中國稱釣魚島)周邊領海外側毗連區航...",
            "keywords": "日中關係, ",
            "snippet": "",
            "url": "https://tchina.kyodonews.net/news/2024/07/b166b059d1dd-215.html",
            "image_url": "https://tchina.kyodonews.net/favicon.ico",
            "language": "zh",
            "published_at": "2024-07-25T10:37:27.000000Z",
            "source": "tchina.kyodonews.net",
            "categories": [
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "44d9cdd4-f4a5-440f-b582-482855b0f5a5",
            "title": "详讯:中国船在尖阁周边连续航行天数止步215天",
            "description": "【共同社7月25日电】日本第11管区海上保安总部(那霸)24日称,此前在尖阁诸岛(中国称钓鱼岛)周边领海外侧毗连区航...",
            "keywords": "日中关系, ",
            "snippet": "",
            "url": "https://china.kyodonews.net/news/2024/07/b166b059d1dd-215.html",
            "image_url": "https://china.kyodonews.net/favicon.ico",
            "language": "zh",
            "published_at": "2024-07-25T10:37:27.000000Z",
            "source": "china.kyodonews.net",
            "categories": [
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "9d17a85e-acf8-4909-9c9a-be4d01d2519b",
            "title": "ABC마트, 반스 협업 '티셔츠 커스텀' 프로모션 실시",
            "description": "컨슈머타임스=김동역 기자 | ABC마트는 스케이트보딩 브랜드 반스와 손잡고 세상에 하나뿐인 나만의 티셔츠를 커스텀 할 ...",
            "keywords": "",
            "snippet": "[사진= ABC마트 제공]\n\n컨슈머타임스=김동역 기자 | ABC마트는 스케이트보딩 브랜드 반스와 손잡고 세상에 하나뿐인 나만의...",
            "url": "https://www.cstimes.com/news/articleView.html?idxno=603243",
            "image_url": "https://www.cstimes.com/news/photo/202407/603243_516423_5043.jpg",
            "language": "ko",
            "published_at": "2024-07-25T10:37:25.000000Z",
            "source": "cstimes.com",
            "categories": [],
            "relevance_score": null
        },
        {
            "uuid": "be5a2581-eaec-4be3-b61f-4b89bcd03ad1",
            "title": "미래에셋, 'TIGER 미국S&P500 ETF' 최근 1년간 개인 누적 순매수 ETF 1위",
            "description": "컨슈머타임스=김지훈 기자 | 미래에셋자산운용은 'TIGER 미국S&P500 ETF(360750)'가 국내 상장된 전체 ETF 가운데 최근 1년간 개?...",
            "keywords": "",
            "snippet": "컨슈머타임스=김지훈 기자 | 미래에셋자산운용은 'TIGER 미국S&P500 ETF(360750)'가 국내 상장된 전체 ETF 가운데 최근 1년간 개?...",
            "url": "https://www.cstimes.com/news/articleView.html?idxno=603300",
            "image_url": "https://www.cstimes.com/news/photo/202407/603300_516486_376.jpg",
            "language": "ko",
            "published_at": "2024-07-25T10:37:19.000000Z",
            "source": "cstimes.com",
            "categories": [],
            "relevance_score": null
        },
        {
            "uuid": "c91554fa-a51e-48ae-aff6-9a0c8a60e435",
            "title": "너도나도 뛰어드는 중고차 시장헤이딜러 신사업 발판 되겠네",
            "description": "너도나도 중고자동차 매매 시장에 뛰어들면서 중고차 거래 플랫폼 ‘헤이딜러’의 성장세도 가속화될 것으로 여겨진다....",
            "keywords": "헤이딜러, 피알앤디컴퍼니, 중고차",
            "snippet": "최근 완성차 업체들과 중고 렌터카 업체들이 중고차 매매 시장에 뛰어들면서 헤이딜러 운영사인 피알앤디컴퍼니의 실적...",
            "url": "http://www.smedaily.co.kr/news/articleView.html?idxno=298550",
            "image_url": "https://cdn.smedaily.co.kr/news/thumbnail/202407/298550_235446_3552_v150.jpg",
            "language": "ko",
            "published_at": "2024-07-25T10:37:18.000000Z",
            "source": "smedaily.co.kr",
            "categories": [
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "0f7efd8e-abd3-4339-afba-fe746827cfdd",
            "title": "솔트룩스, 특허청 ‘생성형 AI 심사 업무 지원 서비스’ 개발 나서",
            "description": "[아이티데일리] 인공지능(AI) 기업 솔트룩스(대표 이경일)는 ‘2024년 초거대 AI 기반 서비스 개발 지원사업’의 하나로 AI ?...",
            "keywords": "",
            "snippet": "[아이티데일리] 인공지능(AI) 기업 솔트룩스(대표 이경일)는 ‘2024년 초거대 AI 기반 서비스 개발 지원사업’의 하나로 AI ?...",
            "url": "http://www.itdaily.kr/news/articleView.html?idxno=225506",
            "image_url": "https://cdn.itdaily.kr/news/thumbnail/202407/225506_229986_1717_v150.jpg",
            "language": "ko",
            "published_at": "2024-07-25T10:37:12.000000Z",
            "source": "itdaily.kr",
            "categories": [
                "tech",
                "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: 2024-07-25T10:37:18 | 2024-07-25T10:37 | 2024-07-25T10 | 2024-07-25 | 2024-07 | 2024
published_after false Find all articles published after the specified date. Supported formats include: Y-m-d\TH:i:s | Y-m-d\TH:i | Y-m-d\TH | Y-m-d | Y-m | Y.
Examples: 2024-07-25T10:37:18 | 2024-07-25T10:37 | 2024-07-25T10 | 2024-07-25 | 2024-07 | 2024
published_on false Find all articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2024-07-25
limit false Specify the number of articles you want to return in the request. The maximum limit is based on your plan. The default limit is the maximum specified for your plan.
page false Use this to paginate through the result set. Default is 1. Note that the max result set can't exceed 20,000. For example if your limit is 50, the max page you can have is 400 (50 * 400 = 20,000).
Example: page=2

Response Objects

name description
meta > found The number of articles found for the request.
meta > returned The number of articles returned on the page. This is useful to determine the end of the result set as if this is lower than limit, there are no more articles after this page.
meta > limit The limit based on the limit parameter.
meta > page The page number based on the page parameter.
data > uuid The unique identifier for an article in our system. Store this and use it to find specific articles using our single article endpoint.
data > title The article title.
data > description The article meta description.
data > keywords The article meta keywords.
data > snippet The first 60 characters of the article body.
data > url The URL to the article.
data > image_url The URL to the article image.
data > language The language of the source.
data > published_at The datetime the article was published.
data > source The domain of the source.
data > categories Array of strings which the source is categorized as.
data > relevance_score Relevance score based on the article provided.

If no results are found, the data object will be empty.

Example Request

            
                GET https://api.thenewsapi.com/v1/news/similar/cc11e3ab-ced0-4a42-9146-e426505e2e67?api_token=YOUR_API_TOKEN&language=en&published_on=2020-12-01
            
        

Example Response

            
                
            {
               "meta": {
                  "found": 3571,
                  "returned": 3,
                  "limit": 3,
                  "page": 1
               },
               "data": [
                  {
                     "uuid": "df4ad427-a672-4c67-b6c6-6f81aa00e164",
                     "title": "Tesla stock jumps after announcement it will join S&P 500 in one go",
                     "description": "Tesla's stock price surged early Tuesday after the company b...",
                     "keywords": "Business, s&p 500, stocks, tesla",
                     "snippet": "Tesla’s stock price surged early Tuesday after the company...",
                     "url": "https://nypost.com/2020/12/01/tesla-stock-jumps-on-news-it-will-join-sp-500-in-one-shot/",
                     "image_url": "https://nypost.com/wp-content/uploads/sites/2/2020/12/tesla-52.jpg?quality=90&strip=all&w=1200",
                     "language": "en",
                     "published_at": "2020-12-01T14:35:46.000000Z",
                     "source": "nypost.com",
                     "categories": [
                        "business"
                     ],
                     "relevance_score": 153.61266
                  },
                  {
                     "uuid": "c9a23881-12dd-4005-8982-7b6552a2eb50",
                     "title": "Tesla To Join S&P 500 With Full Market Cap On December 21",
                     "description": "Tesla will be added to the S&P 500 index all at once at its ...",
                     "keywords": "Tesla, S&P500, EV, Automotive, Stocks, Investing",
                     "snippet": "Tesla (NASDAQ: TSLA) will be added to the S&P 500 index all ...",
                     "url": "https://oilprice.com/Latest-Energy-News/World-News/Tesla-To-Join-SP-500-With-Full-Market-Cap-On-December-21.html",
                     "image_url": "https://d32r1sh890xpii.cloudfront.net/news/718x300/2020-12-01_xwjdajwctl.jpg",
                     "language": "en",
                     "published_at": "2020-12-01T16:30:00.000000Z",
                     "source": "oilprice.com",
                     "categories": [
                        "general",
                        "business"
                     ],
                     "relevance_score": 146.92773
                  },
                  {
                     "uuid": "18afdb1c-7742-4016-bf8c-a2f114e11199",
                     "title": "Tesla to Enter S&P 500 at Full Weight in December",
                     "description": "The electric-vehicle maker will be added to the broad stock-...",
                     "keywords": "Motor Vehicles, Alternative Fuel Vehicles, Trusts Funds Financial Vehicles, Diversified Holding Companies, Automotive",
                     "snippet": "S&P Dow Jones Indices said it will add Tesla Inc.’s full w...",
                     "url": "https://www.wsj.com/articles/tesla-to-enter-s-p-500-at-full-weight-in-december-11606780897?mod=pls_whats_news_us_business_f",
                     "image_url": "https://images.wsj.net/im-265933/social",
                     "language": "en",
                     "published_at": "2020-12-01T00:01:00.000000Z",
                     "source": "online.wsj.com",
                     "categories": [
                        "business"
                     ],
                     "relevance_score": 128.22346
                  }
               ]
            }
        
            
        

News by UUID Available on: All plans

Endpoint

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

Use this endpoint to find specific articles by the UUID which is returned on our search endpoints. This is useful if you wish to store the UUID to return the article later.

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

All text data returned is UTF-8.

All dates are in UTC (GMT).

HTTP GET Parameters

name required description
api_token true Your API token which can be found on your account dashboard.

Response Objects

name description
uuid The unique identifier for an article in our system. Store this and use it to find specific articles using our single article endpoint.
title The article title.
description The article meta description.
keywords The article meta keywords.
snippet The first 60 characters of the article body.
url The URL to the article.
image_url The URL to the article image.
language The language of the source.
published_at The datetime the article was published.
source The domain of the source.
categories Array of strings which the source is categorized as.

If no results are found, a resource_not_found error will be returned.

Example Request

            
                GET https://api.thenewsapi.com/v1/news/uuid/147013d8-6c2c-4d50-8bad-eb3c8b7f5740?api_token=YOUR_API_TOKEN
            
        

Example Response

            
                
            {
                "uuid": "147013d8-6c2c-4d50-8bad-eb3c8b7f5740",
                "title": "These Are The Four American Companies Worth Over $1 Trillion Each – 24",
                "description": "America’s major market indexes set records in the early pa...",
                "keywords": "",
                "snippet": "These Are The Four American Companies Worth Over $1 Trillion...",
                "url": "https://247wallst.com/investing/2020/10/17/these-are-the-four-american-companies-worth-over-1-trillion-each/",
                "image_url": "https://247wallst.com/wp-content/uploads/2020/08/imageForEntry2-Qrj.jpg",
                "language": "en",
                "published_at": "2020-10-17T11:16:20.000000Z",
                "source": "247wallst.com",
                "categories": [
                    "business"
                ]
            }
        
            
        

Sources Available on: All plans

Endpoint

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

Use this endpoint to sources to use in your news API requests. Note that the limit is 50 for all requests.

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

All text data returned is UTF-8.

HTTP GET Parameters

name required description
categories false Comma separated list of categories to include
Example: business,tech
exclude_categories false Comma separated list of categories to exclude
language false Comma separated list of languages to include. Default is all.
Click here for a list of supported languages.
Examples: en,es (English + Spanish)
page false Use this to paginate through the result set. Default is 1.
Example: page=2

Response Objects

name description
meta > found The number of sources found for the request.
meta > returned The number of sources returned on the page.
meta > limit The limit is 50. This currently can not be changed.
meta > page The page number based on the page parameter.
data > source_id The unique ID of the source feed. Use this for the source_ids or exclude_source_ids parameters in the news endpoints. There may be many source_ids for each domain, therefore we would generally suggest using the domains filter instead the source_ids filter.
data > domain The domain of the source. You can use this for the domains or exclude_domains parameters in the news endpoints.
data > language The source language.
data > locale The source locale. Note that only select sources have locales.
data > categories Array of strings which the source is categorized as.

If no results are found, the data object will be empty.

Example Request

            
                GET https://api.thenewsapi.com/v1/news/sources?api_token=YOUR_API_TOKEN&language=en
            
        

Example Response

            
                
            {
                "meta": {
                    "found": 15453,
                    "returned": 50,
                    "limit": 50,
                    "page": 1
                },
                "data": [
                    {
                        "source_id": "arstechnica.com-1",
                        "domain": "arstechnica.com",
                        "language": "en",
                        "locale": null,
                        "categories": [
                            "tech"
                        ]
                    },
                    {
                        "source_id": "adweek.com-1",
                        "domain": "adweek.com",
                        "language": "en",
                        "locale": null,
                        "categories": [
                            "business"
                        ]
                    },
                    ...
        
            
        

Errors

Errors

If your request was unsuccessful, you will receive a JSON formatted error. Below you will find the potential errors you may encounter when using the API.

Errors

error code HTTP status description
malformed_parameters 400 Validation of parameters failed. The failed parameters are usually shown in the error message.
invalid_api_token 401 Invalid API token.
usage_limit_reached 402 Usage limit of your plan has been reached. Usage limit and remaining requests can be found on the X-UsageLimit-Limit header.
endpoint_access_restricted 403 Access to the endpoint is not available on your current subscription plan.
resource_not_found 404 Resource could not be found.
invalid_api_endpoint 404 API route does not exist.
rate_limit_reached 429 Too many requests in the past 60 seconds. Rate limit and remaining requests can be found on the X-RateLimit-Limit header.
server_error 500 A server error occured.
maintenance_mode 503 The service is currently under maintenance.

Example Error Response

            
                
            {
                "error": {
                    "code": "malformed_parameters",
                    "message": "The published_before parameter(s) are incorrectly formatted."
                }
            }
        
            
        

Examples

API Examples

Our endpoints are very useful for filtering to find only specific resources you need. Follow each example request below to see how you can build dynamic queries.

Example Request 1

This is a basic request which will return all articles which match the search term "usd" within the title or body of the article:

    
        GET https://api.thenewsapi.com/v1/news/all?api_token=YOUR_API_TOKEN&search=usd
    

Example Request 2

This will return all articles which match the search term "usd" OR "gbp":

    
        GET https://api.thenewsapi.com/v1/news/all?api_token=YOUR_API_TOKEN&search=usd%20%7C%20gbp
    

Example Request 3

This will return all articles which match the search term "usd" AND "gbp":

    
        GET https://api.thenewsapi.com/v1/news/all?api_token=YOUR_API_TOKEN&search=usd%20%2B%20gbp
    

Example Request 4

This will return all articles which match the search term "usd" AND "gbp" but removes any articles which mentions "cad":

    
        GET https://api.thenewsapi.com/v1/news/all?api_token=YOUR_API_TOKEN&search=usd%20%2B%20gbp%20-cad
    

Example Request 5

This will return all articles which match the search term "forex" AND "usd" OR "gbp" but removes any articles which mentions "cad":

    
        GET https://api.thenewsapi.com/v1/news/all?api_token=YOUR_API_TOKEN&search=forex%20%2B%20%28usd%20%7C%20gbp%29%20-cad
    

Example Request 6

This is the same as Example Request 5 but will also ensure the articles returned are in English and categorized by business or tech but not travel, and are published within the last week:

    
        GET https://api.thenewsapi.com/v1/news/all?api_token=YOUR_API_TOKEN&search=forex%20%2B%20%28usd%20%7C%20gbp%29%20-cad&language=en&categories=business%2Ctech&exclude_categories=travel&published_after=2024-07-18
    

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