Documentation

Sign up for free!

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

Sign up now

Getting Started

Introduction

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

To 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-09-15
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": "80b0c904-c13b-4a71-96d4-0562a938e645",
                "title": "Chelsea 1-0 Bournemouth (Sep 14, 2024) Game Analysis",
                "description": "Expert recap and game analysis of the Chelsea vs. AFC Bournemouth English Premier League game from September 14, 2024 on ESPN.",
                "keywords": "",
                "snippet": "Chelsea substitute Christopher Nkunku struck in the 86th minute to secure a 1-0 victory at Bournemouth in a game littered with a Premier League record 14 yellow...",
                "url": "https://www.espn.com/soccer/report/_/gameId/704310",
                "image_url": "https://a.espncdn.com/combiner/i?img=/i/espn/misc_logos/500/soccer.png",
                "language": "en",
                "published_at": "2024-09-15T00:20:58.000000Z",
                "source": "espn.com",
                "categories": [
                    "sports",
                    "general"
                ],
                "locale": "us",
                "similar": [
                    {
                        "uuid": "d11935e3-b317-404c-ac94-d5891680363e",
                        "title": "Nottm Forest 1-0 Liverpool (Sep 14, 2024) Game Analysis",
                        "description": "Expert recap and game analysis of the Nottingham Forest vs. Liverpool English Premier League game from September 14, 2024 on ESPN.",
                        "keywords": "",
                        "snippet": "Liverpool's Arne Slot explains why he is not distracted by the contract situations of his star players.\n\nA superb second-half goal from substitute Callum Hudson...",
                        "url": "https://www.espn.com/soccer/report/_/gameId/704314",
                        "image_url": "https://a.espncdn.com/combiner/i?img=/i/espn/misc_logos/500/soccer.png",
                        "language": "en",
                        "published_at": "2024-09-14T17:08:28.000000Z",
                        "source": "espn.com",
                        "categories": [
                            "sports",
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "96c3ae28-6de1-400e-8f4f-c10032edbfb9",
                        "title": "Leverkusen 4-1 Hoffenheim (Sep 14, 2024) Game Analysis",
                        "description": "Expert recap and game analysis of the Bayer Leverkusen vs. TSG Hoffenheim German Bundesliga game from September 14, 2024 on ESPN.",
                        "keywords": "",
                        "snippet": "Two goals from Victor Boniface help Bayer Leverkusen to a 4-1 victory over Hoffenheim.\n\nChampions Bayer Leverkusen cruised to a 4-1 victory at Hoffenheim on Sat...",
                        "url": "https://www.espn.com/soccer/report/_/gameId/711457",
                        "image_url": "https://a.espncdn.com/combiner/i?img=/i/espn/misc_logos/500/soccer.png",
                        "language": "en",
                        "published_at": "2024-09-14T20:47:24.000000Z",
                        "source": "espn.com",
                        "categories": [
                            "sports",
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "54d8b6ba-2a79-464e-a785-af737433377c",
                        "title": "Empoli 0-0 Juventus (Sep 14, 2024) Game Analysis",
                        "description": "Expert recap and game analysis of the Empoli vs. Juventus Italian Serie A game from September 14, 2024 on ESPN.",
                        "keywords": "",
                        "snippet": "Thiago Motta cut a frustrated figure as Juventus dropped points against Empoli. ISABELLA BONOTTO/AFP via Getty Images\n\nJuventus were held to a 0-0 Serie A draw ...",
                        "url": "https://www.espn.com/soccer/report/_/gameId/712146",
                        "image_url": "https://a.espncdn.com/combiner/i?img=/i/espn/misc_logos/500/soccer.png",
                        "language": "en",
                        "published_at": "2024-09-14T20:47:24.000000Z",
                        "source": "espn.com",
                        "categories": [
                            "sports",
                            "general"
                        ],
                        "locale": "us"
                    }
                ]
            },
            {
                "uuid": "98aeea9c-7e07-4363-b515-af290043b4a8",
                "title": "Bill Maher makes this bold 2024 prediction after Trump-Harris debate",
                "description": "HBO host Bill Maher predicted former President Trump will lose the upcoming election following his debate performance against Vice President Kamala Harris.",
                "keywords": "",
                "snippet": "\"Real Time\" host Bill Maher made a bold prediction about who will win the 2024 election following the first presidential debate between former President Trump a...",
                "url": "https://www.foxnews.com/media/bill-maher-makes-bold-2024-prediction-after-trump-harris-debate",
                "image_url": "https://static.foxnews.com/foxnews.com/content/uploads/2024/09/MaherDebate2.jpg",
                "language": "en",
                "published_at": "2024-09-14T17:33:26.000000Z",
                "source": "foxnews.com",
                "categories": [
                    "general",
                    "politics"
                ],
                "locale": "us",
                "similar": [
                    {
                        "uuid": "de56f91b-f423-4ae4-841d-279efe897179",
                        "title": "Following debate ‘win,’ CNN host admits that people still ‘don’t really know’ Harris’ policies",
                        "description": "CNN host Sara Sidner recently reported that new polling shows that voters are still confused as to what Vice President Kamala Harris' policies would be as president.",
                        "keywords": "",
                        "snippet": "CNN host Sara Sidner recently wondered what Vice President Kamala Harris needs to do to show people who she is, as some are still confused about her actual poli...",
                        "url": "https://www.foxnews.com/media/following-debate-win-cnns-sidner-admits-people-still-dont-know-harris-policies",
                        "image_url": "https://static.foxnews.com/foxnews.com/content/uploads/2024/09/Sara-Sidner-CNN.png",
                        "language": "en",
                        "published_at": "2024-09-14T14:05:58.000000Z",
                        "source": "foxnews.com",
                        "categories": [
                            "general",
                            "politics"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "4fa11ecf-f288-4576-8462-0b82019d07e2",
                        "title": "Trump makes half-hearted attempt to distance himself from Laura Loomer amid backlash",
                        "description": "Donald Trump made a feeble attempt to distance himself from Laura Loomer, saying she is not part of his campaign and that he disagrees with her \"statements.\"",
                        "keywords": "",
                        "snippet": "Donald Trump made a feeble attempt to fend off bipartisan outrage over his association this week with Laura Loomer, the far-right social media activist and fail...",
                        "url": "https://www.msnbc.com/top-stories/latest/trump-laura-loomer-9-11-conspiracy-theories-rcna171134",
                        "image_url": "https://media-cldnry.s-nbcnews.com/image/upload/t_nbcnews-fp-1200-630,f_auto,q_auto:best/rockcms/2024-09/240914-split-laura-loomer-donald-trump-ch-1018-e8d8a7.jpg",
                        "language": "en",
                        "published_at": "2024-09-14T17:01:03.000000Z",
                        "source": "msnbc.com",
                        "categories": [
                            "general",
                            "politics"
                        ],
                        "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-09-15T00:51:20 | 2024-09-15T00:51 | 2024-09-15T00 | 2024-09-15 | 2024-09 | 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-09-15T00:51:20 | 2024-09-15T00:51 | 2024-09-15T00 | 2024-09-15 | 2024-09 | 2024
published_on false Find all articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2024-09-15
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": 1104877,
        "returned": 10,
        "limit": 10,
        "page": 1
    },
    "data": [
        {
            "uuid": "68a7adc3-a3e6-4bfb-8ad1-d9eba795bc94",
            "title": "Miami vs. Philadelphia (Sep 14, 2024) Live Score",
            "description": "Live coverage of the Inter Miami CF vs. Philadelphia Union MLS game on ESPN, including live score, highlights and updated stats.",
            "keywords": "",
            "snippet": "EA Sports FC 25 ratings: How do Mbappé, Messi, Ronaldo score?\n\nEA Sports will launch FC 25 this month. Here's a look at which men's and women's players command...",
            "url": "https://www.espn.com/soccer/match/_/gameId/693006",
            "image_url": "https://a.espncdn.com/combiner/i?img=/i/espn/misc_logos/500/soccer.png",
            "language": "en",
            "published_at": "2024-09-15T00:38:44.000000Z",
            "source": "espn.com",
            "categories": [
                "sports",
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "80b0c904-c13b-4a71-96d4-0562a938e645",
            "title": "Chelsea 1-0 Bournemouth (Sep 14, 2024) Game Analysis",
            "description": "Expert recap and game analysis of the Chelsea vs. AFC Bournemouth English Premier League game from September 14, 2024 on ESPN.",
            "keywords": "",
            "snippet": "Chelsea substitute Christopher Nkunku struck in the 86th minute to secure a 1-0 victory at Bournemouth in a game littered with a Premier League record 14 yellow...",
            "url": "https://www.espn.com/soccer/report/_/gameId/704310",
            "image_url": "https://a.espncdn.com/combiner/i?img=/i/espn/misc_logos/500/soccer.png",
            "language": "en",
            "published_at": "2024-09-15T00:20:58.000000Z",
            "source": "espn.com",
            "categories": [
                "sports",
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "55f5c232-3304-4791-9c24-ce6b93de113c",
            "title": "Milan 4-0 Venezia (Sep 14, 2024) Game Analysis",
            "description": "Expert recap and game analysis of the AC Milan vs. Venezia Italian Serie A game from September 14, 2024 on ESPN.",
            "keywords": "",
            "snippet": "New AC Milan coach Paulo Fonseca got his first Serie A win in style, and it couldn't have come at a better time for the Rossoneri as they kickstarted their seas...",
            "url": "https://www.espn.com/soccer/report/_/gameId/712149",
            "image_url": "https://a.espncdn.com/combiner/i?img=/i/espn/misc_logos/500/soccer.png",
            "language": "en",
            "published_at": "2024-09-15T00:20:58.000000Z",
            "source": "espn.com",
            "categories": [
                "sports",
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "269ef32a-7695-4d8f-801d-bb9bdd3fe61d",
            "title": "Carlo Ancelotti hails Kylian Mbappé's best Real Madrid game",
            "description": "Carlo Ancelotti praised Kylian Mbappé's performance after the forward scored in Real Madrid's 2-0 win away at Real Sociedad on Saturday, saying Mbappé looked",
            "keywords": "",
            "snippet": "Kylian Mbappe scores his third goal in two games for Real Madrid as they extend their lead over Real Sociedad. (0:54)\n\nOpen Extended Reactions\n\nCarlo Ancelotti ...",
            "url": "https://www.espn.com/soccer/story/_/id/41261898/carlo-ancelotti-hails-kylian-mbappe-best-real-madrid-game",
            "image_url": "https://a1.espncdn.com/combiner/i?img=%2Fphoto%2F2024%2F0914%2Fr1386399_1296x729_16%2D9.jpg",
            "language": "en",
            "published_at": "2024-09-15T00:20:57.000000Z",
            "source": "espn.com",
            "categories": [
                "sports",
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "8250ff1d-d26a-4e39-955f-adaf6295c38f",
            "title": "How to watch Canelo vs. Berlanga: PPV prices and live stream info",
            "description": "Canelo Alvarez will defend his super middleweight titles against Edgar Berlanga tonight. We'll show you how to watch Canelo vs. Berlanga from anywhere.",
            "keywords": "",
            "snippet": "When you buy through our links, Business Insider may earn an affiliate commission. Learn more\n\nCanelo Alvarez will once again defend his super middleweight titl...",
            "url": "https://www.businessinsider.com/guides/streaming/how-to-watch-canelo-vs-berlanga-live-stream-2024",
            "image_url": "https://i.insider.com/66e498a8d17aa3c7b2b29b16?width=1200&format=jpeg",
            "language": "en",
            "published_at": "2024-09-15T00:00:01.000000Z",
            "source": "businessinsider.com",
            "categories": [
                "business",
                "tech"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "147405f4-ab5e-4a84-9275-51f17d0e9f3e",
            "title": "Apalachee High School football team makes surprise visit to Falcons practice one week after deadly shooting",
            "description": "The Apalachee High School football team visited the Atlanta Falcons on Friday. The student athletes made the special trip just over a week after a devastating s...",
            "keywords": "",
            "snippet": "Georgia's Apalachee High School continues to grapple with tragedy. But, the school's football team received a special surprise on Friday which many hope will he...",
            "url": "https://www.foxnews.com/sports/falcons-host-apalachee-high-school-football-team-days-after-shooting-left-four-dead",
            "image_url": "https://static.foxnews.com/foxnews.com/content/uploads/2024/09/Apalachee-High-School-Falcons.jpg.jpg",
            "language": "en",
            "published_at": "2024-09-14T23:44:50.000000Z",
            "source": "foxnews.com",
            "categories": [
                "general",
                "politics"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "525eff7d-4820-4946-b053-387bab6ee188",
            "title": "American activist killed by Israeli fire in West Bank is buried in Turkey",
            "description": "A Turkish-American activist who was killed by Israeli fire in the West Bank was laid to rest on Saturday in her hometown in Turkey with thousands lining the str...",
            "keywords": "",
            "snippet": "ISTANBUL, Turkey — A Turkish-American activist who was killed by Israeli fire in the West Bank was laid to rest on Saturday in her hometown in Turkey with tho...",
            "url": "https://www.nbcnews.com/news/world/american-activist-killed-israeli-fire-west-bank-buried-turkey-rcna171165",
            "image_url": "https://media-cldnry.s-nbcnews.com/image/upload/t_nbcnews-fp-1200-630,f_auto,q_auto:best/rockcms/2024-09/240914-aysenur-ezgi-eygi-wm-438p-3959e2.jpg",
            "language": "en",
            "published_at": "2024-09-14T23:42:33.000000Z",
            "source": "nbcnews.com",
            "categories": [
                "general",
                "politics"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "99f02b74-2486-42db-aa37-ae8956144b8f",
            "title": "Trump urges California GOP US Senate candidate Garvey to reach out over endorsement: ‘No chance’ without MAGA",
            "description": "Former President Trump said on Friday that California Republican U.S. Senate candidate Steve Garvey made a \"big mistake\" not reaching out to him for an endorsem...",
            "keywords": "",
            "snippet": "Former President Trump told reporters on Friday that California Republican U.S. Senate candidate Steve Garvey \"hasn’t reached out to MAGA\" after the president...",
            "url": "https://www.foxnews.com/politics/trump-urges-california-gop-us-senate-candidate-garvey-reach-out-over-endorsement-no-chance-without-maga",
            "image_url": "https://static.foxnews.com/foxnews.com/content/uploads/2024/09/TRUMP-STEVE-GARVEY-SPLIT.jpg",
            "language": "en",
            "published_at": "2024-09-14T23:40:39.000000Z",
            "source": "foxnews.com",
            "categories": [
                "general",
                "politics"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "235595fb-b5ba-45b0-8d58-6f9327f66545",
            "title": "JD Vance says it would be 'very hard' for Trump to win without North Carolina",
            "description": "GREENVILLE, N.C. — Sen. JD Vance, R-Ohio, said on Saturday that it would be “very hard” for the Trump campaign to win in November if it does not hold on t...",
            "keywords": "",
            "snippet": "Create your free profile or log in to save this article\n\nCreate your free profile or log in to save this article\n\nGREENVILLE, N.C. — Sen. JD Vance, R-Ohio, sa...",
            "url": "https://www.nbcnews.com/politics/2024-election/jd-vance-says-hard-trump-win-north-carolina-rcna171162",
            "image_url": "https://media-cldnry.s-nbcnews.com/image/upload/t_nbcnews-fp-1200-630,f_auto,q_auto:best/rockcms/2024-09/240914-jd-vance-north-carolina-wm-333p-2ffa17.jpg",
            "language": "en",
            "published_at": "2024-09-14T23:37:36.000000Z",
            "source": "nbcnews.com",
            "categories": [
                "general",
                "politics"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "2eea181f-76c4-45dd-8611-f432b3176b88",
            "title": "Demi Moore Reflects On ‘The Substance’ And The “Harsh Violence” That “We Do To Ourselves”",
            "description": "Demi Moore reflected on her experience filming 'The Substance' and the 'violence' women subject themselves to when conforming to beauty standards.",
            "keywords": "",
            "snippet": "Demi Moore reflected on her experience filming The Substance — which nabbed the Best Screenplay distinction at its Cannes premiere earlier this year — calli...",
            "url": "https://deadline.com/2024/09/demi-moore-the-substance-violence-beauty-standards-1236088155/",
            "image_url": "https://deadline.com/wp-content/uploads/2024/09/demi-moore-the-substance.jpg?w=1024",
            "language": "en",
            "published_at": "2024-09-14T23:31:36.000000Z",
            "source": "deadline.com",
            "categories": [
                "entertainment"
            ],
            "relevance_score": null,
            "locale": "us"
        }
    ]
}

All News Available on: All plans

Endpoint

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

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

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

All text data returned is UTF-8.

All dates are in UTC (GMT).

HTTP GET Parameters

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

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

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

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

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-09-15T00:51:20 | 2024-09-15T00:51 | 2024-09-15T00 | 2024-09-15 | 2024-09 | 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-09-15T00:51:20 | 2024-09-15T00:51 | 2024-09-15T00 | 2024-09-15 | 2024-09 | 2024
published_on false Find all articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2024-09-15
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": 49260834,
        "returned": 10,
        "limit": 10,
        "page": 1
    },
    "data": [
        {
            "uuid": "4a743c3d-b493-4c98-b13b-8103c384daa2",
            "title": "[현장핫피플] ''린가드 둘리 춤 갚아주자 생각했다''...'대전 메시' 김현욱, ''팬들에게 더 많은 즐거움을 선사하고 싶다''::스포탈코리아",
            "description": "[스포탈코리아=서울] 박윤서 기자= 린가드는 약속대로 둘리 춤을 보여줬다. 그러나 승리의 둘리 춤은 김현욱의 몫이었다....",
            "keywords": "[현장핫피플] ''린가드 둘리 춤 갚아주자 생각했다''...'대전 메시' 김현욱, ''팬들에게 더 많은 즐거움을 선사하고 싶다'', 스포츠, 축구",
            "snippet": "[스포탈코리아=서울] 박윤서 기자= 린가드는 약속대로 둘리 춤을 보여줬다. 그러나 승리의 둘리 춤은 김현욱의 몫이었다....",
            "url": "https://www.sportalkorea.com/news/view.php?gisa_uniq=2024091500230535&cp=fo",
            "image_url": "https://img.sportalkorea.com/service_img/2024/SK004_20240914_350801_1726329022.jpg",
            "language": "ko",
            "published_at": "2024-09-15T00:51:15.000000Z",
            "source": "sportalkorea.com",
            "categories": [
                "sports"
            ],
            "relevance_score": null
        },
        {
            "uuid": "f09d7dfd-f971-455d-83e9-e4c0168bcba6",
            "title": "ビリー・ジョエルの最新ライヴにロッド・スチュワートがゲスト参加",
            "description": "ビリー・ジョエルの最新ライヴにロッド・スチュワートがゲスト参加。「Stay With Me」を一緒に披露しています。映像あ?...",
            "keywords": "音楽, 洋楽, 邦楽, music, アニメ, 映画, 特撮, cd, dvd, Blu-ray",
            "snippet": "",
            "url": "https://amass.jp/177898/",
            "image_url": "https://amassing2.sakura.ne.jp/image/jacket/300/2024b/135594.jpg",
            "language": "ja",
            "published_at": "2024-09-15T00:49:00.000000Z",
            "source": "amass.jp",
            "categories": [
                "entertainment",
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "79e0a65b-ee21-4444-8c7f-1a5ffc6d47b6",
            "title": "No Rock in Rio, Lulu Santos faz o que se espera, ou seja, é impecável",
            "description": "Principais notícias do mundo dos famosos, BBB, A Fazenda, cinema, séries, música e novelas na TV. Saiba as fofocas, casais e separações.",
            "keywords": "",
            "snippet": "Com o dia ainda claro, Lulu Santos abriu o Palco Mundo no segundo dia do Rock In Rio instaurando uma celebração da vida, do futuro, da liberdade, do amor — ...",
            "url": "https://www.uol.com.br/splash/noticias/2024/09/14/no-rock-in-rio-lulu-santos-faz-o-que-se-espera-ou-seja-e-impecavel.htm",
            "image_url": "https://conteudo.imguol.com.br/c/entretenimento/e0/2024/09/14/14set2024---lulu-santos-se-apresenta-no-palco-mundo-na-segunda-noite-do-rock-in-rio-2024-1726345265222_v2_615x300.jpg",
            "language": "pt",
            "published_at": "2024-09-15T00:48:07.000000Z",
            "source": "uol.com.br",
            "categories": [
                "tech",
                "science"
            ],
            "relevance_score": null
        },
        {
            "uuid": "bf975406-ea8f-454c-b104-f947d9fae96c",
            "title": "0h Mais de 8 mil colocados na 2ªfase de acesso ao Ensino Superior",
            "description": "RTP Notícias - Descrição",
            "keywords": "RTP, Notícias, RTP Notícias",
            "snippet": "0h Mais de 8 mil colocados na 2ªfase de acesso ao Ensino Superior",
            "url": "https://www.rtp.pt/noticias/noticiario-antena1/0h-mais-de-8-mil-colocados-na-2afase-de-acesso-ao-ensino-superior_a1_1599784",
            "image_url": "https://cdn-images.rtp.pt/noticias/images/img_article_a1.jpg?w=860&q=90&auto=format",
            "language": "pt",
            "published_at": "2024-09-15T00:48:03.000000Z",
            "source": "rtp.pt",
            "categories": [
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "73743a9e-ef6e-4921-bd18-f7880ef01dcb",
            "title": "Greve para aeroporto na Argentina e brasileiros reclamam: 'Estragaram a viagem'",
            "description": "Veja as principais notícias e manchetes do dia no Brasil e no Mundo. Leia textos e assista a vídeos de Política, Cotidiano, Crimes e mais.",
            "keywords": "",
            "snippet": "\"Vamos ter de ficar aqui, em Buenos Aires, no mínimo, até dia 18, esperando a disponibilidade de um voo. E teremos de pagar hospedagem e refeições do nosso ...",
            "url": "https://noticias.uol.com.br/ultimas-noticias/rfi/2024/09/14/brasileiros-sao-os-estrangeiros-mais-afetados-por-greve-aeronautica-na-argentina.htm",
            "image_url": "https://conteudo.imguol.com.br/c/noticias/f7/2024/09/14/uma-passageira-presa-usa-seu-telefone-enquanto-esta-sentada-ao-lado-de-um-painel-eletronico-anunciando-voos-cancelados-devido-a-uma-greve-de-sindicatos-da-aviacao-no-aeroporto-aeroparque-jorge-newbery-em-1726322285023_v2_615x300.jpg",
            "language": "pt",
            "published_at": "2024-09-15T00:48:02.000000Z",
            "source": "uol.com.br",
            "categories": [
                "tech",
                "science"
            ],
            "relevance_score": null
        },
        {
            "uuid": "303e47b7-5aa8-4b43-9f02-bacab0b499bf",
            "title": "Como fãs fazem 'força-tarefa' e conseguem driblar o calor no Rock in Rio",
            "description": "Os dois primeiros dias de Rock in Rio foram marcados por temperaturas que superaram os 35ºC e baixa umidade relativa do ar",
            "keywords": "",
            "snippet": "A intenção é ficar até o final. Chegamos na abertura, às 14h. Trouxe cinco garrafas para cada um, 15 no total. O leque virou uma ferramenta essencial, pegu...",
            "url": "https://www.uol.com.br/toca/noticias/2024/09/14/como-fas-fazem-forca-tarefa-e-conseguem-driblar-o-calor-no-rock-in-rio.htm",
            "image_url": "https://conteudo.imguol.com.br/c/entretenimento/58/2024/09/14/familia-arruda-no-rock-in-rio-1726348201948_v2_615x300.jpg",
            "language": "pt",
            "published_at": "2024-09-15T00:47:44.000000Z",
            "source": "uol.com.br",
            "categories": [
                "tech",
                "science"
            ],
            "relevance_score": null
        },
        {
            "uuid": "70f7f6a4-fff5-465f-aece-59c143c787a7",
            "title": "Lakers, Christian Koloko Agree To Contract",
            "description": "Lakers Christian Koloko Agree To Contract - RealGM Wiretap",
            "keywords": "Lakers Christian Koloko Agree To Contract, RealGM Wiretap",
            "snippet": "The Los Angeles Lakers and center Christian Koloko have agreed to a contract. When Koloko receives clearance from the NBA's Fitness to Play panel, he'll sign hi...",
            "url": "https://basketball.realgm.com/wiretap/277262/Lakers-Christian-Koloko-Agree-To-Contract",
            "image_url": "https://basketball.realgm.com/images/nba/4.2/wiretap/photos/2006/Koloko_Christian_tor_230109.jpg",
            "language": "en",
            "published_at": "2024-09-15T00:47:28.000000Z",
            "source": "basketball.realgm.com",
            "categories": [
                "sports"
            ],
            "relevance_score": null
        },
        {
            "uuid": "e867cd61-0afb-461a-a00d-db978a921f6c",
            "title": "Wake the Giant Music Festival 2024",
            "description": "The Wake the Giant Music Festival is a homecoming for Indigenous students who move to Thunder Bay, Ont., from northern communities to complete high school. Here...",
            "keywords": "",
            "snippet": "Wake the Giant Music Festival 2024\n\nThe Wake the Giant Music Festival is a homecoming for Indigenous students who move to Thunder Bay, Ont., from northern commu...",
            "url": "https://www.cbc.ca/news/canada/thunder-bay/wake-the-giant-music-festival-2024-1.7323867?cmp=rss",
            "image_url": "https://i.cbc.ca/1.7323877.1726356656!/fileImage/httpImage/image.JPG_gen/derivatives/16x9_620/jingle-dress-dancers.JPG",
            "language": "en",
            "published_at": "2024-09-15T00:45:09.000000Z",
            "source": "cbc.ca",
            "categories": [
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "357be3e4-a2b6-42ff-94e9-f592fa6b0945",
            "title": "得宝手帕纸_Tempo 得宝 手帕纸7张12包（香味任选）多少钱-什么值得买",
            "description": "Tempo 得宝 手帕纸7张12包（香味任选）3元什么值得买甄选出天猫超市优惠促销商品,包括Tempo/得宝报价、多少钱等信息,认真...",
            "keywords": "天猫超市, Tempo/得宝多少钱",
            "snippet": "",
            "url": "https://www.smzdm.com/p/125624309/",
            "image_url": "https://qny.smzdm.com/202106/24/60d3ed45e31701111.jpg_d250.jpg",
            "language": "zh",
            "published_at": "2024-09-15T00:44:11.000000Z",
            "source": "smzdm.com",
            "categories": [],
            "relevance_score": null
        },
        {
            "uuid": "72b1c405-13c4-451d-a2c0-70ce9039c2b1",
            "title": "Jon Jones vs. Stipe Miocic heavyweight bout set for UFC 309 in New York",
            "description": "After months of waiting, fight fans can breathe a sigh of relief as Jon Jones vs. Stipe Miocic finally has a set date.",
            "keywords": "",
            "snippet": "Sign in to Sportsnet\n\nSign In Sign Up\n\nFirst Name {* traditionalRegistration_firstName *} {* traditionalRegistration_firstName *} Last Name {* traditionalRegist...",
            "url": "https://www.sportsnet.ca/ufc/article/jon-jones-vs-stipe-miocic-heavyweight-bout-set-for-ufc-309-in-new-york/",
            "image_url": "https://www.sportsnet.ca/wp-content/uploads/2024/04/jones_jon1280-1040x572.jpg",
            "language": "en",
            "published_at": "2024-09-15T00:43:11.000000Z",
            "source": "sportsnet.ca",
            "categories": [
                "sports"
            ],
            "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-09-15T00:51:20 | 2024-09-15T00:51 | 2024-09-15T00 | 2024-09-15 | 2024-09 | 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-09-15T00:51:20 | 2024-09-15T00:51 | 2024-09-15T00 | 2024-09-15 | 2024-09 | 2024
published_on false Find all articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2024-09-15
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-09-08

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