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-07-04
headlines_per_category false Specify the number of articles you want to return per category. The maximum is 10 and the default is 6.
include_similar false Specify if you wish to include similar articles with each base article. Default is true.

Response Objects

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

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

Example Request

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

Example Response

            
                {
    "data": {
        "general": [
            {
                "uuid": "c096d06a-3a90-4cea-8920-098dc1e89ede",
                "title": "A Black man who was killed by police was unarmed at the time of the shooting",
                "description": "Officials in Akron, Ohio, released video of the pursuit and shooting of Jayland Walker, 25. The police chief said officers tried to stop Walker's car for unspecified traffic and equipment violations.",
                "keywords": "",
                "snippet": "A Black man who was killed by police was unarmed at the time of the shooting\n\ntoggle caption Phil Masturzo/Akron Beacon Journal via AP\n\nAKRON, Ohio — A Black ...",
                "url": "https://www.npr.org/2022/07/03/1109624745/jayland-walker-akron-ohio",
                "image_url": "https://media.npr.org/assets/img/2022/07/03/ap22183790424940_wide-8953f77e0e4e4d7cd5c5d6894b0e8374195e498b.jpg?s=1400",
                "language": "en",
                "published_at": "2022-07-03T19:32:33.000000Z",
                "source": "npr.org",
                "categories": [
                    "general"
                ],
                "locale": "us",
                "similar": [
                    {
                        "uuid": "bf9fae3b-9b3e-4db1-afb6-f109eefcfc9e",
                        "title": "Several dead in Copenhagen mall shooting; suspect arrested",
                        "description": "COPENHAGEN, Denmark (AP) — A gunman opened fired inside a busy shopping mall in the Danish capital on Sunday, killing several people and wounding several others, police said. A 22-year-old Danish man was arrested after the shooting, Copenhagen police inspector Søren Thomassen told reporters, adding there was no indication that anyone else was involved, though police were still investigating.",
                        "keywords": "Entertainment, Sports, AP Top News, World News, Europe, Business, Harry Styles, Music, Shootings, Arrests, Denmark, Copenhagen",
                        "snippet": "An ambulance and armed police outside the Field's shopping center, in Orestad, Copenhagen, Denmark, Sunday, July 3, 2022, after reports of shots fired. Danish p...",
                        "url": "https://apnews.com/article/shootings-denmark-copenhagen-e5670b98e4b604da265028614652cbd3",
                        "image_url": "https://storage.googleapis.com/afs-prod/media/6e2abf2f159e438299e99665fe2b7543/3000.jpeg",
                        "language": "en",
                        "published_at": "2022-07-03T19:50:57.000000Z",
                        "source": "news.google.com",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "84960e01-379c-441e-b151-f32b2dd39833",
                        "title": "3 dead, 3 critically wounded in shooting at Denmark mall",
                        "description": "COPENHAGEN — A gunman opened fire inside a busy shopping mall in the Danish capital Sunday, killing three people and critically wounding three others, police said.",
                        "keywords": "Denmark, Shooting",
                        "snippet": "A 22-year-old Danish man was arrested after the shooting, Copenhagen police inspector Søren Thomassen told reporters, adding there was no indication that anyon...",
                        "url": "https://www.bostonglobe.com/2022/07/03/world/3-dead-3-critically-wounded-shooting-denmark-mall/?camp=bg:brief:rss:feedly&rss_id=feedly_rss_brief",
                        "image_url": "https://www.bostonglobe.com/pf/resources/images/logo-bg.jpg?d=349",
                        "language": "en",
                        "published_at": "2022-07-03T23:37:18.000000Z",
                        "source": "bostonglobe.com",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "8976dc0d-7538-45b4-bf08-87707b49c6b7",
                        "title": "Jayland Walker bodycam footage: Policing experts say more questions come from fatal shooting video",
                        "description": "Experts told USA TODAY the videos on their own ultimately do not provide full clarity on key moments, including what led to the use of deadly force.",
                        "keywords": "",
                        "snippet": "Jayland Walker bodycam footage: Policing experts say more questions come from fatal shooting video\n\nShow Caption Hide Caption Akron man shot dozens of times by ...",
                        "url": "https://www.usatoday.com/story/news/nation/2022/07/03/jayland-walker-bodycam-footage-experts/7799664001/",
                        "image_url": "https://www.gannett-cdn.com/presto/2022/07/03/USAT/269986fc-3658-41f6-b054-72fef8ac8616-AP_Fatal_Police_Shooting.JPG?auto=webp&crop=2399,1349,x0,y208&format=pjpg&width=1200",
                        "language": "en",
                        "published_at": "2022-07-03T23:51:59.000000Z",
                        "source": "usatoday.com",
                        "categories": [
                            "general",
                            "travel",
                            "sports"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "9a45ee46-37fb-4460-98df-459c7cf73236",
                        "title": "Harry Styles Concert in Denmark Canceled After Mass Shooting",
                        "description": "Following a mass shooting in Copenhagen, Harry Styles took to social media saying he was \"devastated\" for the people of Denmark.",
                        "keywords": "",
                        "snippet": "Watch : Olivia Wilde Subtly Supports BF Harry Styles' New Album\n\nLove on pause.\n\nJust hours before he was set to hit the stage, Harry Styles canceled his July 3...",
                        "url": "https://www.eonline.com/news/1336709/harry-styles-speaks-out-after-denmark-concert-is-canceled-after-mass-shooting-in-nearby-mall?cmpid=rss-000000-rssfeed-365-topstories&utm_source=eonline&utm_medium=rssfeeds&utm_campaign=rss_topstories",
                        "image_url": "https://akns-images.eonline.com/eol_images/Entire_Site/202249/rs_1200x1200-220509172726-1200-Harry-styles-1.jpg?fit=around%7C1080:566&output-quality=90&crop=1080:566;center,top",
                        "language": "en",
                        "published_at": "2022-07-04T00:41:27.000000Z",
                        "source": "eonline.com",
                        "categories": [
                            "entertainment",
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "47323e06-3b1a-45bb-a43f-032a841eb252",
                        "title": "Harry Styles cancels Copenhagen show after",
                        "description": "British pop star Harry Styles has canceled his performance in Copenhagen after a shooting took place at a mall close to the concert venue where he was scheduled to perform.",
                        "keywords": "entertainment, Harry Styles cancels Copenhagen show after  - CNN",
                        "snippet": "(CNN) British pop star Harry Styles has canceled his performance in Copenhagen after a shooting took place at a mall close to the concert venue where he was sch...",
                        "url": "https://www.cnn.com/2022/07/03/entertainment/harry-styles-copenhagen/index.html",
                        "image_url": "https://cdn.cnn.com/cnnnext/dam/assets/220630093612-pm-harry-styles-super-tease.jpg",
                        "language": "en",
                        "published_at": "2022-07-04T00:59:13.000000Z",
                        "source": "cnn.com",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    }
                ]
            },
            {
                "uuid": "5f270bc2-396e-446f-86bd-6da530e1f033",
                "title": "Police say unarmed Black man in Ohio traffic stop was shot 60 times",
                "description": "A 25-year-old Black man who was killed last week by police officers in Akron, Ohio, suffered more than 60 gunshot wounds but was unarmed at the time, the police chief said Sunday.",
                "keywords": "",
                "snippet": "Walker had one traffic ticket and no criminal record. Police said they initially sought to pull him over for an equipment violation and a traffic violation.\n\nTh...",
                "url": "https://www.bostonglobe.com/2022/07/03/nation/police-say-unarmed-black-man-ohio-traffic-stop-was-shot-60-times/?camp=bg:brief:rss:feedly&rss_id=feedly_rss_brief",
                "image_url": "https://bostonglobe-prod.cdn.arcpublishing.com/resizer/F5DVIwPGbJzTIJDelyWgugDcyno=/506x0/cloudfront-us-east-1.images.arcpublishing.com/bostonglobe/BX7XCMATROSBFQ4TRSBVDNXAAA.jpg",
                "language": "en",
                "published_at": "2022-07-04T01:54:33.000000Z",
                "source": "bostonglobe.com",
                "categories": [
                    "general"
                ],
                "locale": "us",
                "similar": [
                    {
                        "uuid": "00faa239-53ec-4594-84af-2ea4471ef567",
                        "title": "Black man was unarmed when 8 Ohio officers opened fire on him: Family lawyer",
                        "description": "As Ohio police officials are poised to release officer body-camera footage of a 25-year-old Black man killed in a hail of bullets fired by eight officers.",
                        "keywords": "",
                        "snippet": "Police body-camera footage of the shooting is expected to be released Sunday.\n\nWith Ohio police officials poised to release officer body-camera footage of a 25-...",
                        "url": "https://abcnews.go.com/US/black-man-unarmed-ohio-officers-opened-fire-family/story?id=86149929",
                        "image_url": "https://s.abcnews.com/images/US/jayland-walker-shooting-01-ht-llr-220703_1656859177296_hpMain_16x9_992.jpg",
                        "language": "en",
                        "published_at": "2022-07-03T17:04:52.000000Z",
                        "source": "abcnews.go.com",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "b0416dd8-9f46-454f-aa0f-545507d22fa8",
                        "title": "Police: Man shot was unarmed, officers feared he would fire",
                        "description": "Police say a Black man shot and killed by Akron police officers in a hail of bullets following a vehicle and foot pursuit was unarmed at the time of the shooting",
                        "keywords": "Human rights and civil liberties, Discrimination, Workplace discrimination, Business, Personnel, Social affairs, Social issues, Labor issues, Government and politics, Law enforcement agencies, Police, Law and order, Criminal investigations, General news, ",
                        "snippet": "Police say a Black man shot and killed by Akron police officers in a hail of bullets following a vehicle and foot pursuit was unarmed at the time of the shootin...",
                        "url": "https://abcnews.go.com/US/wireStory/police-man-shot-unarmed-officers-feared-fire-86157997",
                        "image_url": "https://s.abcnews.com/images/US/abc_news_default_2000x2000_update_16x9_992.jpg",
                        "language": "en",
                        "published_at": "2022-07-03T19:09:26.000000Z",
                        "source": "abcnews.go.com",
                        "categories": [
                            "general",
                            "politics"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "770c77a4-7a45-4947-a158-1d333359f597",
                        "title": "Police: Man shot was unarmed, officers feared he would fire",
                        "description": "AKRON, Ohio (AP) — A Black man shot and killed by Akron police officers in a hail of bullets following a vehicle and foot pursuit was unarmed at the time of the shooting, but a shot appeared to have come from the vehicle during the pursuit, and officers said they feared he was preparing to fire when they discharged their weapons, authorities said.",
                        "keywords": "Akron, AP Top News, U.S. News, Business, Fires, Police, Shootings, Ohio",
                        "snippet": "Protesters march along South High Street on Saturday, July 2, 2022, in Akron, Ohio, calling for justice for Jayland Walker after he was fatally shot by Akron Po...",
                        "url": "https://apnews.com/article/police-shootings-ohio-akron-829de644001793209e1c2dc3b2e22ca3",
                        "image_url": "https://storage.googleapis.com/afs-prod/media/d1734cbd68024ba0a3be3659ed937333/3000.jpeg",
                        "language": "en",
                        "published_at": "2022-07-03T20:23:03.000000Z",
                        "source": "apnews.com",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "4cbf8afd-484f-4a2e-a37b-f22dbe4185de",
                        "title": "Jayland Walker left his gun in the car. Then Akron police shot him 60 times.",
                        "description": "Authorities on Sunday released the shocking body camera footage from eight police officers shooting a Black man up to 60 times.",
                        "keywords": "",
                        "snippet": "Jayland Walker left his gun in the car. Then Akron police shot him 60 times. The video of Jayland Walker's death is another one that will traumatize people of c...",
                        "url": "https://www.usatoday.com/story/opinion/2022/07/03/akron-police-shooting-inflicts-more-trauma-people-color/7800020001/?gnt-cfr=1",
                        "image_url": "https://www.gannett-cdn.com/presto/2022/07/03/USAT/30b62f2d-b66d-4bf3-8bd5-18d4cdcc9d67-AP_Fatal_Police_Shooting_Ohio.jpg?auto=webp&crop=1999,1124,x0,y0&format=pjpg&width=1200",
                        "language": "en",
                        "published_at": "2022-07-03T22:22:11.000000Z",
                        "source": "usatoday.com",
                        "categories": [
                            "general",
                            "travel",
                            "sports"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "4eeb1375-0daf-4a29-b112-7759132b5677",
                        "title": "Videos of shooting of Ohio man by police raise more questions",
                        "description": "Following the release of the videos, hundreds of protesters marched in downtown Akron, demanding justice for Walker and decrying police violence, as Walker’s family urged the community to remain peaceful.",
                        "keywords": "",
                        "snippet": "Walker had one traffic ticket and no criminal record. Police said they initially sought to pull him over for an equipment violation and a traffic violation.\n\nTh...",
                        "url": "https://www.bostonglobe.com/2022/07/03/nation/videos-shooting-ohio-man-by-police-raise-more-questions/?camp=bg:brief:rss:feedly&rss_id=feedly_rss_brief",
                        "image_url": "https://bostonglobe-prod.cdn.arcpublishing.com/resizer/zuQd35pqVBp1vWL4VxQaqOPb7Fo=/506x0/cloudfront-us-east-1.images.arcpublishing.com/bostonglobe/G7J3SHAHZUVY63SWODB4KDWSJU.jpg",
                        "language": "en",
                        "published_at": "2022-07-04T00:21:10.000000Z",
                        "source": "bostonglobe.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.
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-07-04T03:30:02 | 2022-07-04T03:30 | 2022-07-04T03 | 2022-07-04 | 2022-07 | 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-07-04T03:30:02 | 2022-07-04T03:30 | 2022-07-04T03 | 2022-07-04 | 2022-07 | 2022
published_on false Find all articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2022-07-04
sort false Sort by published_on or relevance_score (only available when used in conjunction with search). Default is published_at unless search is used and sorting by published_at is not included, in which case relevance_score is used.
limit false Specify the number of articles you want to return in the request. The maximum limit is based on your plan. The default limit is the maximum specified for your plan.
page false Use this to paginate through the result set. Default is 1. Note that the max result set can't exceed 20,000. For example if your limit is 50, the max page you can have is 400 (50 * 400 = 20,000).
Example: page=2

Response Objects

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

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

Example Request

            
                GET https://api.thenewsapi.com/v1/news/top?api_token=YOUR_API_TOKEN&locale=us&limit=3
            
        

Example Response

            
                {
    "meta": {
        "found": 494277,
        "returned": 10,
        "limit": 10,
        "page": 1
    },
    "data": [
        {
            "uuid": "eea2a949-2536-4d85-95de-18550b764b5f",
            "title": "India bars Pulitzer-winning Kashmiri photojournalist from flying to France : news",
            "description": "24.9m members in the news community. The place for news articles about current events in the United States and the rest of the world. Discuss it all …",
            "keywords": "",
            "snippet": "We believe everyone on Reddit has something incredible to share. Let us help you express it.",
            "url": "https://www.reddit.com/r/news/comments/vquoqq/india_bars_pulitzerwinning_kashmiri/",
            "image_url": "https://external-preview.redd.it/7NVgiFzIvkPXSN3U_SncMAM3ET6Rv1Fr_Y25bJDHo0c.jpg?auto=webp&s=9d132bb6bee721ab3f3f9cb895ff89a95744748d",
            "language": "en",
            "published_at": "2022-07-04T03:18:43.000000Z",
            "source": "reddit.com",
            "categories": [
                "general",
                "politics"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "36812ae4-c507-43a6-9a2a-e40f321d431b",
            "title": "Fireworks technician injured in preparation for North Andover July 4th celebration",
            "description": "A technician was injured during set-up for the North Andover pre-Fourth of July fireworks display on Sunday afternoon, but the evening’s fireworks went on as ...",
            "keywords": "",
            "snippet": "A technician was injured during set-up for the North Andover pre-Fourth of July fireworks display on Sunday afternoon, but the evening’s fireworks went on as ...",
            "url": "https://www.bostonglobe.com/2022/07/03/metro/fireworks-technician-injured-preparation-north-andover-july-4th-celebration/?camp=bg:brief:rss:feedly&rss_id=feedly_rss_brief",
            "image_url": "https://www.bostonglobe.com/pf/resources/images/logo-bg.jpg?d=349",
            "language": "en",
            "published_at": "2022-07-04T03:02:50.000000Z",
            "source": "bostonglobe.com",
            "categories": [
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "6572aebc-4fcd-4ffa-b986-27a50975d8cf",
            "title": "After 3 feet of rain, 32,000 in Sydney area may need to flee",
            "description": "Parts of the city of 5 million people are facing a fourth flooding emergency in a year and a half after torrential rain since Friday caused dams to overflow and...",
            "keywords": "Australia, Floods",
            "snippet": "“The latest information we have is that there’s a very good chance that the flooding will be worse than any of the other three floods that those areas had i...",
            "url": "https://www.bostonglobe.com/2022/07/03/world/after-3-feet-rain-32000-sydney-area-may-need-flee/?camp=bg:brief:rss:feedly&rss_id=feedly_rss_brief",
            "image_url": "https://bostonglobe-prod.cdn.arcpublishing.com/resizer/kMTJhkhYIKw100X93x_ShgucpCI=/506x0/cloudfront-us-east-1.images.arcpublishing.com/bostonglobe/WVEHFFCZ5ES6O3UMP3S3A6DNRM.jpg",
            "language": "en",
            "published_at": "2022-07-04T03:01:12.000000Z",
            "source": "bostonglobe.com",
            "categories": [
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "6e10bbbc-ea4d-4841-8f4a-fc7ef2e7ebef",
            "title": "\"Endeavour\" creator on drying out the \"heroic drunk\" detective myth and plans for the series' end",
            "description": "Salon talks to series creator Russell Lewis about this season's sober view of Morse's love of whiskey and ale",
            "keywords": "",
            "snippet": "Endeavour Morse's affection for ale and whiskey is one of the character quirks Colin Dexter wrote into his detective in his novels. When John Thaw brought \"Insp...",
            "url": "https://www.salon.com/2022/07/03/endeavour-finale-season-8-russell-lewis-ending/",
            "image_url": "https://mediaproxy.salon.com/width/1200/https://media.salon.com/2022/07/endeavor-still05.jpg",
            "language": "en",
            "published_at": "2022-07-04T03:00:01.000000Z",
            "source": "salon.com",
            "categories": [
                "general",
                "politics",
                "entertainment"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "42308c06-f172-4e03-8814-02242b6bea31",
            "title": "Photos: Deadly shooting at mall in Copenhagen",
            "description": "A shooting at a mall in Copenhagen has left several people dead and at least three hospitalized, local authorities said Sunday.\nOne person, described as a 22-ye...",
            "keywords": "world, Photos: Deadly shooting at mall in Copenhagen",
            "snippet": "Olafur Steinar Gestsson/Ritzau Scanpix/AFP/Getty Images Police and other emergency services respond to reports of a shooting at the Field's shopping center in C...",
            "url": "https://www.cnn.com/2022/07/03/world/gallery/copenhagen-mall-shooting/index.html",
            "image_url": "https://cdn.cnn.com/cnnnext/dam/assets/220703224800-lead-denmark-shooting-fields-shopping-center-070322-super-tease.jpg",
            "language": "en",
            "published_at": "2022-07-04T02:59:43.000000Z",
            "source": "cnn.com",
            "categories": [
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "92619200-55c2-43a5-a6ab-6141a34dee79",
            "title": "‘Man Who Fell To Earth’s Chiwetel Ejiofor & EP Alex Kurtzman On Bowie’s Last Word In Tonight’s Season 1 Finale, A Season 2 & Why “Love Is Blind”",
            "description": "The end of Showtime's series & sequel to the Divine David starring 1976 film went very large tonight, with a look backwards & forwards",
            "keywords": "",
            "snippet": "SPOILER ALERT: This article contains details of tonight’s The Man Who Fell To Earth Season 1 finale. That’s all we got.\n\n“Maybe they’re not a bundle of ...",
            "url": "https://deadline.com/2022/07/bowie-man-who-fell-to-earth-finale-spoilers-chiwetel-ejiofor-alex-kurtzman-interview-1235057519/",
            "image_url": "https://deadline.com/wp-content/uploads/2022/07/MWFTE-S1-FINALE-2-SHOWTIME.jpeg?w=1024",
            "language": "en",
            "published_at": "2022-07-04T02:59:24.000000Z",
            "source": "deadline.com",
            "categories": [
                "entertainment"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "d5b06438-174b-4de7-a407-ed15c9dd65a4",
            "title": "Taiwan: China attack not imminent, but US watching closely, says Gen Milley : news",
            "description": "24.9m members in the news community. The place for news articles about current events in the United States and the rest of the world. Discuss it all …",
            "keywords": "",
            "snippet": "The place for news articles about current events in the United States and the rest of the world. Discuss it all here.",
            "url": "https://www.reddit.com/r/news/comments/vqx6dp/taiwan_china_attack_not_imminent_but_us_watching/",
            "image_url": "https://external-preview.redd.it/BRbYEt4v1HbEDWLyTH-VPEJB-PQ8dfati4G9oqi3iOo.jpg?auto=webp&s=7522236539404f5a77184b421f62da2388f204f9",
            "language": "en",
            "published_at": "2022-07-04T02:58:03.000000Z",
            "source": "reddit.com",
            "categories": [
                "general",
                "politics"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "b96291ae-38d5-440a-94fc-565c9e7f6abb",
            "title": "Boston civil rights leaders denounce white supremacist group that marched through city",
            "description": "Local civil rights leaders on Sunday denounced the white supremacist group Patriot Front a day after about 100 members marched through Boston carrying shields, ...",
            "keywords": "",
            "snippet": "“My reaction was and still is deep concern, because this is now the third demonstration we’ve had within the city limits [this year],” said Sullivan, who ...",
            "url": "https://www.bostonglobe.com/2022/07/03/metro/boston-civil-rights-leaders-denounce-white-supremacist-group-that-marched-through-city/?camp=bg:brief:rss:feedly&rss_id=feedly_rss_brief",
            "image_url": "https://www.bostonglobe.com/pf/resources/images/logo-bg.jpg?d=349",
            "language": "en",
            "published_at": "2022-07-04T02:51:32.000000Z",
            "source": "bostonglobe.com",
            "categories": [
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "f88bde36-ec6a-4332-bbba-a7149ab7ddf1",
            "title": "Eat Sheet: Our Tips on Where to Dine in Dublin",
            "description": "Many a visitor to Dublin finds themselves surprised by its culinary offerings. Now, you can make your choices easily.",
            "keywords": "Dublin, eat sheet",
            "snippet": "An explanation for our dining guide, Eat Sheet, can be found here. This week we bring you to Dublin, the capital of Ireland, which long ago pushed aside the isl...",
            "url": "https://www.thedailybeast.com/where-to-eat-in-dublin",
            "image_url": "https://img.thedailybeast.com/image/upload/c_crop,d_placeholder_euli9k,h_1688,w_3000,x_0,y_0/dpr_2.0/c_limit,w_740/fl_lossy,q_auto/v1656859451/220703-eat-sheet-dublin-hero_ojhycn",
            "language": "en",
            "published_at": "2022-07-04T02:37:56.000000Z",
            "source": "thedailybeast.com",
            "categories": [
                "general",
                "politics"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "afe09ea9-dbf0-4f26-a39d-37261f58e5de",
            "title": "Suspect dead after killing 2 and injuring 4, including 3 officers, in Haltom City shooting : news",
            "description": "74 votes, 10 comments. 24.9m members in the news community. The place for news articles about current events in the United States and the rest of …",
            "keywords": "",
            "snippet": "The place for news articles about current events in the United States and the rest of the world. Discuss it all here.",
            "url": "https://www.reddit.com/r/news/comments/vqrno4/suspect_dead_after_killing_2_and_injuring_4/",
            "image_url": "https://external-preview.redd.it/3XKdgSMmr1a2j4wMuLzh3hOYB6D4eO39B1k3YYvSxJo.jpg?auto=webp&s=f367b5e50be4a6e37255ca2dadde6d3023df923b",
            "language": "en",
            "published_at": "2022-07-04T02:37:50.000000Z",
            "source": "reddit.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.
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-07-04T03:30:02 | 2022-07-04T03:30 | 2022-07-04T03 | 2022-07-04 | 2022-07 | 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-07-04T03:30:02 | 2022-07-04T03:30 | 2022-07-04T03 | 2022-07-04 | 2022-07 | 2022
published_on false Find all articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2022-07-04
sort false Sort by published_on or relevance_score (only available when used in conjunction with search). Default is published_at unless search is used and sorting by published_at is not included, in which case relevance_score is used.
limit false Specify the number of articles you want to return in the request. The maximum limit is based on your plan. The default limit is the maximum specified for your plan.
page false Use this to paginate through the result set. Default is 1. Note that the max result set can't exceed 20,000. For example if your limit is 50, the max page you can have is 400 (50 * 400 = 20,000).
Example: page=2

Response Objects

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

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

Example Request

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

Example Response

            
                {
    "meta": {
        "found": 67274602,
        "returned": 10,
        "limit": 10,
        "page": 1
    },
    "data": [
        {
            "uuid": "1f882d24-ef99-4b12-aac6-54eccb560db4",
            "title": "任先生认为习不在乎中国经济,不在乎十多亿人的生计活路,也不在乎中国共产党,他是把他自己放在第一位的。这个看法与我一样。 任先生认为下半年或许会出一系列事情,任先生认为毛推迟开党代会,直到认为自己已经搞定全盘了,才在1969年开9大,习也有可能推迟开20大,直到他能搞定一切。 #推特中文圈, page 1",
            "description": "任先生认为习不在乎中国经济,不在乎十多亿人的生计活路,也不在乎中国共产党,他是把他自己放在第一位的。这个看?...",
            "keywords": "",
            "snippet": "",
            "url": "https://Lvv2.com/t/4050907",
            "image_url": "https://Lvv2.com/templates/default/images/favicon.ico",
            "language": "zh",
            "published_at": "2022-07-04T03:28:32.000000Z",
            "source": "Lvv2.com",
            "categories": [],
            "relevance_score": null
        },
        {
            "uuid": "b781150d-7cda-47cc-9f17-86e11090da63",
            "title": "蝙蝠 也是游泳健将 #gay, page 1",
            "description": "蝙蝠\n也是游泳健将",
            "keywords": "",
            "snippet": "Your browser does not support the video tag.",
            "url": "https://Lvv2.com/t/4050906",
            "image_url": "https://pbs.twimg.com/ext_tw_video_thumb/1542991697361117184/pu/img/Bg9J4bsIoH-7VzjM.jpg",
            "language": "zh",
            "published_at": "2022-07-04T03:28:21.000000Z",
            "source": "Lvv2.com",
            "categories": [],
            "relevance_score": null
        },
        {
            "uuid": "3c315806-33b2-470c-8784-fc6fa13f1261",
            "title": "Des champignons comme cadeau pour leur 1er logement",
            "description": "Deux Longueuillois devront attendre avant de goûter à la vie en appartement.",
            "keywords": "",
            "snippet": "Un jeune couple de Longueuil a été bouleversé de découvrir de la moisissure, un morceau de plafond mou et un important problème de plomberie au moment d’...",
            "url": "https://www.journaldequebec.com/2022/07/03/des-champignons-comme-cadeau-pour-leur-1er-logement",
            "image_url": "https://m1.quebecormedia.com/emp/emp/Cropsfce5bfff-c7dc-4d8b-9dad-f51393a2b344_ORIGINAL.jpg?impolicy=crop-resize&x=0&y=312&w=2000&h=826&width=1200",
            "language": "fr",
            "published_at": "2022-07-04T03:26:44.000000Z",
            "source": "journaldequebec.com",
            "categories": [
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "87c23104-e4e1-41b1-a454-f637aecfeb09",
            "title": "Des champignons comme cadeau pour leur 1er logement",
            "description": "Deux Longueuillois devront attendre avant de goûter à la vie en appartement.",
            "keywords": "",
            "snippet": "Un jeune couple de Longueuil a été bouleversé de découvrir de la moisissure, un morceau de plafond mou et un important problème de plomberie au moment d’...",
            "url": "https://www.journaldemontreal.com/2022/07/03/des-champignons-comme-cadeau-pour-leur-1er-logement",
            "image_url": "https://m1.quebecormedia.com/emp/emp/Cropsfce5bfff-c7dc-4d8b-9dad-f51393a2b344_ORIGINAL.jpg?impolicy=crop-resize&x=0&y=312&w=2000&h=826&width=1200",
            "language": "fr",
            "published_at": "2022-07-04T03:26:44.000000Z",
            "source": "journaldemontreal.com",
            "categories": [
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "a0952814-2768-4676-9b30-721eaea55bd3",
            "title": "Wheeler, Hoskins, Realmuto lift Phillies over Cardinals 4-0",
            "description": "PHILADELPHIA (AP) — Zack Wheeler threw seven shutout innings of four-hit ball and Rhys Hoskins and J...",
            "keywords": "baseball, sports, winnipeg news, winnioeg news, winnipeg free press, wpeg free press",
            "snippet": "PHILADELPHIA (AP) — Zack Wheeler threw seven shutout innings of four-hit ball and Rhys Hoskins and J.T. Realmuto slugged home runs as the Philadelphia Phillie...",
            "url": "https://www.winnipegfreepress.com/sports/baseball/wheeler-hoskins-realmuto-lift-phillies-over-cardinals-4-0-576642602.html",
            "image_url": "https://media.winnipegfreepress.com/images/20220703220724-62c24f80c73af26b62213d04jpeg.jpg",
            "language": "en",
            "published_at": "2022-07-04T03:26:35.000000Z",
            "source": "winnipegfreepress.com",
            "categories": [
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "ca4a1319-d444-4f04-b92e-eb5fa30a255a",
            "title": "Highlighting the invisible labor of domestic women",
            "description": "Jennifer Siebel-Newsom joins 'The Next Revolution' to discuss her new documentary 'Fair Play.'",
            "keywords": "",
            "snippet": "",
            "url": "https://video.foxnews.com/v/6309084094112/",
            "image_url": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/694940094001/7c7bbe61-309b-4620-a15e-b179cd36fae7/5b77269f-ea18-4530-ac8e-5f5394f5fb51/1280x720/match/image.jpg",
            "language": "en",
            "published_at": "2022-07-04T03:26:16.000000Z",
            "source": "video.foxnews.com",
            "categories": [
                "general",
                "tech"
            ],
            "relevance_score": null
        },
        {
            "uuid": "dd0fcdb3-0a5c-4d05-bda6-a6bdb7c07c18",
            "title": "谢谢大家送上的生日祝福 那,我们来切蛋糕吧~ (你学fei了吗 #币圈, page 1",
            "description": "谢谢大家送上的生日祝福\n那,我们来切蛋糕吧~\n\n(你学fei了吗",
            "keywords": "",
            "snippet": "",
            "url": "https://Lvv2.com/t/4050904",
            "image_url": "https://pbs.twimg.com/media/FWwvyykagAA6lk4.jpg",
            "language": "zh",
            "published_at": "2022-07-04T03:26:11.000000Z",
            "source": "Lvv2.com",
            "categories": [],
            "relevance_score": null
        },
        {
            "uuid": "ebbbb927-18a3-4adf-98f8-47ed66dcabc8",
            "title": "La rédemption pour Dylan Groenewegen",
            "description": "Le Néerlandais remporte la 3e étape deux ans après avoir failli causer la mort de Fabio Jakobsen.",
            "keywords": "",
            "snippet": "SONDERBORG | Trois ans après son dernier succès sur le Tour de France, le Néerlandais Dylan Groenewegen a chassé les démons de sa longue suspension en remp...",
            "url": "https://www.journaldemontreal.com/2022/07/03/la-redemption-pour-dylan-groenewegen",
            "image_url": "https://m1.quebecormedia.com/emp/emp/Groenewegen4c82da2d-0f5b-471c-80e0-2a42f4aa4f90_ORIGINAL.jpg?impolicy=crop-resize&x=0&y=61&w=2000&h=822&width=1200",
            "language": "fr",
            "published_at": "2022-07-04T03:26:01.000000Z",
            "source": "journaldemontreal.com",
            "categories": [
                "sports"
            ],
            "relevance_score": null
        },
        {
            "uuid": "bf945bdb-5011-4211-bfd9-322f2b7821a9",
            "title": "2024 election must be about economic 'policy' because America is at a 'turning point'",
            "description": "Kevin Warsh, a Hoover Institution visiting fellow, talks about his proposed economic plan and how it aims to solve America's economic problems on 'The Next Revo...",
            "keywords": "",
            "snippet": "",
            "url": "https://video.foxnews.com/v/6309080832112/",
            "image_url": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/694940094001/91ddc856-1c98-4b1f-87f9-7f2d6033938f/f1f49bbe-22b3-4f26-8b76-3059d986d1ac/1280x720/match/image.jpg",
            "language": "en",
            "published_at": "2022-07-04T03:25:35.000000Z",
            "source": "video.foxnews.com",
            "categories": [
                "general",
                "tech"
            ],
            "relevance_score": null
        },
        {
            "uuid": "df9b776d-7090-405e-b2c6-b3e5a6ce8883",
            "title": "小說改篇動畫《無職轉生》第二季 新預告2023年開播",
            "description": "根據同名人氣輕小說改編的新番TV動畫《無職轉生:到了異世界就拿出真本事》第二季官方宣布將於2023年開播,最新先導?...",
            "keywords": "小說改篇動畫《無職轉生》第二季 新預告2023年開播",
            "snippet": "根據同名人氣輕小說改編的新番TV動畫《無職轉生:到了異世界就拿出真本事》第二季官方宣布將於2023年開播,最新先導?...",
            "url": "https://www.gameapps.hk/news/51078/Mushoku-Tensei-Jobless-Reincarnation-2023",
            "image_url": "https://image.gameapps.hk/images/202207/04/01.jpg",
            "language": "zh",
            "published_at": "2022-07-04T03:25:00.000000Z",
            "source": "gameapps.hk",
            "categories": [
                "tech"
            ],
            "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-07-04T03:30:02 | 2022-07-04T03:30 | 2022-07-04T03 | 2022-07-04 | 2022-07 | 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-07-04T03:30:02 | 2022-07-04T03:30 | 2022-07-04T03 | 2022-07-04 | 2022-07 | 2022
published_on false Find all articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2022-07-04
limit false Specify the number of articles you want to return in the request. The maximum limit is based on your plan. The default limit is the maximum specified for your plan.
page false Use this to paginate through the result set. Default is 1. Note that the max result set can't exceed 20,000. For example if your limit is 50, the max page you can have is 400 (50 * 400 = 20,000).
Example: page=2

Response Objects

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

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

Example Request

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

Example Response

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

News by UUID Available on: All plans

Endpoint

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

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

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

All text data returned is UTF-8.

All dates are in UTC (GMT).

HTTP GET Parameters

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

Response Objects

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

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

Example Request

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

Example Response

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

Sources Available on: All plans

Endpoint

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

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

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

All text data returned is UTF-8.

HTTP GET Parameters

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

Response Objects

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

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

Example Request

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

Example Response

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

Errors

Errors

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

Errors

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

Example Error Response

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

Examples

API Examples

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

Example Request 1

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

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

Example Request 2

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

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

Example Request 3

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

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

Example Request 4

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

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

Example Request 5

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

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

Example Request 6

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

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

Code Examples

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

PHP

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

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

        $json = curl_exec($ch);

        curl_close($ch);

        $apiResult = json_decode($json, true);

        print_r($apiResult);
    

Python

    
        # Python 3
        import http.client, urllib.parse

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

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

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

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

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

Go

    
        package main

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

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

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

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

            baseURL.RawQuery = params.Encode()

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

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

            defer res.Body.Close()

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

            fmt.Println(string(body))
        }
    

JavaScript

    
        var requestOptions = {
            method: 'GET'
        };

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

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

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

C#

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

        var request = new RestRequest(Method.GET);

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

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

Java

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

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

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

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

More

Stock Market News APIs

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