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-05-21
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": "82e47031-77d3-4609-88b0-d97a3891b0d4",
                "title": "Florida shatters record for international tourism market share",
                "description": "Roughly 45% of all international visitors last year to America touched down in Florida.",
                "keywords": "News, ron desantis, tourism",
                "snippet": "Florida shattered the record for the state with the highest share of international tourism in 2021, eclipsing the prior mark set by New York back in 2011, offic...",
                "url": "https://nypost.com/2022/05/20/florida-shatters-record-for-international-tourism-share/",
                "image_url": "https://nypost.com/wp-content/uploads/sites/2/2022/05/florida-tourism-comp-1.jpg?quality=75&strip=all&w=1024",
                "language": "en",
                "published_at": "2022-05-20T17:48:25.000000Z",
                "source": "nypost.com",
                "categories": [
                    "general"
                ],
                "locale": "us",
                "similar": [
                    {
                        "uuid": "bb41b15c-15b5-4d69-9810-2ad2381ccb69",
                        "title": "DeSantis-backed congressional map in Florida reinstated by appeals court",
                        "description": "A Florida appeals court has reinstated the congressional map Republican Gov. Ron DeSantis signed into law last month, allowing the controversial new district boundaries to take effect for now.",
                        "keywords": "",
                        "snippet": "At left, J. Alex Kelly, deputy chief of staff to Florida Gov. Ron DeSantis, answers questions about the new congressional district lines his office developed du...",
                        "url": "https://www.cnn.com/2022/05/20/politics/florida-congressional-map-ron-desantis/index.html",
                        "image_url": "https://media.cnn.com/api/v1/images/stellar/prod/220511130826-02-florida-redistricting-desantis.jpg?c=16x9&q=w_800,c_fill",
                        "language": "en",
                        "published_at": "2022-05-20T18:00:07.000000Z",
                        "source": "cnn.com",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "76f1ed9a-b255-4162-8910-913a84a52df1",
                        "title": "Racist photo leads to punishment for Florida students",
                        "description": "Officials say a group of Florida students posed for a photo outside a middle school while holding large letters that spelled out a racial slur",
                        "keywords": "Education issues, School discipline, Human rights and civil liberties, Discrimination, Racial and ethnic discrimination, Social issues, Race and ethnicity, African-Americans, Social affairs, Education, Primary and secondary education, General news, North",
                        "snippet": "Officials say a group of Florida students posed for a photo outside a middle school while holding large letters that spelled out a racial slur\n\nPALM CITY, Fla. ...",
                        "url": "https://abcnews.go.com/US/wireStory/racist-photo-leads-punishment-florida-students-84866935",
                        "image_url": "https://abcnews.go.com/US/wireStory/null",
                        "language": "en",
                        "published_at": "2022-05-20T19:55:51.000000Z",
                        "source": "abcnews.go.com",
                        "categories": [
                            "general",
                            "politics"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "e7dd5b02-cded-487e-90a1-87c789bd395d",
                        "title": "Florida family finds nearly 11-foot alligator in pool",
                        "description": "A large alligator was found swimming in the pool at a family home in Charlotte County, Florida, before officers removed the animal off the property.",
                        "keywords": "",
                        "snippet": "NEW You can now listen to Fox News articles!\n\nA family in Florida had an unexpected guest stop by their home for a swim this week.\n\nAn almost-11-foot alligator ...",
                        "url": "https://www.foxnews.com/lifestyle/11-foot-alligator-florida-pool",
                        "image_url": "https://static.foxnews.com/foxnews.com/content/uploads/2022/05/Gator-Charlotte-County-Sheriffs-Office-display-crop.jpg",
                        "language": "en",
                        "published_at": "2022-05-20T20:06:30.000000Z",
                        "source": "foxnews.com",
                        "categories": [
                            "general",
                            "politics"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "d5780349-0e94-4dcc-bf66-0859f97eb41e",
                        "title": "Florida wants to avoid critical race theory and ‘social justice’ in social studies texts",
                        "description": "Florida education officials, in guidance, told publishers that all proposed social studies content must abide by the state’s rules outlawing critical race theory and similar teachings.",
                        "keywords": "",
                        "snippet": "Florida education officials, in the guidance, told publishers that all proposed social studies content must abide by the state’s rules outlawing critical race...",
                        "url": "https://www.politico.com/news/2022/05/20/florida-critical-race-theory-social-justice-social-studies-00034104",
                        "image_url": "https://static.politico.com/65/2b/1e1231ad408caafd5eb0221ce47b/20200527-textbooks-getty-773.jpg",
                        "language": "en",
                        "published_at": "2022-05-20T19:59:23.000000Z",
                        "source": "politico.com",
                        "categories": [
                            "politics",
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "8a42b416-1e45-4626-84bb-cc024b2a4804",
                        "title": "Deputy should be charged after Florida man is burned in fire ignited by stun gun, sheriff says",
                        "description": "Charges should be filed against both the deputy who used a stun gun on a man covered in gasoline and the man who was burned when a fire ignited, a Florida sheriff said Thursday.",
                        "keywords": "",
                        "snippet": "Charges should be filed against both the deputy who used a stun gun on a man covered in gasoline and the man who was burned when a fire ignited, a Florida sheri...",
                        "url": "https://www.nbcnews.com/news/us-news/florida-deputy-charged-man-covered-gasoline-cooked-alive-fire-sparked-rcna29783",
                        "image_url": "https://media-cldnry.s-nbcnews.com/image/upload/t_nbcnews-fp-1200-630,f_auto,q_auto:best/rockcms/2022-05/220518-jean-barreto-mjf-1144-fea4d9.jpg",
                        "language": "en",
                        "published_at": "2022-05-20T19:15:51.000000Z",
                        "source": "news.google.com",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    }
                ]
            },
            {
                "uuid": "5ae686b6-8273-4640-abc0-741d2968f27c",
                "title": "Tornado strikes northern Michigan; damage yet unknown",
                "description": "A tornado has struck in Michigan’s northern Lower Peninsula",
                "keywords": "Property damage, Accidents and disasters, Natural disasters, Tornadoes, General news, Weather, Detroit, North America, United States, Michigan",
                "snippet": "A tornado has struck in Michigan’s northern Lower Peninsula\n\nGAYLORD, Mich. -- A tornado struck Michigan's northern Lower Peninsula on Friday, the National We...",
                "url": "https://abcnews.go.com/US/wireStory/tornado-strikes-northern-michigan-damage-unknown-84867849",
                "image_url": "https://abcnews.go.com/US/wireStory/null",
                "language": "en",
                "published_at": "2022-05-20T20:43:11.000000Z",
                "source": "abcnews.go.com",
                "categories": [
                    "general",
                    "politics"
                ],
                "locale": "us",
                "similar": [
                    {
                        "uuid": "bff4e1f0-0a22-485b-ac2c-08960dddbdf4",
                        "title": "Michigan tornado causes 'catastrophic' damage",
                        "description": "A tornado quickly moved through Gaylord in the northern Lower Peninsula of Michigan, on Friday afternoon, according to Lt. Jim Gorno of the Michigan Department of Natural Resources.",
                        "keywords": "weather, Michigan tornado causes 'catastrophic' damage - CNN",
                        "snippet": "(CNN) A tornado quickly moved through Gaylord in the northern Lower Peninsula of Michigan, on Friday afternoon, according to Lt. Jim Gorno of the Michigan Depar...",
                        "url": "https://www.cnn.com/2022/05/20/weather/severe-weather-friday-wxn/index.html",
                        "image_url": "https://cdn.cnn.com/cnnnext/dam/assets/220520172731-01-gaylord-michigan-tornado-damage-0520-super-tease.jpg",
                        "language": "en",
                        "published_at": "2022-05-20T21:34:33.000000Z",
                        "source": "cnn.com",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "d9a85993-1916-4829-86b1-02d6df0eb816",
                        "title": "Tornado in Northern Michigan Damages Homes and Businesses",
                        "description": "The Michigan State Police said that trees and power lines were blocking roadways and reported that “multiple homes and businesses” were damaged in Gaylord, a city of about 4,000.",
                        "keywords": "",
                        "snippet": "A tornado swept through northern Michigan on Friday, damaging multiple homes and businesses, the authorities said.\n\nThe extent of damage and injuries was not im...",
                        "url": "https://www.nytimes.com/2022/05/20/us/northern-michigan-tornado.html",
                        "image_url": "https://static01.nyt.com/images/2022/05/20/multimedia/20xp-tornado-01/20xp-tornado-01-facebookJumbo.jpg",
                        "language": "en",
                        "published_at": "2022-05-20T21:49:45.000000Z",
                        "source": "nytimes.com",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "4d8c1219-c38d-4a27-a4ee-acac0555d731",
                        "title": "A tornado swept through Paderborn, Germany, and injured at least 30 people, authorities said",
                        "description": "A tornado swept through the German city of Paderborn Friday, injuring at least 30 people, authorities said, and blew away roofs, toppled trees and sent debris flying for miles.",
                        "keywords": "europe, A tornado swept through Paderborn, Germany, and injured at least 30 people, authorities said - CNN",
                        "snippet": "(CNN) A tornado swept through the German city of Paderborn Friday, injuring at least 30 people, authorities said, and blew away roofs, toppled trees and sent de...",
                        "url": "https://www.cnn.com/2022/05/20/europe/paderborn-germany-tornado/index.html",
                        "image_url": "https://cdn.cnn.com/cnnnext/dam/assets/220520172718-paderborn-storm-restricted-052022-super-tease.jpg",
                        "language": "en",
                        "published_at": "2022-05-20T22:20:03.000000Z",
                        "source": "cnn.com",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "3c22a238-59d0-4844-a4c0-cd91d942aefe",
                        "title": "Teacher at Michigan school on leave after assignment shows former President Obama with animals",
                        "description": "A teacher at a school in Michigan has been placed on leave over an assignment showing former President Barack Obama with monkeys.",
                        "keywords": "",
                        "snippet": "Teacher at Michigan school on leave after assignment shows former President Obama with animals\n\nShow Caption Hide Caption 'Stay in Mexico' remark disrupts schoo...",
                        "url": "https://www.usatoday.com/story/news/education/2022/05/20/michigan-teacher-barack-obama-primates/9860121002/",
                        "image_url": "https://www.gannett-cdn.com/presto/2021/09/28/USAT/d6bdeeed-1ab7-4c3f-b20e-1ed8a255bf5d-AFP_AFP_9NQ223.jpg?auto=webp&crop=4027,2266,x0,y134&format=pjpg&width=1200",
                        "language": "en",
                        "published_at": "2022-05-20T21:26:32.000000Z",
                        "source": "usatoday.com",
                        "categories": [
                            "general",
                            "travel",
                            "sports"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "900d6023-231b-40d6-8a7c-6dcbee1190f7",
                        "title": "'Heavy damage' reported after tornado strikes northern Michigan",
                        "description": "Multiple people were injured after a destructive tornado tore through northern Michigan Friday afternoon, authorities said.",
                        "keywords": "",
                        "snippet": "No fatalities have been reported so far, police said.\n\nMultiple people were injured and \"heavy damage\" reported after a destructive tornado tore through norther...",
                        "url": "https://abcnews.go.com/US/heavy-damage-reported-tornado-strikes-northern-michigan/story?id=84869605",
                        "image_url": "https://s.abcnews.com/images/US/tornado-michigan-ap-jt-220520_1653086705124_hpMain_16x9_992.jpg",
                        "language": "en",
                        "published_at": "2022-05-21T00:05:25.000000Z",
                        "source": "abcnews.go.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-05-21T03:24:22 | 2022-05-21T03:24 | 2022-05-21T03 | 2022-05-21 | 2022-05 | 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-05-21T03:24:22 | 2022-05-21T03:24 | 2022-05-21T03 | 2022-05-21 | 2022-05 | 2022
published_on false Find all articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2022-05-21
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": 498231,
        "returned": 10,
        "limit": 10,
        "page": 1
    },
    "data": [
        {
            "uuid": "a0cd70f0-e6df-426a-91b3-eecd0312c37d",
            "title": "Giuliani meets with Jan. 6 committee for over 7 hours",
            "description": "Rudy Giuliani, who helped lead Donald Trump’s efforts to overturn the results of the 2020 election as his personal lawyer, sat Friday for a lengthy interview ...",
            "keywords": "",
            "snippet": "It was unclear what Giuliani told the committee, but his centrality to Trump’s various attempts to subvert the election made him a potentially pivotal witness...",
            "url": "https://www.bostonglobe.com/2022/05/20/nation/giuliani-meets-with-jan-6-committee-over-7-hours/?camp=bg:brief:rss:feedly&rss_id=feedly_rss_brief",
            "image_url": "https://bostonglobe-prod.cdn.arcpublishing.com/resizer/uddKSdhY70MYq3Dp5IHgo-uWo50=/506x0/cloudfront-us-east-1.images.arcpublishing.com/bostonglobe/MI37Q7TOP4BMIDSDKJJM2DOMNM.jpg",
            "language": "en",
            "published_at": "2022-05-21T03:06:24.000000Z",
            "source": "bostonglobe.com",
            "categories": [
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "0d1c42b3-31ea-4b8a-a501-4e2c9008ac36",
            "title": "Four teenage boys face charges of setting off fireworks in downtown Boston",
            "description": "Police responded at 3:27 p.m. to a report of a large explosion near Summer and Arch streets downtown and spoke there with several witnesses who said a group of ...",
            "keywords": "",
            "snippet": "Four teenage boys are facing juvenile charges of using an incendiary device after witnesses said they set off fireworks in downtown Boston on Friday afternoon, ...",
            "url": "https://www.bostonglobe.com/2022/05/20/metro/four-teenage-boys-face-charges-setting-off-fireworks-downtown-boston/?camp=bg:brief:rss:feedly&rss_id=feedly_rss_brief",
            "image_url": "https://www.bostonglobe.com/pf/resources/images/logo-bg.jpg?d=337",
            "language": "en",
            "published_at": "2022-05-21T03:00:20.000000Z",
            "source": "bostonglobe.com",
            "categories": [
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "f5858c24-9d08-4e42-ae3d-61b52eb46898",
            "title": "CDC urges adults 50 and older to get a 2nd booster",
            "description": "In a sign of growing concern among federal health officials about the spread of new coronavirus infections, the Centers for Disease Control and Prevention is no...",
            "keywords": "",
            "snippet": "Previously, the agency said those 50 and older had the option of the additional shot but only encouraged people older than 65 or with underlying medical conditi...",
            "url": "https://www.bostonglobe.com/2022/05/20/nation/cdc-urges-adults-50-older-get-2nd-booster/?camp=bg:brief:rss:feedly&rss_id=feedly_rss_brief",
            "image_url": "https://bostonglobe-prod.cdn.arcpublishing.com/resizer/rbsoJi5Mwcte_WFWzD9eFqQmkvQ=/506x0/cloudfront-us-east-1.images.arcpublishing.com/bostonglobe/UYRTW7QNSJMS3I5AIBNBUCRQKM.jpg",
            "language": "en",
            "published_at": "2022-05-21T02:56:31.000000Z",
            "source": "bostonglobe.com",
            "categories": [
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "8689d0fb-0fac-488d-946f-5deb06515178",
            "title": "Ex-MMA fighter William Cassoday chokes out man attacking Indiana cop",
            "description": "Former MMA fighter William Cassoday put suspect Christopher Delgado in a chokehold when he saw him attacking Porter County Sheriff's Office patrolman Jamison Sm...",
            "keywords": "News, indiana, mma, police",
            "snippet": "A former mixed martial arts competitor jumped into action to takedown a man that was fighting a cop on the side of the road in Indiana, a report said.\n\nWilliam ...",
            "url": "https://nypost.com/2022/05/20/mma-fighter-william-cassoday-chokes-man-attacking-cop/",
            "image_url": "https://nypost.com/wp-content/uploads/sites/2/2022/05/mma-rescues-cop-138.jpg?quality=75&strip=all&w=1024",
            "language": "en",
            "published_at": "2022-05-21T02:52:35.000000Z",
            "source": "nypost.com",
            "categories": [
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "7ec8cead-c3e0-41fa-ab2e-0b5f0aedda93",
            "title": "Biden's push for more government spending, more regulation will be 'jet fuel' on inflation: Ryun",
            "description": "Ned Ryun says says President Biden's solution to solving inflation will be 'jet fuel' on",
            "keywords": "",
            "snippet": "NEW You can now listen to Fox News articles!\n\nAmerican Majority CEO Ned Ryun said that many on the left do not care about the priorities of the American people ...",
            "url": "https://www.foxnews.com/media/biden-government-spending-regulation-jet-fuel-inflation-ryun",
            "image_url": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/694940094001/d2475677-4bcd-42fd-988c-b1eefa118ea4/eebc3042-54fb-45bc-b017-a353f1150ec2/1280x720/match/image.jpg",
            "language": "en",
            "published_at": "2022-05-21T02:41:15.000000Z",
            "source": "foxnews.com",
            "categories": [
                "general",
                "politics"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "3087ffc9-6d8f-4c2b-9d67-a7ff6f347eb0",
            "title": "Migrants stay in 'waiting rooms' along US border: Here's a closer look",
            "description": "Migrants waiting to cross the U.S.-Mexico border have been staying in hundreds of makeshift camps. The Texas Department of Public Safety gave Fox News a firstha...",
            "keywords": "",
            "snippet": "NEW You can now listen to Fox News articles!\n\nThe Texas Department of Public Safety gave Fox News a closer look at the status of thousands of migrants waiting t...",
            "url": "https://www.foxnews.com/world/title-42-decision-looms-migrants-stay-waiting-rooms-us-border-closer-look",
            "image_url": "https://static.foxnews.com/foxnews.com/content/uploads/2022/05/Screen-Shot-2022-05-19-at-11.52.11-PM.png",
            "language": "en",
            "published_at": "2022-05-21T02:36:22.000000Z",
            "source": "foxnews.com",
            "categories": [
                "general",
                "politics"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "0df03205-734e-4451-8057-9bfb3ba9920a",
            "title": "‘This Is Us’ Series Finale Photos: The Pearsons Gather One Last Time To Pay Tribute To Rebecca",
            "description": "The end is near for NBC's celebrated family drama This Is Us, and NBC has released first-look images for the May 24 series finale,",
            "keywords": "",
            "snippet": "The end is near for NBC’s celebrated family drama This Is Us, and NBC has released first-look images for the May 24 series finale, “Us.”\n\nIn it, The Big T...",
            "url": "https://deadline.com/2022/05/this-is-us-series-finale-photos-spoilers-rebecca-funeral-big-three-1235029501/",
            "image_url": "https://deadline.com/wp-content/uploads/2022/05/NUP_197545_02695.jpg?w=1000",
            "language": "en",
            "published_at": "2022-05-21T02:35:38.000000Z",
            "source": "deadline.com",
            "categories": [
                "entertainment"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "c55da43c-4ae2-4a04-a864-08a3b7115981",
            "title": "Clinton campaign manager drops 'bombshell' exposing Clinton and media mob's years-long Russia hoax",
            "description": "Fox News legal analyst George Jarrett weighed in on 'bombshell' revelation in the Durham probe on",
            "keywords": "",
            "snippet": "NEW You can now listen to Fox News articles!\n\nFox News legal analyst George Jarrett walked viewers through Robby Mook's testimony in the Trump-Russia trial Frid...",
            "url": "https://www.foxnews.com/media/clinton-campaign-manager-media-russia-hoax",
            "image_url": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/694940094001/cd062a53-5ef7-4211-a374-47644bab0615/4af75729-604f-4f6b-a9f0-1ee26b186b34/1280x720/match/image.jpg",
            "language": "en",
            "published_at": "2022-05-21T02:17:44.000000Z",
            "source": "foxnews.com",
            "categories": [
                "general",
                "politics"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "ce6feb44-32a6-4322-9988-1b81805da22c",
            "title": "Opinion: Dark clouds are on the horizon for Democrats",
            "description": "Julian Zelizer writes since the beginning of President Joe Biden's mandate, the Democrats' future has looked ugly. Now it's even worse.",
            "keywords": "opinions, Opinion: Dark clouds are on the horizon for Democrats - CNN",
            "snippet": "Julian Zelizer, a CNN political analyst, is a professor of history and public affairs at Princeton University. He is the author and editor of 24 books, includin...",
            "url": "https://www.cnn.com/2022/05/20/opinions/joe-biden-democrats-november-midterms-zelizer/index.html",
            "image_url": "https://cdn.cnn.com/cnnnext/dam/assets/220518232115-biden-cumbre-invitacion-cuba-venezuela-nicaragua-super-tease.jpg",
            "language": "en",
            "published_at": "2022-05-21T02:11:27.000000Z",
            "source": "cnn.com",
            "categories": [
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "b1651f79-7dc1-4c49-b754-48e358f37f8c",
            "title": "Migrants allowed into US despite Title 42 now face homelessness",
            "description": "To combat migrants coming into the US, a judge has ruled Title 42 must stay in place, but migrants who were allowed into the country despite Title 42 face anoth...",
            "keywords": "politics, Migrants allowed into US despite Title 42 now face homelessness - CNN Video",
            "snippet": "To combat migrants coming into the US, a judge has ruled Title 42 must stay in place, but migrants who were allowed into the country despite Title 42 face anoth...",
            "url": "https://www.cnn.com/videos/politics/2022/05/21/homeless-migrants-title-42-flores-dnt-ebof-vpx.cnn",
            "image_url": "https://cdn.cnn.com/cnnnext/dam/assets/220520212852-migrant-homelessness-05-20-22-super-tease.jpg",
            "language": "en",
            "published_at": "2022-05-21T02:10:29.000000Z",
            "source": "cnn.com",
            "categories": [
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        }
    ]
}
            
        

All News Available on: All plans

Endpoint

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

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

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

All text data returned is UTF-8.

All dates are in UTC (GMT).

HTTP GET Parameters

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

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

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

For more advanced query examples, see our API Examples section.
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-05-21T03:24:22 | 2022-05-21T03:24 | 2022-05-21T03 | 2022-05-21 | 2022-05 | 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-05-21T03:24:22 | 2022-05-21T03:24 | 2022-05-21T03 | 2022-05-21 | 2022-05 | 2022
published_on false Find all articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2022-05-21
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": 68556276,
        "returned": 10,
        "limit": 10,
        "page": 1
    },
    "data": [
        {
            "uuid": "ec6a8792-20c6-4313-9ad3-350311fed59a",
            "title": "震惊! 第一剂86.61%, 第二剂81.21%, 加强针都打了63.81% 没有被中共攻下来,台湾政府却自己带着全台湾跳进了毒苗的陷阱,实在是太悲哀了! #键政, page 1",
            "description": "震惊!\n第一剂86.61%,\n第二剂81.21%,\n加强针都打了63.81%\n\n没有被中共攻下来,台湾政府却自己带着全台湾跳进了毒苗的陷阱,...",
            "keywords": "",
            "snippet": "",
            "url": "https://Lvv2.com/t/3932863",
            "image_url": "https://pbs.twimg.com/media/FTOGDzracAEufN6.jpg",
            "language": "zh",
            "published_at": "2022-05-21T03:24:32.000000Z",
            "source": "Lvv2.com",
            "categories": [],
            "relevance_score": null
        },
        {
            "uuid": "39b1db8e-63eb-43e7-a7c9-e8208bce9c4c",
            "title": "居然……这样子就把迷你杯插破了吗,那就接着撸好了——",
            "description": "居然……这样子就把迷你杯插破了吗,那就接着撸好了——",
            "keywords": "",
            "snippet": "Your browser does not support the video tag.",
            "url": "https://Lvv2.com/t/3932862",
            "image_url": "https://pbs.twimg.com/ext_tw_video_thumb/1527710569670664193/pu/img/1tdocKuo4ZFb-yc2.jpg",
            "language": "zh",
            "published_at": "2022-05-21T03:24:21.000000Z",
            "source": "Lvv2.com",
            "categories": [],
            "relevance_score": null
        },
        {
            "uuid": "0aeb7a42-3e01-4a17-9d8c-2bca2e6b08fe",
            "title": "好多毛的直男。 真是毛多。原创",
            "description": "好多毛的直男。 真是毛多。原创",
            "keywords": "",
            "snippet": "Your browser does not support the video tag.",
            "url": "https://Lvv2.com/t/3932861",
            "image_url": "https://pbs.twimg.com/ext_tw_video_thumb/1527711232626524161/pu/img/8i3BF_M7Fkt1Rbh8.jpg",
            "language": "zh",
            "published_at": "2022-05-21T03:24:11.000000Z",
            "source": "Lvv2.com",
            "categories": [],
            "relevance_score": null
        },
        {
            "uuid": "ec7a7f10-fcc0-4e12-b591-2824c6a66dc5",
            "title": "Most Popular Singers May 2022: Lim Young Woong, BTS, More!",
            "description": "From Lim Young Woong to BTS, read to know the full list of the most popular singers for May 2022!\r\n\r\n#BrandReputation #brandreputationrankings #reputationrankin...",
            "keywords": "BTS, Psy, IU, BLACKPINK, Red Velvet, seventeen, Starship Entertainment, Oh My Girl, Kang Daniel, BigBang, Big Bang, SM Entertainment, Lee Seung Gi, Jessi, Jannabi, EXO, Brave Girls",
            "snippet": "On May 21 KST, the Korean Business Research Institute announced the brand reputation rankings for singers for the month of May this year. From Lim Young Woong t...",
            "url": "https://www.kpopstarz.com/articles/306779/20220520/popular-singers-2022-lim-young-woong-bts-more.htm",
            "image_url": "https://1409791524.rsc.cdn77.org/data/images/full/613327/lim-young-woong-bts-psy.jpg",
            "language": "en",
            "published_at": "2022-05-21T03:23:50.000000Z",
            "source": "kpopstarz.com",
            "categories": [
                "entertainment"
            ],
            "relevance_score": null
        },
        {
            "uuid": "2da367e3-bced-495a-abe2-00f3c7b49100",
            "title": "Blue Jays eke out win behind Ryu, Springer and Bichette, Votto makes emotional return",
            "description": "Joey Votto's profile certainly fits a need for the Blue Jays, who rode an RBI single from George Springer, run-scoring double from Bo Bichette and six shutout i...",
            "keywords": "",
            "snippet": "TORONTO – Joey Votto described himself as being at his most excited when home, so much so that the feeling left him with goosebumps and cost him sleep.\n\nHe gr...",
            "url": "https://www.sportsnet.ca/mlb/article/blue-jays-eke-out-win-behind-ryu-springer-and-bichette-votto-makes-emotional-return/",
            "image_url": "https://www.sportsnet.ca/wp-content/uploads/2022/05/Bichette-2-1040x572.jpg",
            "language": "en",
            "published_at": "2022-05-21T03:21:30.000000Z",
            "source": "sportsnet.ca",
            "categories": [
                "sports"
            ],
            "relevance_score": null
        },
        {
            "uuid": "a6502e9d-eacb-4fe6-b9bd-b3cc06d67434",
            "title": "Thankful Melvin happy to be back in Padres dugout",
            "description": "SAN FRANCISCO (AP) — A smiling and thankful Bob Melvin returned to manage the San Diego Padres for t...",
            "keywords": "baseball, sports, winnipeg news, winnioeg news, winnipeg free press, wpeg free press",
            "snippet": "SAN FRANCISCO (AP) — A smiling and thankful Bob Melvin returned to manage the San Diego Padres for the start of a three-game series in San Francisco on Friday...",
            "url": "https://www.winnipegfreepress.com/sports/baseball/thankful-melvin-happy-to-be-back-in-padres-dugout-576522182.html",
            "image_url": "https://media.winnipegfreepress.com/images/399*600/20220520220516-62884c0d79dce16d6a2bbbc9jpeg.jpg",
            "language": "en",
            "published_at": "2022-05-21T03:20:39.000000Z",
            "source": "winnipegfreepress.com",
            "categories": [
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "f98f8c9d-ef66-4f2e-8e16-191bb59789fc",
            "title": "어머니가 생각난 궁예 아저씨.jpg : 클리앙",
            "description": "😭😭😭",
            "keywords": "",
            "snippet": "SIGNATURE\n\n인생이란 결코 공평하지 않다. 이 사실에 익숙해져라. ~ 빌 게이츠",
            "url": "https://www.clien.net/service/board/park/17268067",
            "image_url": "https://cdn.clien.net/web/api/file/F01/12945792/1c17a405ff03da.jpg",
            "language": "ko",
            "published_at": "2022-05-21T03:20:28.000000Z",
            "source": "clien.net",
            "categories": [
                "tech"
            ],
            "relevance_score": null
        },
        {
            "uuid": "69d8eeff-8578-4e77-a665-805ffc9e46eb",
            "title": "但凡你共能把高雅的宪法完全执行 你中推圈 都没几个反贼",
            "description": "但凡你共能把高雅的宪法完全执行 你中推圈 都没几个反贼",
            "keywords": "",
            "snippet": "",
            "url": "https://Lvv2.com/t/3932860",
            "image_url": "https://Lvv2.com/templates/default/images/favicon.ico",
            "language": "zh",
            "published_at": "2022-05-21T03:20:21.000000Z",
            "source": "Lvv2.com",
            "categories": [],
            "relevance_score": null
        },
        {
            "uuid": "2174b14f-bd5b-42b9-b2af-8507d112e336",
            "title": "#ikeakuma 一款摘掉眼镜会变成魅魔的ike 是520(521)特供! #图片, page 1",
            "description": "#ikeakuma\n一款摘掉眼镜会变成魅魔的ike\n是520(521)特供!",
            "keywords": "",
            "snippet": "",
            "url": "https://Lvv2.com/t/3932859",
            "image_url": "https://pbs.twimg.com/media/FTOPo8nXEAMmJ9J.jpg",
            "language": "zh",
            "published_at": "2022-05-21T03:20:11.000000Z",
            "source": "Lvv2.com",
            "categories": [],
            "relevance_score": null
        },
        {
            "uuid": "d2df3607-cce4-41de-adcb-befea8072268",
            "title": "Sanction contre Wimbledon",
            "description": "Représailles de l’ATP et la WTA pour avoir banni les joueurs russes.",
            "keywords": "",
            "snippet": "PARIS | L’ATP et la WTA ne distribueront pas de points au classement à Wimbledon, en guise de sanction à l’endroit du plus prestigieux tournoi de tennis a...",
            "url": "https://www.journaldequebec.com/2022/05/20/sanction-contre-wimbledon",
            "image_url": "https://m1.quebecormedia.com/emp/emp/AFP_32AB9M3_8751493d249e62-477e-452e-b652-9af5ff4662b1_ORIGINAL.jpg?impolicy=crop-resize&x=0&y=72&w=2000&h=823&width=1200",
            "language": "fr",
            "published_at": "2022-05-21T03:19:34.000000Z",
            "source": "journaldequebec.com",
            "categories": [
                "general"
            ],
            "relevance_score": null
        }
    ]
}
            
        

Similar News Available on: All plans

Endpoint

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

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

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

All text data returned is UTF-8.

All dates are in UTC (GMT).

HTTP GET Parameters

name required description
api_token true Your API token which can be found on your account dashboard.
categories false Comma separated list of categories to include.
Supported categories: general | science | sports | business | health | entertainment | tech | politics | food | travel
Example: business,tech
exclude_categories false Comma separated list of categories to exclude.
domains false Comma separated list of domains to include. List of domains can be obtained through our Sources endpoint, found further down this page.
exclude_domains false Comma separated list of domains to exclude
source_ids false Comma separated list of source_ids to include. List of source_ids can be obtained through our Sources endpoint, found further down this page.
exclude_source_ids false Comma separated list of source_ids to exclude.
language false Comma separated list of languages to include. Default is all.
Click here for a list of supported languages.
Examples: en,es (English + Spanish)
published_before false Find all articles published before the specified date. Supported formats include: Y-m-d\TH:i:s | Y-m-d\TH:i | Y-m-d\TH | Y-m-d | Y-m | Y.
Examples: 2022-05-21T03:24:22 | 2022-05-21T03:24 | 2022-05-21T03 | 2022-05-21 | 2022-05 | 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-05-21T03:24:22 | 2022-05-21T03:24 | 2022-05-21T03 | 2022-05-21 | 2022-05 | 2022
published_on false Find all articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2022-05-21
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-05-14
    

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.