Getting Started

Introduction

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

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

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

Authentication

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

API Endpoints

Headlines Available on: Standard plan and above

Endpoint

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

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

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

All text data returned is UTF-8.

All dates are in UTC (GMT).

HTTP GET Parameters

name required description
api_token true Your API token which can be found on your account dashboard.
locale false Comma separated list of country codes to include in the result set. Default is countries. Click here for a list of supported countries.
Example: us,ca (US + Canada).
domains false Comma separated list of domains to include. List of domains can be obtained through our Sources endpoint, found further down this page.
exclude_domains false Comma separated list of domains to exclude
source_ids false Comma separated list of source_ids to include. List of source_ids can be obtained through our Sources endpoint, found further down this page.
exclude_source_ids false Comma separated list of source_ids to exclude.
language false Comma separated list of languages to include. Default is all.
Click here for a list of supported languages.
Examples: en,es (English + Spanish)
published_on false Find headlines for articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2022-12-10
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": "4e2970e1-8472-4045-adf7-711fc2a65b4d",
                "title": "American soccer journalist Grant Wahl dies at 48 in Qatar",
                "description": "Grant Wahl, a prominent U.S. soccer writer, died early Saturday while covering the World Cup match between Argentina and the Netherlands.",
                "keywords": "",
                "snippet": "LUSAIL, Qatar -- Grant Wahl, one of the most well-known soccer writers in the United States, died early Saturday while covering the World Cup match between Arge...",
                "url": "https://www.espn.com/espn/story/_/id/35221443/american-soccer-journalist-grant-wahl-dies-48-qatar",
                "image_url": "https://a.espncdn.com/combiner/i?img=%2Fphoto%2F2022%2F1210%2Fr1104732_400x400_1%2D1.jpg",
                "language": "en",
                "published_at": "2022-12-10T03:00:55.000000Z",
                "source": "espn.com",
                "categories": [
                    "sports",
                    "general"
                ],
                "locale": "us",
                "similar": [
                    {
                        "uuid": "edcafe41-2a49-4292-aff3-1fe84b9f0a75",
                        "title": "U.S. soccer journalist Grant Wahl dies while covering World Cup in Qatar",
                        "description": "Grant Wahl, a United States soccer journalist, died in Qatar while covering the World Cup, the U.S. Soccer Federation said Friday night.",
                        "keywords": "",
                        "snippet": "Grant Wahl, a United States soccer journalist, died in Qatar while covering the World Cup, the U.S. Soccer Federation said Friday night.\n\nGrant Wahl in 2013. Er...",
                        "url": "https://www.nbcnews.com/news/sports/us-soccer-journalist-dies-covering-world-cup-qatar-rcna61097",
                        "image_url": "https://media-cldnry.s-nbcnews.com/image/upload/t_nbcnews-fp-1200-630,f_auto,q_auto:best/rockcms/2022-12/221209-Grant-Wahl-2014-se-954p-e8149b.jpg",
                        "language": "en",
                        "published_at": "2022-12-10T03:02:28.000000Z",
                        "source": "nbcnews.com",
                        "categories": [
                            "general",
                            "politics"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "aea207fa-b759-4311-a632-be724e568225",
                        "title": "Longtime soccer sportswriter Grant Wahl has died covering the World Cup in Qatar",
                        "description": "Grant Wahl was influential in the soccer world. He was able to break down the most intricate of plays and relate to hardcore and casual fans alike.",
                        "keywords": "",
                        "snippet": "Longtime soccer sportswriter Grant Wahl has died covering the World Cup in Qatar\n\nEnlarge this image toggle caption Michael Loccisano/Getty Images Michael Locci...",
                        "url": "https://www.npr.org/2022/12/09/1142054844/grant-wahl-soccer-writer-dies-qatar-world-cup",
                        "image_url": "https://media.npr.org/assets/img/2022/12/09/gettyimages-483445061_wide-0b3a317c68d28725dad5336052e8a23ba91b6d1a-s1400-c100.jpg",
                        "language": "en",
                        "published_at": "2022-12-10T03:15:22.000000Z",
                        "source": "npr.org",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "232b09f0-10c0-4bef-9d66-77d03ee5e44d",
                        "title": "Grant Wahl, soccer journalist, dies at 48 in Qatar while covering World Cup",
                        "description": "Prominent soccer journalist Grant Wahl died while covering the\\u00a0World Cup in Qatar, just days after his 48th birthday.",
                        "keywords": "",
                        "snippet": "Grant Wahl, soccer journalist, dies at 48 in Qatar while covering World Cup\n\nShow Caption Hide Caption 2022 World Cup: Should this even be taking place in Qatar...",
                        "url": "https://www.usatoday.com/story/sports/media/2022/12/09/grant-wahl-soccer-journalist-dies-qatar-world-cup/10869014002/",
                        "image_url": "https://www.gannett-cdn.com/presto/2022/12/10/USAT/ac0261a7-4e29-4f1a-8369-9a0d5e6ef00c-worldcup-soccer-ball.jpg?auto=webp&crop=843,474,x2660,y2153&format=pjpg&width=1200",
                        "language": "en",
                        "published_at": "2022-12-10T02:58:33.000000Z",
                        "source": "usatoday.com",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "0eb9aa83-3bb1-427b-9de2-92e573e2136a",
                        "title": "American soccer journalist Grant Wahl dies at 48 in Qatar",
                        "description": "Grant Wahl, a prominent U.S. soccer writer, died early Saturday while covering the World Cup match between Argentina and the Netherlands.",
                        "keywords": "",
                        "snippet": "LUSAIL, Qatar -- Grant Wahl, one of the most well-known soccer writers in the United States, died early Saturday while covering the World Cup match between Arge...",
                        "url": "https://www.espn.com/espn/story/_/id/35221443/american-soccer-journalist-grant-wahl-dies-49-qatar",
                        "image_url": "https://a.espncdn.com/combiner/i?img=%2Fphoto%2F2022%2F1210%2Fr1104732_400x400_1%2D1.jpg",
                        "language": "en",
                        "published_at": "2022-12-10T03:37:32.000000Z",
                        "source": "espn.com",
                        "categories": [
                            "sports",
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "4718bc4b-5b10-4b7c-aefe-349f5fb3f769",
                        "title": "Prominent U.S. soccer journalist dies while covering World Cup",
                        "description": "The State Department is engaged with senior Qatari officials over Grant Wahl's death.",
                        "keywords": "",
                        "snippet": "“I am so thankful for the support of my husband @GrantWahl‘s soccer family & of so many friends who’ve reached out tonight. I’m in complete shock,” Ce...",
                        "url": "https://www.politico.com/news/2022/12/09/u-s-soccer-journalist-dies-world-cup-grant-wahl-00073361",
                        "image_url": "https://static.politico.com/b9/1f/27de5fd3461584e47b24ea5a20cd/wahl.jpg",
                        "language": "en",
                        "published_at": "2022-12-10T03:27:54.000000Z",
                        "source": "politico.com",
                        "categories": [
                            "politics",
                            "general"
                        ],
                        "locale": "us"
                    }
                ]
            },
            {
                "uuid": "5dbc7f1f-13ad-46bc-88d6-8d984c8431aa",
                "title": "Judge Denies DOJ Request to Hold Donald Trump in Contempt",
                "description": "A federal judge denied the DOJ’s request to hold Donald Trump in contempt for allegedly failing to comply with a grand jury subpoena.",
                "keywords": "",
                "snippet": "A federal judge on Friday denied the U.S. Department of Justice’s (DOJ) request to hold former President Donald Trump in contempt for allegedly failing to com...",
                "url": "https://www.breitbart.com/politics/2022/12/09/judge-denies-department-justice-request-hold-donald-trump-contempt/",
                "image_url": "https://media.breitbart.com/media/2022/08/mar_a_lago2-640x335.jpg",
                "language": "en",
                "published_at": "2022-12-09T23:55:06.000000Z",
                "source": "breitbart.com",
                "categories": [
                    "general",
                    "politics"
                ],
                "locale": "us",
                "similar": [
                    {
                        "uuid": "5eb75c5f-c11c-44d4-8646-4ff5dcc9df5e",
                        "title": "Legal experts: Trump attorneys may throw him under the bus after DOJ moves to hold them in contempt",
                        "description": "The Justice Department is asking a federal judge to hold former President Donald Trump's legal team in contempt of court for failing to comply with a subpoena issued this summer ordering him to return all classified documents in his possession, sources told The Washington Post.U.S. District Court Ju...",
                        "keywords": "",
                        "snippet": "The Justice Department is asking a federal judge to hold former President Donald Trump's legal team in contempt of court for failing to comply with a subpoena i...",
                        "url": "https://www.alternet.org/the-right-wing/trump-doj-2658944570/",
                        "image_url": "https://www.alternet.org/media-library/image.png?id=27995730&width=1200&height=600&coordinates=0%2C4%2C0%2C4",
                        "language": "en",
                        "published_at": "2022-12-09T18:22:04.000000Z",
                        "source": "alternet.org",
                        "categories": [
                            "general",
                            "politics"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "aa8df8dc-c940-4cf0-a1e9-93d7e8833477",
                        "title": "Justice Department urges judge to hold Trump’s legal team in contempt over Mar-a-Lago case",
                        "description": "Federal prosecutors urged a judge in a closed-door hearing Friday to hold Donald Trump’s legal team in contempt of court for failing to fully turn over all...",
                        "keywords": "article_normal, N/A, Regulation/Government Policy, Corporate/Industrial News, Political/General News, Crime/Legal Action, Political Appointments/Terminations, Politics/International Relations, Domestic Politics, Government Bodies (Discontinued from 10th January 2023), Executive Branch (Discontinued from 10th January 2023), Justice Department (Discontinued from 10th January 2023), Content Types, Factiva Filters, C&E Industry News Filter, regulation, government policy, corporate, industrial news, political, general news, crime, legal action, political appointments, terminations, politics, international relations, domestic politics, government bodies (discontinued from 10th january 2023), executive branch (discontinued from 10th january 2023), justice department (discontinued from 10th january 2023), content types, factiva filters, c&e industry news filter, n, a",
                        "snippet": "WASHINGTON — Federal prosecutors urged a judge in a closed-door hearing Friday to hold Donald Trump’s legal team in contempt of court for failing to fully t...",
                        "url": "https://www.marketwatch.com/story/justice-department-urges-judge-to-hold-trumps-legal-team-in-contempt-over-mar-a-lago-case-11670621735",
                        "image_url": "https://images.mktw.net/im-681407/social",
                        "language": "en",
                        "published_at": "2022-12-09T21:35:00.000000Z",
                        "source": "marketwatch.com",
                        "categories": [
                            "business",
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "7fa09b1d-49ee-4fbb-9ef8-4cee75eb1d74",
                        "title": "Judge declines DOJ request to hold Trump team in contempt over classified documents: Sources",
                        "description": "A federal judge has declined a DOJ request to hold Trump's team in contempt over classified documents.",
                        "keywords": "",
                        "snippet": "The judge urged the DOJ and Trump's team to resolve the dispute themselves.\n\nA federal judge in Washington declined to hold Trump or his legal team in contempt ...",
                        "url": "https://abcnews.go.com/Politics/judge-declines-doj-request-hold-trump-team-contempt/story?id=94809481",
                        "image_url": "https://s.abcnews.com/images/Politics/fbi-mar-a-lago-search-trump-affadavit-02-ap-llr-220824_1661370798455_hpMain_16x9_992.jpg",
                        "language": "en",
                        "published_at": "2022-12-09T21:44:06.000000Z",
                        "source": "abcnews.go.com",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "34436fad-8e70-4ff3-ab5d-a545d2a7d1fb",
                        "title": "Judge rejects DOJ bid to hold Trump team in contempt over classified docs: reports",
                        "description": "A federal judge declined a request to hold members of former President Donald Trump’s legal team or the ex-president himself in contempt of court for not turning over classified documents from his White House tenure.",
                        "keywords": "News, donald trump, justice department, law, mar-a-lago, trump fbi raid, white house",
                        "snippet": "A federal judge on Friday declined a request from the Justice Department to hold members of former President Donald Trump’s legal team or the ex-president him...",
                        "url": "https://nypost.com/2022/12/09/judge-rejects-doj-bid-to-hold-trump-team-in-contempt-over-classified-docs/",
                        "image_url": "https://nypost.com/wp-content/uploads/sites/2/2022/12/trump-doj-no-contempt-index.jpg?quality=75&strip=all&w=1024",
                        "language": "en",
                        "published_at": "2022-12-09T23:26:59.000000Z",
                        "source": "nypost.com",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "8065ad24-bd97-4284-9c25-060fbc80545a",
                        "title": "Trump contempt judge rebuked by DOJ vet as Feds ramp up Mar-A-Lago pressure",
                        "description": "A federal judge rejects the DOJ request to hold Trump in contempt over the Mar-a-Lago classified documents probe. The contempt hearing reveals an aggressive approach from the new special counsel Jack Smith. It comes after at least two more classified documents were found in a Trump storage facility and turned over to the DOJ. Former federal prosecutor John Flannery joins MSNBC Chief Legal Correspondent Ari Melber on the judge's ruling saying the idea that no one is above the law and the subject doesn't matter is now",
                        "keywords": "",
                        "snippet": "A federal judge rejects the DOJ request to hold Trump in contempt over the Mar-a-Lago classified documents probe. The contempt hearing reveals an aggressive app...",
                        "url": "https://www.msnbc.com/the-beat-with-ari/watch/trump-contempt-judge-rebuked-by-doj-vet-as-feds-ramp-up-mar-a-lago-pressure-156884549887",
                        "image_url": "https://media-cldnry.s-nbcnews.com/image/upload/t_nbcnews-fp-1200-630,f_auto,q_auto:best/mpx/2704722219/2022_12/1670632252820_n_ari_contempt_221209_1920x1080-nugp9z.jpg",
                        "language": "en",
                        "published_at": "2022-12-10T00:32:04.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 countries. Click here for a list of supported countries.
Example: us,ca (US + Canada).
categories false Comma separated list of categories to include.
Supported categories: general | science | sports | business | health | entertainment | tech | politics | food | travel
Example: business,tech
exclude_categories false Comma separated list of categories to exclude.
domains false Comma separated list of domains to include. List of domains can be obtained through our Sources endpoint, found further down this page.
exclude_domains false Comma separated list of domains to exclude
source_ids false Comma separated list of source_ids to include. List of source_ids can be obtained through our Sources endpoint, found further down this page.
exclude_source_ids false Comma separated list of source_ids to exclude.
language false Comma separated list of languages to include. Default is all.
Click here for a list of supported languages.
Examples: en,es (English + Spanish)
published_before false Find all articles published before the specified date. Supported formats include: Y-m-d\TH:i:s | Y-m-d\TH:i | Y-m-d\TH | Y-m-d | Y-m | Y.
Examples: 2022-12-10T06:10:56 | 2022-12-10T06:10 | 2022-12-10T06 | 2022-12-10 | 2022-12 | 2022
published_after false Find all articles published after the specified date. Supported formats include: Y-m-d\TH:i:s | Y-m-d\TH:i | Y-m-d\TH | Y-m-d | Y-m | Y.
Examples: 2022-12-10T06:10:56 | 2022-12-10T06:10 | 2022-12-10T06 | 2022-12-10 | 2022-12 | 2022
published_on false Find all articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2022-12-10
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": 488677,
        "returned": 10,
        "limit": 10,
        "page": 1
    },
    "data": [
        {
            "uuid": "c52f660f-c277-4a8d-a421-70d0c4474b51",
            "title": "Global growth forecast slashed",
            "description": "Fitch Ratings has lowered global GDP projections for next year, citing soaring inflation",
            "keywords": "",
            "snippet": "The world economy is expected to grow in 2023 by less than previously expected, says Fitch Ratings\n\nInternational agency Fitch Ratings said on Tuesday it has on...",
            "url": "https://www.rt.com/business/567752-global-growth-forecast-slashed/",
            "image_url": "https://mf.b37mrtl.ru/files/2022.12/article/638f48f685f5407d166f2d3c.jpg",
            "language": "en",
            "published_at": "2022-12-10T05:56:40.000000Z",
            "source": "rt.com",
            "categories": [
                "general",
                "politics"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "761e3da9-b7bc-430f-bb45-4955fa9f0791",
            "title": "Kari Lake sues Arizona’s largest county, seeking to overturn her defeat",
            "description": "Kari Lake, the losing Republican candidate for governor of Arizona, filed a lawsuit Friday contesting the results of an election that was certified by the state...",
            "keywords": "",
            "snippet": "A former news anchor, Lake centered her candidacy on false conspiratorial claims that the 2020 presidential election had been stolen from Donald Trump, who had ...",
            "url": "https://www.bostonglobe.com/2022/12/10/nation/kari-lake-sues-arizonas-largest-county-seeking-overturn-her-defeat/?camp=bg:brief:rss:feedly&rss_id=feedly_rss_brief",
            "image_url": "https://bostonglobe-prod.cdn.arcpublishing.com/resizer/3WuxEctrQY-4oDkwbpMPn7j8KGo=/506x0/cloudfront-us-east-1.images.arcpublishing.com/bostonglobe/2TQCB2G762GY2BGHRLL5XYPOUI.jpg",
            "language": "en",
            "published_at": "2022-12-10T05:46:54.000000Z",
            "source": "bostonglobe.com",
            "categories": [
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "3b015a96-911f-41a8-9135-5335448ce7f2",
            "title": "Peru’s ex-president faced bigotry for impoverished past",
            "description": "LIMA, Peru (AP) — When Pedro Castillo won Peru’s presidency last year, it was celebrated as a victory by the country’s poor — the peasants and Indigenou...",
            "keywords": "Latin America, AP Top News, World News, Peru, Discrimination, Peru government, Government and politics, Pedro Castillo, Racism, Indigenous people",
            "snippet": "FILE - Free Peru party presidential candidate Pedro Castillo, wearing a hat and poncho, talks to neighbors in Chugur, in the Andes of Peru, April 15, 2021. When...",
            "url": "https://apnews.com/article/latin-america-peru-discrimination-government-and-politics-33f5b1ab4358a3a7a89014f3a817800b",
            "image_url": "https://storage.googleapis.com/afs-prod/media/f8bafacb308e44318ff5720bf2d30e5f/3000.webp",
            "language": "en",
            "published_at": "2022-12-10T05:23:04.000000Z",
            "source": "apnews.com",
            "categories": [
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "858305ae-ff0f-4c96-a8c0-66d2d10ddc1e",
            "title": "Rural voters ‘in the trenches’ on climate, leery of Biden",
            "description": "NEW YORK (AP) — Drought in California meant Raquel Krach, a rice farmer and graduate student in the Sacramento Valley, planted very little. Using groundwater,...",
            "keywords": "2022 Midterm elections, Science, Politics, AP Top News, Droughts, U.S. Department of Agriculture, U.S. Republican Party, Climate and environment, Government and politics",
            "snippet": "FILE - People walk to Tower Rock, an attraction normally surrounded by the Mississippi River and only accessible by boat, Oct. 19, 2022, in Perry County, Mo. Fo...",
            "url": "https://apnews.com/article/2022-midterm-elections-science-us-department-of-agriculture-climate-and-environment-government-politics-c3b2d4e7b8dbe9891e8a1cf37030fe04",
            "image_url": "https://storage.googleapis.com/afs-prod/media/1d044b5d02c6404fab2a96bf965ce98b/3000.webp",
            "language": "en",
            "published_at": "2022-12-10T05:23:04.000000Z",
            "source": "apnews.com",
            "categories": [
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "5b34e5e6-dac1-4489-8e97-95ae7b0677db",
            "title": "Sinema party switch highlights 2024 obstacles for Democrats",
            "description": "PHOENIX (AP) — Less than three days after Democrats celebrated victory  in the final Senate contest of the 2022 midterms, the challenges facing the party head...",
            "keywords": "2022 Midterm elections, Politics, AP Top News, Elections, Arizona, Kyrsten Sinema, U.S. Republican Party, United States Senate, u.s. democratic party, United States government, Government and politics",
            "snippet": "FILE - Sen. Kyrsten Sinema, D-Ariz., arrives for a meeting of the Senate Homeland Security Committee at the Capitol in Washington, Aug. 3, 2022. The decision by...",
            "url": "https://apnews.com/article/2022-midterm-elections-politics-arizona-kyrsten-sinema-us-republican-party-074c53a0ed0be3baaa80eeaefe21f3f6",
            "image_url": "https://storage.googleapis.com/afs-prod/media/8f87003149bb4fc7a6726e2922851899/3000.webp",
            "language": "en",
            "published_at": "2022-12-10T05:23:04.000000Z",
            "source": "apnews.com",
            "categories": [
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "4f9c61d9-caf0-49b7-abdb-3811cd467b38",
            "title": "Kari Lake challenges her defeat in Arizona governor’s race",
            "description": "Kari Lake, the Republican defeated in Arizona governor’s race, is formally challenging her loss to Democrat Katie Hobbs, asking a court to throw out certified...",
            "keywords": "Election 2022, Arizona",
            "snippet": "Lake has refused to acknowledge that she lost to Hobbs by more than 17,000 votes.\n\nThe lawsuit filed late Friday by Lake centers on long lines and other difficu...",
            "url": "https://www.bostonglobe.com/2022/12/10/nation/kari-lake-challenges-her-defeat-arizona-governors-race/?camp=bg:brief:rss:feedly&rss_id=feedly_rss_brief",
            "image_url": "https://bostonglobe-prod.cdn.arcpublishing.com/resizer/eF1YTuKS7T_-DPUC4yLQMAV4Wx0=/506x0/cloudfront-us-east-1.images.arcpublishing.com/bostonglobe/7MGOKSWPQV6CYD45ATFUQGS5FQ.jpg",
            "language": "en",
            "published_at": "2022-12-10T05:22:16.000000Z",
            "source": "bostonglobe.com",
            "categories": [
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "bda024fe-adc1-492c-beb3-c08e517ea868",
            "title": "Coyotes take advantage in closing seconds to beat the Bruins",
            "description": "Lawson Crouse capitalized on some confusion over a non-icing call to score the winning goal with 14 seconds remaining in regulation.",
            "keywords": "",
            "snippet": "It appeared the two sides were headed to overtime when the Coyotes struck for the winner with 13.5 seconds to go, after the Bruins anticipated an icing call tha...",
            "url": "https://www.bostonglobe.com/2022/12/10/sports/coyotes-take-advantage-closing-seconds-beat-bruins/?camp=bg:brief:rss:feedly&rss_id=feedly_rss_brief",
            "image_url": "https://bostonglobe-prod.cdn.arcpublishing.com/resizer/gFcEgyI_Qv9Yqvi2LSQT-t6I870=/506x0/cloudfront-us-east-1.images.arcpublishing.com/bostonglobe/54TRAOZTJGFB2VBBRBOUBJNUZ4.jpg",
            "language": "en",
            "published_at": "2022-12-10T05:13:14.000000Z",
            "source": "bostonglobe.com",
            "categories": [
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "d822c55f-c6cd-4d76-8454-706dcb6fd681",
            "title": "Twitter execs vowed to ‘hit’ conservative accounts ‘hard’ but were hands-off with pro-Biden tweets",
            "description": "Twitter executives bent over backwards to try to suppress tweets from high-profile conservatives leading up to the 2020 election – but found ways to justify k...",
            "keywords": "News, 2020 presidential election, censorship, donald trump, elon musk, twitter",
            "snippet": "Twitter executives bent over backwards to try to suppress tweets from high-profile conservatives leading up to the 2020 election – but found ways to justify k...",
            "url": "https://nypost.com/2022/12/10/twitter-execs-vowed-to-hit-conservative-accounts-hard-but-were-hands-off-with-pro-biden-tweets/",
            "image_url": "https://nypost.com/wp-content/uploads/sites/2/2022/12/twitter-execs-comp-1.jpg?quality=75&strip=all&w=1024",
            "language": "en",
            "published_at": "2022-12-10T05:09:50.000000Z",
            "source": "nypost.com",
            "categories": [
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "c873050f-94a8-45d8-b38f-c0d6e7fcaf64",
            "title": "Today in History",
            "description": "Today is Saturday, Dec. 10, the 344th day of 2022. There are 21 days left in the year.",
            "keywords": "Today in History",
            "snippet": "In 1817, Mississippi was admitted as the 20th state of the Union.\n\nBirthdays: Actor Fionnula Flanagan is 81. Actor-singer Gloria Loring is 76. Former Illinois G...",
            "url": "https://www.bostonglobe.com/2022/12/10/metro/today-history/?camp=bg:brief:rss:feedly&rss_id=feedly_rss_brief",
            "image_url": "https://www.bostonglobe.com/pf/resources/images/logo-bg.jpg?d=374",
            "language": "en",
            "published_at": "2022-12-10T05:01:00.000000Z",
            "source": "bostonglobe.com",
            "categories": [
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "43a6bc6f-a026-425e-b4d2-13c055636262",
            "title": "Today in History: December 10, Mandela is mourned",
            "description": "",
            "keywords": "Chess, Tornadoes, Politics, Natural disasters, General news, Richard Pryor, Donald Trump, Yitzhak Rabin, Yasser Arafat, Barack Obama, Nelson Mandela, Shimon Peres, Philadelphia Eagles, United States government, Mississippi state government, Kentucky stat",
            "snippet": "Today in History: December 10, Mandela is mourned\n\nToday in History\n\nToday is Saturday, Dec. 10, the 344th day of 2022. There are 21 days left in the year.\n\nTod...",
            "url": "https://abcnews.go.com/US/wireStory/today-history-december-10-mandela-mourned-94914960",
            "image_url": "https://s.abcnews.com/images/US/abc_news_default_2000x2000_update_16x9_992.jpg",
            "language": "en",
            "published_at": "2022-12-10T05:00:28.000000Z",
            "source": "abcnews.go.com",
            "categories": [
                "general",
                "politics"
            ],
            "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: 2022-12-10T06:10:56 | 2022-12-10T06:10 | 2022-12-10T06 | 2022-12-10 | 2022-12 | 2022
published_after false Find all articles published after the specified date. Supported formats include: Y-m-d\TH:i:s | Y-m-d\TH:i | Y-m-d\TH | Y-m-d | Y-m | Y.
Examples: 2022-12-10T06:10:56 | 2022-12-10T06:10 | 2022-12-10T06 | 2022-12-10 | 2022-12 | 2022
published_on false Find all articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2022-12-10
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": 63260041,
        "returned": 10,
        "limit": 10,
        "page": 1
    },
    "data": [
        {
            "uuid": "572cf76b-a57a-4655-b705-a22a7961d044",
            "title": "Bellator 289 Highlight Video: Patchy Mix Chokes Out Magomed Magomedov",
            "description": "Watch Patrick Mix choke Magomed Magomedov unconscious in Round 2 Friday at Bellator 289.",
            "keywords": "",
            "snippet": "EVENTS / FIGHTS\n\nUFC Fight Night 217 Imavov vs. Gastelum\n\nUFC Fight Night 216 Cannonier vs. Strickland\n\nUFC 282 Blachowicz vs. Ankalaev\n\nBellator 291 Amosov vs....",
            "url": "https://www.sherdog.com/videos/highlightreels/Bellator-289-Highlight-Video-Patchy-Mix-Chokes-Out-Magomed-Magomedov-19302",
            "image_url": "https://www1-cdn.sherdog.com/_images/videos/20221209101040_highlight_640_384.PNG",
            "language": "en",
            "published_at": "2022-12-10T06:10:40.000000Z",
            "source": "sherdog.com",
            "categories": [
                "sports"
            ],
            "relevance_score": null
        },
        {
            "uuid": "42e553a3-d985-4f7d-a0ec-77bb31b474a3",
            "title": "Lionel Messi says Van Gaal 'disrespected' him before WC win",
            "description": "Lionel Messi said he felt",
            "keywords": "",
            "snippet": "Luis Miguel Echegaray reacts to Argentina's dramatic victory over the Netherlands on penalties. (2:04)\n\nEchegaray: Messi's assist one of the best I've ever seen...",
            "url": "https://www.espn.co.uk/football/argentina-arg/story/4829757/lionel-messi-says-netherlands-coach-van-gaal-disrespected-him-before-argentina-world-cup-win",
            "image_url": "https://a.espncdn.com/combiner/i?img=%2Fphoto%2F2022%2F1210%2Fr1104702_1296x729_16%2D9.jpg",
            "language": "en",
            "published_at": "2022-12-10T06:08:13.000000Z",
            "source": "espn.co.uk",
            "categories": [
                "sports"
            ],
            "relevance_score": null
        },
        {
            "uuid": "21816f35-2dcf-4cea-a820-1c7c731fa651",
            "title": "미 증시 3대 지수 하락 마감",
            "description": "미 증시 3대 지수가 하락 마감했다.S&P500: -0.7%나스닥: -0.7%다우: -0.9%",
            "keywords": "",
            "snippet": "",
            "url": "http://coinreaders.com/55174",
            "image_url": "https://www.coinreaders.com/news_skin/coinreaders_com/main/img/favicon.ico?v=1596005342",
            "language": "ko",
            "published_at": "2022-12-10T06:07:23.000000Z",
            "source": "coinreaders.com",
            "categories": [],
            "relevance_score": null
        },
        {
            "uuid": "6ff26ef4-875d-4d1e-9b8a-56696a59ecc7",
            "title": "A \"Settegiorni\" l'iter della manovra in Parlamento e il punto sul Pnrr",
            "description": "In sommario anche il possibile stop ai cellulari in classe",
            "keywords": "",
            "snippet": "Dalle misure contro il caro energia al pacchetto fiscale: il dibattito sulla manovra economica all’esame della commissione Bilancio di Montecitorio è al cent...",
            "url": "https://www.rai.it/ufficiostampa/assets/template/us-articolo.html?ssiPath=/articoli/2022/12/A-Settegiorni-liter-della-manovra-in-Parlamento-e-il-punto-sul-Pnrr-84a58acf-4615-4339-a705-3517884fa2a9-ssi.html",
            "image_url": "http://www.rai.it/cropgd/560x292/dl/img/2020/06/12/1600x900_1591975270350_settegiorni%20rai%20parlamento.jpg",
            "language": "it",
            "published_at": "2022-12-10T06:05:00.000000Z",
            "source": "rai.it",
            "categories": [
                "business"
            ],
            "relevance_score": null
        },
        {
            "uuid": "5188f17e-5491-4f03-b10b-2159caa2238f",
            "title": "한길안과병원 정규형 이사장, '자랑스러운 전문병원인 대상' 수상",
            "description": "한길안과병원 정규형 이사장이 ‘KJ국제 자랑스러운 전문병원인상’ 대상의 영예를 안았다.대한전문병원협회는 지난 9?...",
            "keywords": "",
            "snippet": "대한전문병원협회는 지난 9일 밀레니엄 힐튼 서울에서 열린 ‘제3회 KJ국제 자랑스러운 전문병원인상’ 시상식에서 올 ?...",
            "url": "http://www.docdocdoc.co.kr/news/articleView.html?idxno=3000432",
            "image_url": "https://cdn.docdocdoc.co.kr/news/thumbnail/202212/3000432_3000468_2624_v150.jpg",
            "language": "ko",
            "published_at": "2022-12-10T06:04:40.000000Z",
            "source": "docdocdoc.co.kr",
            "categories": [],
            "relevance_score": null
        },
        {
            "uuid": "4ce59e3a-88a8-4558-8269-cf1b795740ef",
            "title": "Amplify - Spiritual Alchemists (2022)",
            "description": "Tracklist 1. Amplify (MX)  Chacruna – Spiritual Practice (07:33) 2. Amplify (MX)  Ital – Organic Beings (07:12) 3. Amplify (MX)  Psiger – Kali (07:12) 4. ...",
            "keywords": "Amplify, Tracklist, Return, Hypnoise, Possibilities, Universal, Allahu, Sapiens, Mathematics, Galaxy, Awakening, Great, Makers, Inner, Miracle, Level, Solaris, District, Psiger, Beings",
            "snippet": "Information\n\nAll musical material presented on this site is intended for educational purposes only! Acquire, please legitimate discs, which no doubt will adorn ...",
            "url": "https://www.isrbx.net/3138012061-amplify-spiritual-alchemists-2022.html",
            "image_url": "https://www.isrbx.net/templates/eng/images/favicon.ico",
            "language": "en",
            "published_at": "2022-12-10T06:02:42.000000Z",
            "source": "isrbx.net",
            "categories": [
                "entertainment"
            ],
            "relevance_score": null
        },
        {
            "uuid": "5e4344d0-dc4a-48a9-a280-c0e6cc8c30e1",
            "title": "카보메틱스+티쎈트릭, 폐암 임상 3상 실패",
            "description": "[의약뉴스] 입센의 항암제 카보메틱스(성분명 카보잔티닙)와 로슈의 면역항암제 티쎈트릭(성분명 아테졸리주맙) 병용요?...",
            "keywords": "",
            "snippet": "전체 생존기간 개선 못해...자세한 결과는 차후 공개\n\n[의약뉴스] 입센의 항암제 카보메틱스(성분명 카보잔티닙)와 로슈?...",
            "url": "http://www.newsmp.com/news/articleView.html?idxno=228811",
            "image_url": "http://www.newsmp.com/news/thumbnail/202212/228811_240738_3933_v150.jpg",
            "language": "ko",
            "published_at": "2022-12-10T06:01:16.000000Z",
            "source": "newsmp.com",
            "categories": [],
            "relevance_score": null
        },
        {
            "uuid": "25a3203c-b72a-4d13-98aa-8c84025bab61",
            "title": "‘첫 48팀 토너먼트’ 2026 월드컵, 득실? 어차피 우승은…[월드컵]",
            "description": "“모든 이들에게 ‘큰 것’이 더 나은 것인지는 확실치 않다” 2022 카타르 월드컵이 16강전을 마무리하고 최종 우승팀을 ...",
            "keywords": "헤럴드경제, 헤경, heraldcorp, 경제지, 신문, 뉴스, 보도, 속보, 정치, 경제, 사회, 국제, 문화, 사설, 컬럼, News, Newspaper, Korea, South Korea, Rep.Korea",
            "snippet": "2026년 월드컵부터 본선 진출 32개팀→48개팀\n\n각종 이변 가능성…축구 저변 확대의 기회\n\n다윗 vs 골리앗 대결에서 다윗 승...",
            "url": "https://biz.heraldcorp.com/view.php?ud=20221209000654",
            "image_url": "https://res.heraldm.com/content/image/2022/12/09/20221209000633_p.jpg",
            "language": "ko",
            "published_at": "2022-12-10T06:01:10.000000Z",
            "source": "biz.heraldcorp.com",
            "categories": [
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "a0e0c34b-e8d7-4c88-9826-126a59156d13",
            "title": "與, 난데없는 ‘당대표 조건’ 논란...‘MZ 없는 MZ 대표론’ 비판도 [정치쫌!]",
            "description": "주호영 국민의힘 원내대표가 띄우고 정진석 비상대책위원장이 키운 ‘MZ 대표론’ 여진이 거세다. ‘한동훈 차출론’으?...",
            "keywords": "헤럴드경제, 헤경, heraldcorp, 경제지, 신문, 뉴스, 보도, 속보, 정치, 경제, 사회, 국제, 문화, 사설, 컬럼, News, Newspaper, Korea, South Korea, Rep.Korea",
            "snippet": "안철수·유승민, ‘MZ세대 적합한 당대표’ 자기 어필\n\n‘윤핵관’ 김기현·장제원 “어떤 의도인지 이해 안 가”\n\n與, 정?...",
            "url": "https://biz.heraldcorp.com/view.php?ud=20221209000653",
            "image_url": "https://res.heraldm.com/content/image/2022/12/09/20221209000630_p.jpg",
            "language": "ko",
            "published_at": "2022-12-10T06:01:09.000000Z",
            "source": "biz.heraldcorp.com",
            "categories": [
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "f9e2642f-9d41-4f05-949f-c5e51ec01508",
            "title": "Luxembourg Radio Orchestra, Louis De Froment - Daniel-Lesur: Andrea Del Sarto, A Symphonic Poem / Constant: Turner Three Essays for Orchestra / Roussel: Suite in F, Op. 33 / Tomasi: Fanfares Liturgiqu",
            "description": "Tracklist  01. Andrea del Sarto: Symphonic Poem 02. Suite in F Major, Op. 33: I. Prélude 03. Suite in F Major, Op. 33: II. Sarabande 04. Suite in F Major, Op. ...",
            "keywords": "Fanfare, liturgiques, Suite, Major, Turner, Essays, Orchestra, Tracklist, fantastik, publication, Saint, Vendredi, Procession, Apocalypse, Evangile, Annonciation, Portrait, Windsor, himself, Andrea",
            "snippet": "Information\n\nAll musical material presented on this site is intended for educational purposes only! Acquire, please legitimate discs, which no doubt will adorn ...",
            "url": "https://www.isrbx.net/3138012060-luxembourg-radio-orchestra-louis-de-froment-daniel-lesur-andrea-del-sarto-a-symphonic-poem-constant-turner-three-essays-for-orchestra-roussel-suite-in-f-op-33-tomasi-fanfares-liturgiques-202.html",
            "image_url": "https://www.isrbx.net/templates/eng/images/favicon.ico",
            "language": "en",
            "published_at": "2022-12-10T06:00:54.000000Z",
            "source": "isrbx.net",
            "categories": [
                "entertainment"
            ],
            "relevance_score": null
        }
    ]
}
            
        

Similar News Available on: All plans

Endpoint

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

Use this endpoint to find similar stories to a specific article based on its UUID.

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

All text data returned is UTF-8.

All dates are in UTC (GMT).

HTTP GET Parameters

name required description
api_token true Your API token which can be found on your account dashboard.
categories false Comma separated list of categories to include.
Supported categories: general | science | sports | business | health | entertainment | tech | politics | food | travel
Example: business,tech
exclude_categories false Comma separated list of categories to exclude.
domains false Comma separated list of domains to include. List of domains can be obtained through our Sources endpoint, found further down this page.
exclude_domains false Comma separated list of domains to exclude
source_ids false Comma separated list of source_ids to include. List of source_ids can be obtained through our Sources endpoint, found further down this page.
exclude_source_ids false Comma separated list of source_ids to exclude.
language false Comma separated list of languages to include. Default is all.
Click here for a list of supported languages.
Examples: en,es (English + Spanish)
published_before false Find all articles published before the specified date. Supported formats include: Y-m-d\TH:i:s | Y-m-d\TH:i | Y-m-d\TH | Y-m-d | Y-m | Y.
Examples: 2022-12-10T06:10:56 | 2022-12-10T06:10 | 2022-12-10T06 | 2022-12-10 | 2022-12 | 2022
published_after false Find all articles published after the specified date. Supported formats include: Y-m-d\TH:i:s | Y-m-d\TH:i | Y-m-d\TH | Y-m-d | Y-m | Y.
Examples: 2022-12-10T06:10:56 | 2022-12-10T06:10 | 2022-12-10T06 | 2022-12-10 | 2022-12 | 2022
published_on false Find all articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2022-12-10
limit false Specify the number of articles you want to return in the request. The maximum limit is based on your plan. The default limit is the maximum specified for your plan.
page false Use this to paginate through the result set. Default is 1. Note that the max result set can't exceed 20,000. For example if your limit is 50, the max page you can have is 400 (50 * 400 = 20,000).
Example: page=2

Response Objects

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

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

Example Request

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

Example Response

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

News by UUID Available on: All plans

Endpoint

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

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

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

All text data returned is UTF-8.

All dates are in UTC (GMT).

HTTP GET Parameters

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

Response Objects

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

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

Example Request

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

Example Response

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

Sources Available on: All plans

Endpoint

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

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

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

All text data returned is UTF-8.

HTTP GET Parameters

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

Response Objects

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

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

Example Request

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

Example Response

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

Errors

Errors

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

Errors

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

Example Error Response

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

Examples

API Examples

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

Example Request 1

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

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

Example Request 2

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

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

Example Request 3

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

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

Example Request 4

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

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

Example Request 5

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

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

Example Request 6

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

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

Code Examples

See our prepared examples below to quickly get started implementing our API into your next project.

PHP

    
        $queryString = http_build_query([
            'api_token' => 'YOUR_API_TOKEN',
            'categories' => 'business,tech',
            'search' => 'apple',
            'limit' => 50,
        ]);

        $ch = curl_init(sprintf('%s?%s', 'https://api.thenewsapi.com/v1/news/all', $queryString));
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

        $json = curl_exec($ch);

        curl_close($ch);

        $apiResult = json_decode($json, true);

        print_r($apiResult);
    

Python

    
        # Python 3
        import http.client, urllib.parse

        conn = http.client.HTTPSConnection('api.thenewsapi.com')

        params = urllib.parse.urlencode({
            'api_token': 'YOUR_API_TOKEN',
            'categories': 'business,tech',
            'limit': 50,
            })

        conn.request('GET', '/v1/news/all?{}'.format(params))

        res = conn.getresponse()
        data = res.read()

        print(data.decode('utf-8'))
    

Go

    
        package main

        import (
            "fmt"
            "io/ioutil"
            "net/http"
            "net/url"
        )

        func main() {
            baseURL, _ := url.Parse("https://thenewsapi.com")

            baseURL.Path += "v1/news/all"

            params := url.Values{}
            params.Add("api_token", "YOUR_API_TOKEN")
            params.Add("categories", "business,tech")
            params.Add("search", "apple")
            params.Add("limit", "50")

            baseURL.RawQuery = params.Encode()

            req, _ := http.NewRequest("GET", baseURL.String(), nil)

            res, _ := http.DefaultClient.Do(req)

            defer res.Body.Close()

            body, _ := ioutil.ReadAll(res.Body)

            fmt.Println(string(body))
        }
    

JavaScript

    
        var requestOptions = {
            method: 'GET'
        };

        var params = {
            api_token: 'YOUR_API_TOKEN',
            categories: 'business,tech',
            search: 'apple',
            limit: '50'
        };

        var esc = encodeURIComponent;
        var query = Object.keys(params)
            .map(function(k) {return esc(k) + '=' + esc(params[k]);})
            .join('&');

        fetch("https://api.thenewsapi.com/v1/news/all?" + query, requestOptions)
          .then(response => response.text())
          .then(result => console.log(result))
          .catch(error => console.log('error', error));
    

C#

    
        var client = new RestClient("https://api.thenewsapi.com/v1/news/all");
        client.Timeout = -1;

        var request = new RestRequest(Method.GET);

        request.AddQueryParameter("api_token", "YOUR_API_TOKEN");
        request.AddQueryParameter("categories", "business,tech");
        request.AddQueryParameter("search", "apple");
        request.AddQueryParameter("limit", "50");

        IRestResponse response = client.Execute(request);
        Console.WriteLine(response.Content);
    

Java

    
        OkHttpClient client = new OkHttpClient().newBuilder()
          .build();

        HttpUrl.Builder httpBuilder = HttpUrl.parse("https://api.thenewsapi.com/v1/news/all").newBuilder();
        httpBuilder.addQueryParameter("api_token", "YOUR_API_TOKEN");
        httpBuilder.addQueryParameter("categories", "business,tech");
        httpBuilder.addQueryParameter("search", "apple");
        httpBuilder.addQueryParameter("limit", "50");

        Request request = new Request.Builder().url(httpBuilder.build()).build();

        Response response = client.newCall(request).execute();
    

More

Stock Market News APIs

We also provide a dedicated finance and stock market news and analysis API, perfect for financial apps. Check it out here: marketaux.com.