Getting Started

Introduction

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

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

To 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: 2023-02-02
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": "59208fb7-cd81-44d1-ba0b-37bc28f0cc14",
                "title": "Brookline police identify burglary suspect",
                "description": "Wyatt Sears of Milton, N.H. Was identified by surveillance photos circulated on social media, police said.",
                "keywords": "",
                "snippet": "A New Hampshire man was identified Wednesday as the third of five suspects facing charges for allegedly stealing mail and unopened packages from a Brookline apa...",
                "url": "https://www.bostonglobe.com/2023/02/02/metro/brookline-police-identify-burglary-suspect/?camp=bg:brief:rss:feedly&rss_id=feedly_rss_brief",
                "image_url": "https://bostonglobe-prod.cdn.arcpublishing.com/resizer/bNqloxbOCUTjlCwqtxBueQcPZkQ=/506x0/cloudfront-us-east-1.images.arcpublishing.com/bostonglobe/Z2OU6FS77BERZAQ2NJPEKCPALU.jpeg",
                "language": "en",
                "published_at": "2023-02-02T07:38:45.000000Z",
                "source": "bostonglobe.com",
                "categories": [
                    "general"
                ],
                "locale": "us",
                "similar": [
                    {
                        "uuid": "d3689807-f1bc-4385-aee6-beb277fc2778",
                        "title": "Man dies after brawl breaks out at Vermont middle school basketball game: Police",
                        "description": "A 60-year-old man died after a fight broke out between spectators at a middle school basketball game in Alburgh, Vermont, on Tuesday, according to state police.",
                        "keywords": "",
                        "snippet": "A 60-year-old man died after a brawl broke out between spectators at a middle school basketball game in Vermont, according to state police.\n\nThe fight occurred ...",
                        "url": "https://abcnews.go.com/US/man-dies-after-brawl-breaks-vermont-middle-school/story?id=96823132",
                        "image_url": "https://s.abcnews.com/images/US/education-center-ht-230201_1675270783027_hpMain_16x9_992.jpg",
                        "language": "en",
                        "published_at": "2023-02-02T00:09:12.000000Z",
                        "source": "abcnews.go.com",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "73ff32d9-d8fe-46b4-b9ba-50306246d9f2",
                        "title": "R.I. police chief: ‘Yes, Scarlett, there is a Santa Claus’",
                        "description": "Scarlett Doumato, 10, sent half-chewed cookies and carrots to the Cumberland Police Department and asked them to “take a sample of DNA and see if Santa is real?” They investigated, and then held a press conference to explain what they found.",
                        "keywords": "",
                        "snippet": "To quote New York Sun editor Francis B. Church, Police Chief Matthew Benson told Scarlett, who sat in the front row with her family, “Yes, Scarlett, there is ...",
                        "url": "https://www.bostonglobe.com/2023/02/01/metro/ri-police-chief-yes-scarlett-there-is-santa-claus/?camp=bg:brief:rss:feedly&rss_id=feedly_rss_brief",
                        "image_url": "https://bostonglobe-prod.cdn.arcpublishing.com/resizer/acFBrOqZ740plcoNr3ToE5uGAu8=/506x0/cloudfront-us-east-1.images.arcpublishing.com/bostonglobe/3E3OLY5RXREWVAK2EZBK7SAU3Q.jpg",
                        "language": "en",
                        "published_at": "2023-02-02T01:14:39.000000Z",
                        "source": "bostonglobe.com",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "bb7ca84f-3769-47f9-a94c-76baf55d3ce4",
                        "title": "Texas executes man convicted in fatal 2007 shooting of Dallas police officer",
                        "description": "Wesley Ruiz received a lethal injection at the state penitentiary in Huntsville for the killing of Dallas Police Senior Cpl. Mark Nix.",
                        "keywords": "Texas, Executions, execution",
                        "snippet": "A man convicted of fatally shooting a Dallas police officer nearly 16 years ago after a high-speed chase was executed on Wednesday.\n\nWesley Ruiz, 43, received a...",
                        "url": "https://www.cbsnews.com/news/wesley-ruiz-executed-texas-mark-nix-fatal-shooting-dallas-police-officer/",
                        "image_url": "https://assets3.cbsnewsstatic.com/hub/i/r/2023/02/02/c6441e98-e26a-47b0-81ef-4c30f8bc81f0/thumbnail/1200x630/9ce57175d4b50fa7d5b21462c5fcc5bf/ap23031726343649.jpg",
                        "language": "en",
                        "published_at": "2023-02-02T01:57:52.000000Z",
                        "source": "cbsnews.com",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "8f309e6c-0a57-4aa5-807b-c452407996d5",
                        "title": "N.H. State Police cruiser struck on I-93 ramp in Hookset",
                        "description": "A trooper was in the driver’s seat and a passenger was seated in the backseat when the cruiser was struck in the rear at around 7:50 p.m.  Wednesday on the Hooksett Road ramp entrance, New Hampshire State Police said on Twitter.",
                        "keywords": "",
                        "snippet": "A New Hampshire State Police cruiser was struck while on the scene of a single motor vehicle crash on the Interstate 93 ramp in Hookset, N.H., authorities said....",
                        "url": "https://www.bostonglobe.com/2023/02/01/metro/nh-state-police-cruiser-struck-i-93-ramp-hookset/?camp=bg:brief:rss:feedly&rss_id=feedly_rss_brief",
                        "image_url": "https://bostonglobe-prod.cdn.arcpublishing.com/resizer/M9B3XlKexr62NC6APJXBjK3swL8=/506x0/cloudfront-us-east-1.images.arcpublishing.com/bostonglobe/IXLNWKVP2NGERPTB7H63EJTQNI.jpg",
                        "language": "en",
                        "published_at": "2023-02-02T04:33:04.000000Z",
                        "source": "bostonglobe.com",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "ed19de4b-3116-45b1-8432-d553fefd4bb1",
                        "title": "Family pleads for answers after Calif. police fatally shoot double amputee",
                        "description": "Huntington Park police in California fatally shot Anthony Lowe, a double amputee. His family decried the use of lethal force on a disabled suspect.",
                        "keywords": "",
                        "snippet": "Listen Comment Gift Article Share\n\nAnthony Lowe, a double amputee who used a wheelchair, was approached by two police officers on a sidewalk in Huntington Park,...",
                        "url": "https://www.washingtonpost.com/nation/2023/02/02/huntington-police-shooting-amputee/",
                        "image_url": "https://www.washingtonpost.com/wp-apps/imrs.php?src=https://arc-anglerfish-washpost-prod-washpost.s3.amazonaws.com/public/74NZA22D4XSIZJZP6X2JNNIUZM.jpg&w=1440",
                        "language": "en",
                        "published_at": "2023-02-02T05:54:45.000000Z",
                        "source": "washingtonpost.com",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    }
                ]
            },
            {
                "uuid": "c6aa6197-be7f-46ac-bf8d-21a84fb3197e",
                "title": "House GOP preparing to oust Democrat from committee",
                "description": "Thursday's vote is a quick turnaround by House Speaker Kevin McCarthy to solidify wavering Republican support for moving against the Somali-born Muslim woman in the new Congress.",
                "keywords": "Congress, Omar",
                "snippet": "Thursday's vote is a quick turnaround by House Speaker Kevin McCarthy to solidify wavering Republican support for moving against the Somali-born Muslim woman in...",
                "url": "https://www.bostonglobe.com/2023/02/02/nation/house-gop-preparing-oust-democrat-committee/?camp=bg:brief:rss:feedly&rss_id=feedly_rss_brief",
                "image_url": "https://bostonglobe-prod.cdn.arcpublishing.com/resizer/nDxScmGUZ0GETgy-jI9FBweCKuA=/506x0/cloudfront-us-east-1.images.arcpublishing.com/bostonglobe/JNDBQ57PS6LRYU5AQXADGBNU2M.jpg",
                "language": "en",
                "published_at": "2023-02-02T05:18:28.000000Z",
                "source": "bostonglobe.com",
                "categories": [
                    "general"
                ],
                "locale": "us",
                "similar": [
                    {
                        "uuid": "f53768cf-4605-4fb5-85d1-cc220d9f485f",
                        "title": "Timeline of investigation into Joe Biden classified documents: From office to beach house",
                        "description": "The Joe Biden classified documents probe has led to FBI searches at locations tied to the president, including his Rehoboth Beach, Delaware, house.",
                        "keywords": "",
                        "snippet": "Timeline of investigation into Joe Biden classified documents: From office to beach house\n\nShow Caption Hide Caption How Biden's classified document discovery c...",
                        "url": "https://www.usatoday.com/story/news/politics/2023/02/01/biden-documents-investigation-complete-timeline/11163343002/",
                        "image_url": "https://www.gannett-cdn.com/presto/2023/01/22/USAT/d3bbd070-460b-4704-9f90-42be5fa7a49d-AP_Biden_Classified_Document.jpg?auto=webp&crop=3471,1953,x0,y176&format=pjpg&width=1200",
                        "language": "en",
                        "published_at": "2023-02-01T21:05:47.000000Z",
                        "source": "usatoday.com",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "701faba6-2ebe-4e50-82d0-00fc99fe10ce",
                        "title": "Biden, McCarthy meet at White House on debt crisis worries",
                        "description": "“No agreement, no promises except we will continue this conversation,” McCarthy told reporters outside the White House.",
                        "keywords": "",
                        "snippet": "Biden has resisted direct spending negotiations linked to vital action raising the nation’s legal debt ceiling, warning against potentially throwing the econo...",
                        "url": "https://www.bostonglobe.com/2023/02/01/nation/biden-mccarthy-meet-white-house-debt-crisis-worries/?camp=bg:brief:rss:feedly&rss_id=feedly_rss_brief",
                        "image_url": "https://bostonglobe-prod.cdn.arcpublishing.com/resizer/UG7WdrfZsNPiSR9u6zzDgXDgzTc=/506x0/cloudfront-us-east-1.images.arcpublishing.com/bostonglobe/NHOSQ4J2J7GMKPWZ2M6NB5C5TU.jpg",
                        "language": "en",
                        "published_at": "2023-02-01T22:35:06.000000Z",
                        "source": "bostonglobe.com",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "a0bb59ee-fdec-4e43-aea9-bd0222c2d266",
                        "title": "'Bigoted hatred': Republicans prepping vote to oust Ilhan Omar from House Foreign Affairs Committee",
                        "description": "Democratic Rep. Ilhan Omar of Minnesota and her progressive allies are denouncing the Republican effort to oust her from a key House panel as early as Thursday.House Republicans on Wednesday advanced a resolution to remove Omar from the House Foreign Affairs Committee (HFAC). In a party-line 218-209...",
                        "keywords": "",
                        "snippet": "Democratic Rep. Ilhan Omar of Minnesota and her progressive allies are denouncing the Republican effort to oust her from a key House panel as early as Thursday....",
                        "url": "https://www.alternet.org/bigoted-hatred-republicans-ilhan-omar/",
                        "image_url": "https://www.alternet.org/media-library/image.jpg?id=29692573&width=1200&height=600&coordinates=0%2C106%2C0%2C107",
                        "language": "en",
                        "published_at": "2023-02-01T23:15:01.000000Z",
                        "source": "alternet.org",
                        "categories": [
                            "general",
                            "politics"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "1272cfc3-89ed-4bbb-8d41-ac962bfc0911",
                        "title": "House GOP preparing to oust Democrat from committee",
                        "description": "WASHINGTON (AP) — House Republicans are preparing to oust Democratic Rep. Ilhan Omar from the House Foreign Affairs Committee for her past comments critical of Israel , an escalation of tensions after Democrats last session booted far-right GOP lawmakers from committees over their incendiary, violent remarks.",
                        "keywords": "Politics, United States government, U.S. Republican Party, United States House of Representatives, AP Top News, Somalia, Kevin McCarthy, Ilhan Omar, Israel, Minnesota",
                        "snippet": "FILE - Rep. Ilhan Omar, D-Minn., speaks during a news conference on Capitol Hill in Washington, Jan. 25, 2023, in Washington. House Republicans are preparing to...",
                        "url": "https://apnews.com/article/politics-united-states-government-us-republican-party-house-of-representatives-somalia-ee2ae3fd86b895c5b078d8bf576c3360",
                        "image_url": "https://storage.googleapis.com/afs-prod/media/f639142dbc504c2e82cbd786b361e852/3000.webp",
                        "language": "en",
                        "published_at": "2023-02-02T05:23:05.000000Z",
                        "source": "apnews.com",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    }
                ]
            }
        ],
        "business": ...,
        "sports": ...,
        "tech": ...,
        "science": ...,
        "health": ...
    }
}
            
        

Top Stories Available on: All plans

Endpoint

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

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

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

All text data returned is UTF-8.

All dates are in UTC (GMT).

HTTP GET Parameters

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

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

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

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

When using special characters (+, -, |, ", *, ()) you MUST URL-encode this parameter.
search_fields false Comma separated list of fields to apply the search parameter to.
Supported fields: title | description | keywords | main_text
Example: title,description,keywords
Default: title,main_text
locale false Comma separated list of country codes to include in the result set. Default is countries. Click here for a list of supported countries.
Example: us,ca (US + Canada).
categories false Comma separated list of categories to include.
Supported categories: general | science | sports | business | health | entertainment | tech | politics | food | travel
Example: business,tech
exclude_categories false Comma separated list of categories to exclude.
domains false Comma separated list of domains to include. List of domains can be obtained through our Sources endpoint, found further down this page.
exclude_domains false Comma separated list of domains to exclude
source_ids false Comma separated list of source_ids to include. List of source_ids can be obtained through our Sources endpoint, found further down this page.
exclude_source_ids false Comma separated list of source_ids to exclude.
language false Comma separated list of languages to include. Default is all.
Click here for a list of supported languages.
Examples: en,es (English + Spanish)
published_before false Find all articles published before the specified date. Supported formats include: Y-m-d\TH:i:s | Y-m-d\TH:i | Y-m-d\TH | Y-m-d | Y-m | Y.
Examples: 2023-02-02T08:44:09 | 2023-02-02T08:44 | 2023-02-02T08 | 2023-02-02 | 2023-02 | 2023
published_after false Find all articles published after the specified date. Supported formats include: Y-m-d\TH:i:s | Y-m-d\TH:i | Y-m-d\TH | Y-m-d | Y-m | Y.
Examples: 2023-02-02T08:44:09 | 2023-02-02T08:44 | 2023-02-02T08 | 2023-02-02 | 2023-02 | 2023
published_on false Find all articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2023-02-02
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": 543514,
        "returned": 10,
        "limit": 10,
        "page": 1
    },
    "data": [
        {
            "uuid": "82ee146f-fe6d-4ba6-95c9-25297967d645",
            "title": "Russian spy chief weighs in on ‘fighting until last Ukrainian’",
            "description": "Russia has no desire to fight until the last Ukrainian, Moscow’s spy boss Sergey Naryshkin has said",
            "keywords": "",
            "snippet": "Moscow understands that most people in Ukraine are normal and just want a peaceful life, Sergey Naryshkin says\n\nRussia has no desire for the conflict with Kiev ...",
            "url": "https://www.rt.com/russia/570843-ukraine-nato-west-naryshkin/",
            "image_url": "https://mf.b37mrtl.ru/files/2023.02/article/63db724585f540588e3c54cd.jpg",
            "language": "en",
            "published_at": "2023-02-02T08:37:48.000000Z",
            "source": "rt.com",
            "categories": [
                "general",
                "politics"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "d53c05fa-eafc-4098-9566-a2f905a88b9e",
            "title": "As ice storm continues in the South, the Northeast braces for dangerously frigid temperatures",
            "description": "As tens of thousands remain without power in Texas on Thursday amid frigid temperatures and icy roads, the Northeast is bracing for a blast of bitterly cold air...",
            "keywords": "blizzards and ice storms, brand safety-nsf death, brand safety-nsf sensitive, continents and regions, death and dying, deaths and fatalities, domestic alerts, domestic-health and science, domestic-us news, extreme cold, iab-bereavement, iab-business and finance, iab-family and relationships, iab-industries, iab-power and energy industry, iab-science, iab-weather, international alerts, international-health and science, international-us news, north america, northeastern united states, severe weather, society, southwestern united states, texas, the americas, united states, weather",
            "snippet": "CNN —\n\nAs tens of thousands remain without power in Texas on Thursday amid frigid temperatures and icy roads, the Northeast is bracing for a blast of bitterly...",
            "url": "https://www.cnn.com/2023/02/02/weather/winter-storm-south-northeast-us/index.html",
            "image_url": "https://media.cnn.com/api/v1/images/stellar/prod/230202121852-winter-storm-austin-texas-010223.jpg?c=16x9&q=w_800,c_fill",
            "language": "en",
            "published_at": "2023-02-02T08:21:02.000000Z",
            "source": "cnn.com",
            "categories": [
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "2df253c3-081d-4901-990e-c693945cbd53",
            "title": "Israeli AG: Netanyahu mustn't deal with judicial changes",
            "description": "Israel’s attorney general says Prime Minister Benjamin Netanyahu must avoid being involved in an overhaul of the country’s judicial system proposed by his g...",
            "keywords": "",
            "snippet": "Comment Gift Article Share\n\nTEL AVIV, Israel — Israel’s attorney general has told Prime Minister Benjamin Netanyahu he must avoid being involved in an overh...",
            "url": "https://www.washingtonpost.com/world/israeli-ag-netanyahu-mustnt-deal-with-judicial-changes/2023/02/02/71793668-a2d0-11ed-8b47-9863fda8e494_story.html",
            "image_url": "https://www.washingtonpost.com/resizer/2CjPNwqvXHPS_2RpuRTKY-p3eVo=/1484x0/www.washingtonpost.com/pb/resources/img/twp-social-share.png",
            "language": "en",
            "published_at": "2023-02-02T08:06:06.000000Z",
            "source": "washingtonpost.com",
            "categories": [
                "general",
                "politics"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "1eab1ce0-22be-49d3-b078-bc6cab9d06bc",
            "title": "A DC Metro employee is killed trying to stop a gunman shooting at commuters, officials say",
            "description": "A Metro transit system employee in Washington, DC, was shot and killed trying to stop a gunman from targeting commuters Wednesday morning, police say.",
            "keywords": "brand safety-nsf crime, brand safety-nsf death, brand safety-nsf sensitive, brand safety-nsf severe, brand safety-nsf violence, brand safety-nsf weapons, business and industry sectors, business, economy and trade, commuting, crime, law enforcement and corrections, crimes against persons, criminal offenses, ground transportation, heroes and heroism, iab-crime, public transportation, shootings, society, transportation and warehousing",
            "snippet": "CNN —\n\nA Metro transit system employee in Washington, DC, was shot and killed trying to stop a gunman from targeting commuters Wednesday morning, police say.\n...",
            "url": "https://www.cnn.com/2023/02/02/us/dc-metro-employee-killed-stop-gunman-shooting/index.html",
            "image_url": "https://media.cnn.com/api/v1/images/stellar/prod/230202020415-01-dc-metro-shooting-020123.jpg?c=16x9&q=w_800,c_fill",
            "language": "en",
            "published_at": "2023-02-02T08:05:20.000000Z",
            "source": "cnn.com",
            "categories": [
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "7bcec999-d3bc-4363-9e58-dc1a0dd295f3",
            "title": "Laptop email suggests Hunter Biden read newspapers, not classified documents",
            "description": "Republicans claim the president's son wrote a 2014 email with inside information. But the facts he cited could be found in news reports at the time.",
            "keywords": "",
            "snippet": "Listen Comment Gift Article Share\n\n“When I read the email, very, very detailed analysis of what’s happening in Ukraine. Actually, far more detailed than any...",
            "url": "https://www.washingtonpost.com/politics/2023/02/02/laptop-email-suggests-hunter-biden-read-newspapers-not-classified-documents/",
            "image_url": "https://www.washingtonpost.com/wp-apps/imrs.php?src=https://arc-anglerfish-washpost-prod-washpost.s3.amazonaws.com/public/V3EYZWXA6NA7K3JMFNEV2MUQXE.JPG&w=1440",
            "language": "en",
            "published_at": "2023-02-02T08:00:29.000000Z",
            "source": "washingtonpost.com",
            "categories": [
                "politics",
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "bcd7576f-cc95-42f1-8daf-ad46eba265a3",
            "title": "Who’s sending what to Ukraine: A new wave of Western weapons explained",
            "description": "From U.S. M1 Abrams to German Leopard 2 tanks, Kyiv’s allies have agreed to elaborate weapons requests that once made them balk.",
            "keywords": "",
            "snippet": "United States\n\nM1A2 ABRAMS Main battle tank Length: 25 ft 11in Armament One 105mm gun, one 7.62mm coaxial machine gun, one 12.7mm antiaircraft machine Speed 41 ...",
            "url": "https://www.washingtonpost.com/world/2023/02/02/ukraine-weapons-tanks-leopard-abrams/",
            "image_url": "https://www.washingtonpost.com/wp-apps/imrs.php?src=https://arc-anglerfish-washpost-prod-washpost.s3.amazonaws.com/public/OG5EAR26DO474WJLA6Q5X4FOYA.JPG&w=1440",
            "language": "en",
            "published_at": "2023-02-02T08:00:24.000000Z",
            "source": "washingtonpost.com",
            "categories": [
                "general",
                "politics"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "a9d89d2e-3325-44f3-aa5f-5c2814c297d9",
            "title": "Death of teen who went missing for 100 days not suspicious, Chinese police say",
            "description": "There are no suspicious circumstances in the death of a Chinese teenager whose body was found near his school last week more than 100 days after he went missing...",
            "keywords": "asia, brand safety-nsf crime, brand safety-nsf death, brand safety-nsf sensitive, china, continents and regions, crime, law enforcement and corrections, death and dying, deaths and fatalities, demographic groups, domestic alerts, domestic-international news, east asia, families and children, family members and relatives, iab-bereavement, iab-crime, iab-family and relationships, iab-parenting, iab-parenting teens, missing persons, population and demographics, society, teenagers",
            "snippet": "Hong Kong CNN —\n\nThere are no suspicious circumstances in the death of a Chinese teenager whose body was found near his school last week more than 100 days af...",
            "url": "https://www.cnn.com/2023/02/02/china/jiangxi-missing-boy-presser-china-intl-hnk/index.html",
            "image_url": "https://media.cnn.com/api/v1/images/stellar/prod/230130102903-china-missing-teen-body.jpg?c=16x9&q=w_800,c_fill",
            "language": "en",
            "published_at": "2023-02-02T07:56:28.000000Z",
            "source": "cnn.com",
            "categories": [
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "d86e7c41-ba30-454c-b3d2-b6b319dbcbde",
            "title": "Are you a robot?",
            "description": "",
            "keywords": "",
            "snippet": "Why did this happen?\n\nPlease make sure your browser supports JavaScript and cookies and that you are not blocking them from loading. For more information you ca...",
            "url": "https://www.bloomberg.com/tosv2.html?vid=&uuid=fb6e5afa-a2d4-11ed-a6b4-7274464c6761&url=L25ld3MvYXJ0aWNsZXMvMjAyMy0wMi0wMi9hZGFuaS1zdG9jay1yb3V0LWRlZXBlbnMtYWZ0ZXItZmxhZ3NoaXAtZmlybS1wdWxscy1zaGFyZS1zYWxl",
            "image_url": "",
            "language": "en",
            "published_at": "2023-02-02T07:55:00.000000Z",
            "source": "news.google.com",
            "categories": [
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "f87f5c09-99de-4fb5-bb68-a83c524d164b",
            "title": "China set to launch long-awaited IPO reforms to reset the economy",
            "description": "China is set to make market-oriented changes to the way initial public offerings are approved, as it tries to reset the economy and rebuild investor confidence ...",
            "keywords": "asia, banking, finance and investments, business, economy and trade, china, continents and regions, domestic alerts, domestic-business, domestic-international news, east asia, economy and economic indicators, financial markets and investing, financing and stock offering, iab-business, iab-business and finance, iab-business banking & finance, iab-economy, iab-financial industry, iab-industries, iab-personal finance, iab-personal investing, iab-stocks and bonds, initial public offering, international alerts, international-business, securities trading, stock markets",
            "snippet": "Hong Kong CNN —\n\nChina is set to make market-oriented changes to the way initial public offerings are approved, as it tries to reset the economy and rebuild i...",
            "url": "https://www.cnn.com/2023/02/02/economy/china-ipo-reform-reset-the-economy-intl-hnk/index.html",
            "image_url": "https://media.cnn.com/api/v1/images/stellar/prod/230202120822-csrc-building.jpg?c=16x9&q=w_800,c_fill",
            "language": "en",
            "published_at": "2023-02-02T07:50:55.000000Z",
            "source": "cnn.com",
            "categories": [
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "9cab950d-cca6-4cb3-95d2-2423a3497e23",
            "title": "Shell Joins U.S. Oil Majors in Posting Record 2022 Profit",
            "description": "U.K. company’s $41.6 billion full-year profit extends historic results from Chevron, Exxon Mobil driven by soaring energy prices",
            "keywords": "Energy, Fossil Fuels, Integrated Oil/Gas, Oil Industry, Financial Performance, Earnings, Corporate/Industrial News, Content Types, Factiva Filters, C&E Industry News Filter, SYND, WSJ-PRO-WSJ.com, Exxon Mobil, XOM, Shell, SHEL.LN, UK:SHEL, Chevron, CVX, corporate, industrial news, integrated oil, gas",
            "snippet": "LONDON— Shell PLC became the latest oil giant to post a record annual profit last year, joining American peers in surging back from early pandemic losses on s...",
            "url": "https://www.wsj.com/articles/shell-joins-u-s-oil-majors-in-posting-record-2022-profit-11675322967?mod=pls_whats_news_us_business_f",
            "image_url": "https://images.wsj.net/im-715599/social",
            "language": "en",
            "published_at": "2023-02-02T07:47:00.000000Z",
            "source": "online.wsj.com",
            "categories": [
                "business"
            ],
            "relevance_score": null,
            "locale": "us"
        }
    ]
}
            
        

All News Available on: All plans

Endpoint

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

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

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

All text data returned is UTF-8.

All dates are in UTC (GMT).

HTTP GET Parameters

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

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

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

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

When using special characters (+, -, |, ", *, ()) you MUST URL-encode this parameter.
search_fields false Comma separated list of fields to apply the search parameter to.
Supported fields: title | description | keywords | main_text
Example: title,description,keywords
Default: title,main_text
categories false Comma separated list of categories to include.
Supported categories: general | science | sports | business | health | entertainment | tech | politics | food | travel
Example: business,tech
exclude_categories false Comma separated list of categories to exclude.
domains false Comma separated list of domains to include. List of domains can be obtained through our Sources endpoint, found further down this page.
exclude_domains false Comma separated list of domains to exclude
source_ids false Comma separated list of source_ids to include. List of source_ids can be obtained through our Sources endpoint, found further down this page.
exclude_source_ids false Comma separated list of source_ids to exclude.
language false Comma separated list of languages to include. Default is all.
Click here for a list of supported languages.
Examples: en,es (English + Spanish)
published_before false Find all articles published before the specified date. Supported formats include: Y-m-d\TH:i:s | Y-m-d\TH:i | Y-m-d\TH | Y-m-d | Y-m | Y.
Examples: 2023-02-02T08:44:09 | 2023-02-02T08:44 | 2023-02-02T08 | 2023-02-02 | 2023-02 | 2023
published_after false Find all articles published after the specified date. Supported formats include: Y-m-d\TH:i:s | Y-m-d\TH:i | Y-m-d\TH | Y-m-d | Y-m | Y.
Examples: 2023-02-02T08:44:09 | 2023-02-02T08:44 | 2023-02-02T08 | 2023-02-02 | 2023-02 | 2023
published_on false Find all articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2023-02-02
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": 59993779,
        "returned": 10,
        "limit": 10,
        "page": 1
    },
    "data": [
        {
            "uuid": "495072d4-8518-4a37-a877-920315164d74",
            "title": "SK바사 스카이셀플루 칠레서 품목허가",
            "description": "SK바이오사이언스의 독감백신 스카이셀플루4가프리필드시린지(이하 스카이셀플루)가 칠레 공공보건청으로부터 허가받?...",
            "keywords": "SK바이오사이언스, 스카일셀플루",
            "snippet": "중남미 국가로는 처음\n\nSK바이오사이언스의 독감백신 스카이셀플루4가프리필드시린지(이하 스카이셀플루)가 칠레 공공?...",
            "url": "http://www.medical-tribune.co.kr/news/articleView.html?idxno=112379",
            "image_url": "http://www.medical-tribune.co.kr/news/thumbnail/202302/112379_42762_4340_v150.jpg",
            "language": "ko",
            "published_at": "2023-02-02T08:43:52.000000Z",
            "source": "medical-tribune.co.kr",
            "categories": [
                "health"
            ],
            "relevance_score": null
        },
        {
            "uuid": "aee8944c-a597-40bd-8e37-3e9f5f1fd9ea",
            "title": "SK C&C-한국MS, 애저 클라우드 기반 글로벌 AI 헬스케어 사업 협력",
            "description": "[디지털투데이 황치규 기자]SK㈜ C&C가 한국마이크로소프트와 협력해 AI 뇌출혈 영상 의료 솔루션, ‘메디컬 인사이트 플?...",
            "keywords": "클라우드, 애저, 마이크로소프트, SKC&C",
            "snippet": "2일, 경기도 성남시 분당구 정자동 SK-u 타워에서 열린 '디지털 헬스케어 솔루션 글로벌 시장 진출과 산업 생태계 확산을 ?...",
            "url": "http://www.digitaltoday.co.kr/news/articleView.html?idxno=469433",
            "image_url": "https://cdn.digitaltoday.co.kr/news/thumbnail/202302/469433_438711_4218_v150.jpg",
            "language": "ko",
            "published_at": "2023-02-02T08:43:25.000000Z",
            "source": "digitaltoday.co.kr",
            "categories": [
                "tech",
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "729b21d5-f481-4e8e-a02e-ebb8cbbad510",
            "title": "SK㈜ C&C-한국MS, 뇌출혈 솔루션 기반 글로벌 헬스케어 시장 진출 가속",
            "description": "[정보통신신문=박남수기자] SK㈜ C&C가 한국마이크로소프트와 손잡고 인공지능(AI) 뇌출혈 영상 의료 솔루션, ‘메디컬 인?...",
            "keywords": "SK㈜ C&C, 한국MS",
            "snippet": "메디컬 인사이트 플러스 뇌출혈\n\nMS 애저 헬스케어 라인업에 합류\n\n2일, 경기도 성남시 분당구 정자동 SK-u 타워에서 열린 '...",
            "url": "http://www.koit.co.kr/news/articleView.html?idxno=109117",
            "image_url": "http://www.koit.co.kr/news/thumbnail/202302/109117_61427_373_v150.jpg",
            "language": "ko",
            "published_at": "2023-02-02T08:43:00.000000Z",
            "source": "koit.co.kr",
            "categories": [
                "tech"
            ],
            "relevance_score": null
        },
        {
            "uuid": "874cf23a-c045-4b1b-8a99-08effcefca6b",
            "title": "Патрик Кинг. Как постоять за себя. Умение отстаивать свои интересы, устанавливать личные границы и перестать угодничать",
            "description": "",
            "keywords": "",
            "snippet": "",
            "url": "http://cwer.ru/node/548968/",
            "image_url": "http://cwer.ru/media/favicon.ico",
            "language": "ru",
            "published_at": "2023-02-02T08:42:31.000000Z",
            "source": "cwer.ru",
            "categories": [
                "entertainment"
            ],
            "relevance_score": null
        },
        {
            "uuid": "c9d9e6f9-eca7-4c1c-bd74-598daab3316f",
            "title": "우리금융 차기 회장, 3일 심층면접 후 선정",
            "description": "컨슈머타임스=김지훈 기자 | 우리금융지주 임원추천위원회는 1일 차기 회장 후보군에 대한 1차 면접을 종료했다고 발표?...",
            "keywords": "",
            "snippet": "우리금융 차기 회장 후보 4인. 왼쪽부터 이원덕 우리은행장, 신현석 우리 아메리카 법인장, 이동연 전 우리FIS 사장, 임종?...",
            "url": "https://www.cstimes.com/news/articleView.html?idxno=529681",
            "image_url": "https://www.cstimes.com/news/photo/202302/529681_435336_4034.jpeg",
            "language": "ko",
            "published_at": "2023-02-02T08:42:14.000000Z",
            "source": "cstimes.com",
            "categories": [],
            "relevance_score": null
        },
        {
            "uuid": "214d1ae7-10a8-4e1a-b074-18fb883496a2",
            "title": "高铁护路巡防员的2.4公里:趟雪成路 遇渠架桥-中新网视频",
            "description": "高铁护路巡防员的2.4公里:趟雪成路 遇渠架桥",
            "keywords": "",
            "snippet": "",
            "url": "https://www.chinanews.com.cn/shipin/cns/2023/02-02/news950161.shtml",
            "image_url": "https://poss-videocloud.cns.com.cn/oss/2023/02/01/chinanews/MEIZI_YUNSHI/uploadImage/013a876092424024bb63ca4f469c9027_big.jpg",
            "language": "zh",
            "published_at": "2023-02-02T08:42:11.000000Z",
            "source": "chinanews.com",
            "categories": [],
            "relevance_score": null
        },
        {
            "uuid": "23d0843d-dac7-4fcb-bd32-7193cb1fac09",
            "title": "Шок: в Самаре подросток снимал избиение бабушки на видео",
            "description": "Новости Тольятти - Шок: в Самаре подросток снимал избиение бабушки на видео",
            "keywords": "Новости Тольятти - Шок: в Самаре подросток снимал избиение бабушки на видео",
            "snippet": "18+\n\nПост не для слабонервных опубликовал один из самарских пабликов.\n\n«Нам поступила инф...",
            "url": "https://tltgorod.ru/news/?theme=29&news=127339",
            "image_url": "https://tltgorod.ru/favicon.ico",
            "language": "ru",
            "published_at": "2023-02-02T08:42:00.000000Z",
            "source": "tltgorod.ru",
            "categories": [
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "23554d92-8f63-4e29-8098-d0a52e4a2cff",
            "title": "뉴욕증시, FOMC 결과에 환호…나스닥 2%↑마감",
            "description": "*그림1*NYSE 입회장 내 방송 모니터에 금리 인상 속보가 뜬 모습[연합뉴스 자료사진](뉴욕=연합뉴스) 윤영숙 연합인포맥스 ...",
            "keywords": "",
            "snippet": "NYSE 입회장 내 방송 모니터에 금리 인상 속보가 뜬 모습\n\n[연합뉴스 자료사진]\n\n본 기사는 인포맥스 금융정보 단말기에서 ...",
            "url": "https://news.einfomax.co.kr/news/articleView.html?idxno=4252882",
            "image_url": "http://news.einfomax.co.kr/news/thumbnail/202302/4252882_139804_421_v150.jpg",
            "language": "ko",
            "published_at": "2023-02-02T08:41:56.000000Z",
            "source": "news.einfomax.co.kr",
            "categories": [
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "db9e0cd1-7d86-4dd6-b603-1d46ead6d47e",
            "title": "원진재단부설 녹색병원, 비정규직 제로",
            "description": "원진재단부설 녹색병원(병원장 임상혁)과 전국보건의료산업노동조합 녹색병원지부(지부장 조윤찬)가 파견용역 비정규?...",
            "keywords": "녹색병원, 비정규직 제로, 보건의료노조",
            "snippet": "요양보호사(재활통합병동), 조리사, 미화 노동자 전원 정규직 전환\n\n지난 2021년 ‘비정규직 없는 병원 만들겠다’는 약속...",
            "url": "http://www.khanews.com/news/articleView.html?idxno=223535",
            "image_url": "http://www.khanews.com/news/thumbnail/202302/223535_97013_407_v150.jpg",
            "language": "ko",
            "published_at": "2023-02-02T08:41:37.000000Z",
            "source": "khanews.com",
            "categories": [],
            "relevance_score": null
        },
        {
            "uuid": "06297b9e-26ae-49ca-9014-f23b65ace288",
            "title": "甘肃张掖:千年“九曲黄河灯阵”点亮 金光璀璨喜迎元宵节-中新网视频",
            "description": "甘肃张掖:千年“九曲黄河灯阵”点亮 金光璀璨喜迎元宵节",
            "keywords": "甘肃 张掖 九曲黄河灯阵",
            "snippet": "",
            "url": "https://www.chinanews.com.cn/shipin/cns-d/2023/02-02/news950159.shtml",
            "image_url": "https://poss-videocloud.cns.com.cn/oss/2023/02/01/chinanews/MEIZI_YUNSHI/onair/4451EBF1ED8F409484900296CB4C033A.jpg",
            "language": "zh",
            "published_at": "2023-02-02T08:41:24.000000Z",
            "source": "chinanews.com",
            "categories": [],
            "relevance_score": null
        }
    ]
}
            
        

Similar News Available on: All plans

Endpoint

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

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

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

All text data returned is UTF-8.

All dates are in UTC (GMT).

HTTP GET Parameters

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

Response Objects

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

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

Example Request

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

Example Response

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

News by UUID Available on: All plans

Endpoint

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

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

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

All text data returned is UTF-8.

All dates are in UTC (GMT).

HTTP GET Parameters

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

Response Objects

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

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

Example Request

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

Example Response

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

Sources Available on: All plans

Endpoint

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

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

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

All text data returned is UTF-8.

HTTP GET Parameters

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

Response Objects

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

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

Example Request

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

Example Response

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

Errors

Errors

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

Errors

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

Example Error Response

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

Examples

API Examples

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

Example Request 1

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

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

Example Request 2

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

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

Example Request 3

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

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

Example Request 4

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

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

Example Request 5

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

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

Example Request 6

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

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

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.