Documentation

Sign up for free!

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

Sign up now

Getting Started

Introduction

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

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

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

Authentication

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

API Endpoints

Headlines Available on: Standard plan and above

Endpoint

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

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

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

All text data returned is UTF-8.

All dates are in UTC (GMT).

HTTP GET Parameters

name required description
api_token true Your API token which can be found on your account dashboard.
locale false Comma separated list of country codes to include in the result set. Default is 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-08-12
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": "4722e376-cf41-4594-8c51-57c677e75fd9",
                "title": "Anne Heche suffered brain injury and not expected to survive, according to family",
                "description": "Anne Heche is not expected to survive a brain injury she suffered in a fiery car crash.",
                "keywords": "",
                "snippet": "Anne Heche is not expected to survive the brain injury she suffered in a fiery car crash in Los Angeles and is being kept on life support to determine if her or...",
                "url": "https://abcnews.go.com/US/anne-heche-suffered-brain-injury-expected-survive-family/story?id=88278228",
                "image_url": "https://s.abcnews.com/images/US/Heche-sg-AP-8-11_hpMain_20220811-235030_16x9_992.jpg",
                "language": "en",
                "published_at": "2022-08-12T04:12:26.000000Z",
                "source": "abcnews.go.com",
                "categories": [
                    "general"
                ],
                "locale": "us",
                "similar": [
                    {
                        "uuid": "5bcf56f8-fe77-4ef8-a1da-e9ee85b7e734",
                        "title": "Anne Heche is 'not expected to survive,' family says in statement",
                        "description": "Anne Heche, who remains hospitalized after crashing her vehicle into a Los Angeles residence last week, is \"not expected to survive,\" according to a statement from her family and friends shared with CNN by a representative.",
                        "keywords": "entertainment, Anne Heche 'not expected to survive' crash injuries, rep says - CNN",
                        "snippet": "(CNN) Anne Heche, who remains hospitalized after crashing her vehicle into a Los Angeles residence last week, is \"not expected to survive,\" according to a state...",
                        "url": "https://www.cnn.com/2022/08/12/entertainment/anne-heche-family-statement/index.html",
                        "image_url": "https://cdn.cnn.com/cnnnext/dam/assets/220810182905-anne-heche-file-2018-super-tease.jpg",
                        "language": "en",
                        "published_at": "2022-08-12T04:18:40.000000Z",
                        "source": "cnn.com",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "511d36e8-fb07-4d6e-abd7-256859386fca",
                        "title": "Anne Heche ‘Not Expected to Survive,’ Remains in Coma",
                        "description": "Anne Heche is ‘not expected to survive’ after a car crash resulted in a fire on Friday, August 5 — details",
                        "keywords": "",
                        "snippet": "Anne Heche remains in a coma and is and it not expective to survive after her Friday, August 5, car crash.\n\n“We want to thank everyone for their kind wishes a...",
                        "url": "https://www.usmagazine.com/celebrity-news/news/anne-heche-not-expected-to-survive-remains-in-coma/",
                        "image_url": "https://i0.wp.com/www.usmagazine.com/wp-content/uploads/2022/08/Anne-Heche-Is-in-a-Coma-Following-Car-Crash-Everything-to-Know-About-the-Incident-Aftermath.jpg?crop=0px%2C8px%2C1541px%2C809px&resize=1200%2C630&ssl=1&quality=86&strip=all",
                        "language": "en",
                        "published_at": "2022-08-12T04:30:19.000000Z",
                        "source": "usmagazine.com",
                        "categories": [
                            "entertainment",
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "ec947190-08dd-4985-a1ff-694e1dba3a07",
                        "title": "Anne Heche on life support, survival of crash ‘not expected’",
                        "description": "Anne Heche is on life support after suffering a brain injury in a fiery crash a week ago and her survival isn’t expected, according to a statement from a representative.",
                        "keywords": "Anne Heche, Crash",
                        "snippet": "Heche, who's been hospitalized at the Grossman Burn Center at West Hills hospital north of Los Angeles, suffered a “severe anoxic brain injury,” the stateme...",
                        "url": "https://www.bostonglobe.com/2022/08/12/nation/anne-heche-life-support-survival-crash-not-expected/?camp=bg:brief:rss:feedly&rss_id=feedly_rss_brief",
                        "image_url": "https://bostonglobe-prod.cdn.arcpublishing.com/resizer/IjYd1DMgGFu7_ZAkEuMiqXwET98=/506x0/cloudfront-us-east-1.images.arcpublishing.com/bostonglobe/4HTKRV4ERD4AT4B6QLKGITCMAY.jpg",
                        "language": "en",
                        "published_at": "2022-08-12T05:06:58.000000Z",
                        "source": "bostonglobe.com",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "956ba4ef-95c1-48d5-be3f-8efb871e633f",
                        "title": "Anne Heche ‘not expected to survive’ after fiery crash, rep says",
                        "description": "Actress Anne Heche, who last week crashed her car into a Los Angeles home, is not expected to survive the injuries she sustained in the collision, a rep said.",
                        "keywords": "",
                        "snippet": "Actress Anne Heche, who last week crashed her car into a Los Angeles home, is not expected to survive the injuries she sustained in the collision and subsequent...",
                        "url": "https://www.washingtonpost.com/nation/2022/08/12/anne-heche-anoxic-brain-injury-coma/",
                        "image_url": "https://www.washingtonpost.com/wp-apps/imrs.php?src=https://arc-anglerfish-washpost-prod-washpost.s3.amazonaws.com/public/IFX3B5QVJEI63BECA3A4QTHI6I.jpg&w=1440",
                        "language": "en",
                        "published_at": "2022-08-12T07:03:44.000000Z",
                        "source": "washingtonpost.com",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "9d248c2f-9fb5-42df-bc5b-1b6b6071245a",
                        "title": "Anne Heche is suffering from an anoxic brain injury. How does that affect the body?",
                        "description": "Actress Anne Heche, 53, has been hospitalized since last Friday, when she was allegedly speeding in her blue Mini Cooper and crashed into two homes.",
                        "keywords": "",
                        "snippet": "Anne Heche is suffering from an anoxic brain injury. How does that affect the body?\n\nEnlarge this image toggle caption Alberto E. Rodriguez/Getty Images Alberto...",
                        "url": "https://www.npr.org/2022/08/12/1117118523/anne-heche-brain-dead-car-crash",
                        "image_url": "https://media.npr.org/assets/img/2022/08/12/gettyimages-455325239_wide-5b61518c5ba4ca8b5f6cdab834f3bc8f72465e0f.jpg?s=1400",
                        "language": "en",
                        "published_at": "2022-08-12T09:00:40.000000Z",
                        "source": "npr.org",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    }
                ]
            },
            {
                "uuid": "0318ee35-26d9-41ef-b3d0-1d502515bb57",
                "title": "Most German howitzers in Ukraine out of order – official",
                "description": "Two-thirds of German PzH 2000 howitzers supplied to Ukraine have already broken, a German MP has stated",
                "keywords": "",
                "snippet": "Only five out of 15 Western-supplied PzH 2000 howitzers are still operational in Ukraine, says a German politician\n\nMost German PzH 2000 howitzers that have bee...",
                "url": "https://www.rt.com/russia/560728-ukraine-german-howitzers-broken/",
                "image_url": "https://cdni.russiatoday.com/files/2022.08/article/62f66aa320302707ff241791.jpg",
                "language": "en",
                "published_at": "2022-08-12T15:03:35.000000Z",
                "source": "rt.com",
                "categories": [
                    "general",
                    "politics"
                ],
                "locale": "us",
                "similar": [
                    {
                        "uuid": "e0c46ce6-4e76-4ed5-95cf-b7c19c6f6f11",
                        "title": "Live updates: Russia's war in Ukraine",
                        "description": "The situation at the Russian-occupied Zaporizhzhia nuclear power plant in Ukraine has reached a \"grave hour,\" the head of the UN nuclear watchdog said, as he called for an immediate inspection of the facility by experts. Follow live news updates here.",
                        "keywords": "europe, Live updates: Russia's war in Ukraine",
                        "snippet": "A view of the damage following an attack by Russian forces in Nikopol, Ukraine on August 11. (Metin Aktas/Anadolu Agency/Getty Images)\n\nThe city of Nikopol in s...",
                        "url": "https://www.cnn.com/europe/live-news/russia-ukraine-war-news-08-12-22/index.html",
                        "image_url": "https://cdn.cnn.com/cnnnext/dam/assets/220810170043-ukraine-russia-prison-attack-0729-blurred-super-tease.jpeg",
                        "language": "en",
                        "published_at": "2022-08-12T07:33:53.000000Z",
                        "source": "cnn.com",
                        "categories": [
                            "general"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "107984c0-f80e-415b-a2ac-66b08977bc93",
                        "title": "Ukraine, international officials decry 'alarming' military activity near nuclear plant: Updates",
                        "description": "Russia took over the Zaporizhzhia plant in southern Ukraine, one of the 10 largest nuclear plants in the world, shortly after invading the country.",
                        "keywords": "",
                        "snippet": "Ukraine, international officials decry 'alarming' military activity near nuclear plant: Updates\n\nShow Caption Hide Caption Ukraine and Russia point fingers over...",
                        "url": "https://www.usatoday.com/story/news/world/2022/08/12/ukraine-russia-invasion-live-updates/10306006002/",
                        "image_url": "https://www.gannett-cdn.com/presto/2022/08/10/USAT/aa2d8cf7-d715-48ef-a71c-48817d50d696-AP22221670631591.jpg?auto=webp&crop=1023,576,x0,y22&format=pjpg&width=1200",
                        "language": "en",
                        "published_at": "2022-08-12T12:33:56.000000Z",
                        "source": "usatoday.com",
                        "categories": [
                            "general",
                            "travel",
                            "sports"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "6780f101-447e-42e2-be4d-5603f1da8b02",
                        "title": "Ukraine may not be able to maintain industrial economy – WaPo",
                        "description": "Ukraine may have no choice but to deindustrialize due to the loss of access to much of its natural resources, the Washington Post said",
                        "keywords": "",
                        "snippet": "The loss of access to coal and other reserves located in Russia-held lands leaves Kiev at an impasse, the newspaper reports\n\nUkraine has lost “the building bl...",
                        "url": "https://www.rt.com/russia/560714-ukraine-mineral-reserves-deindustrialization/",
                        "image_url": "https://cdni.russiatoday.com/files/2022.08/article/62f647ed2030275dd8275a6d.jpg",
                        "language": "en",
                        "published_at": "2022-08-12T13:31:02.000000Z",
                        "source": "rt.com",
                        "categories": [
                            "general",
                            "politics"
                        ],
                        "locale": "us"
                    },
                    {
                        "uuid": "7969ddcd-7512-4a76-b3ca-4d268ce982e7",
                        "title": "Ukraine Calls Again for More Funds, Arms, Munitions, to 'Stop Russia'",
                        "description": "Ukraine President Volodymyr Zelensky has renewed his almost weekly call for Western nations to do more to help his besieged nation.",
                        "keywords": "",
                        "snippet": "Ukraine President Volodymyr Zelensky on Thursday renewed his almost weekly call for Western nations to do more to help his besieged nation in its fight against ...",
                        "url": "https://www.breitbart.com/europe/2022/08/12/send-money-ukraine-calls-again-for-more-funds-arms-munitions-fighter-jets-to-stop-russia/",
                        "image_url": "https://media.breitbart.com/media/2022/08/zelensky-call-for-funds-640x335.jpg",
                        "language": "en",
                        "published_at": "2022-08-12T10:17:59.000000Z",
                        "source": "breitbart.com",
                        "categories": [
                            "general",
                            "politics"
                        ],
                        "locale": "us"
                    }
                ]
            }
        ],
        "business": ...,
        "sports": ...,
        "tech": ...,
        "science": ...,
        "health": ...
    }
}

Top Stories Available on: All plans

Endpoint

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

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

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

All text data returned is UTF-8.

All dates are in UTC (GMT).

HTTP GET Parameters

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

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

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

For more advanced query examples, see our API Examples section.
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-08-12T15:43:21 | 2022-08-12T15:43 | 2022-08-12T15 | 2022-08-12 | 2022-08 | 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-08-12T15:43:21 | 2022-08-12T15:43 | 2022-08-12T15 | 2022-08-12 | 2022-08 | 2022
published_on false Find all articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2022-08-12
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": 496740,
        "returned": 10,
        "limit": 10,
        "page": 1
    },
    "data": [
        {
            "uuid": "df2bab61-515a-4375-bc9d-ebbf78c9a42c",
            "title": "Amazon driver deactivated after firing in self-defense at Middletown man with knife : news",
            "description": "25.1m 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/wmnk8l/amazon_driver_deactivated_after_firing_in/",
            "image_url": "https://external-preview.redd.it/VvaRRZC4e0a4LYbCnXMhfu7AsttEE3hUrrl86Za9PmI.jpg?auto=webp&s=ebfec33d57f977b5548a0b0b1a4d7352ed03f4ba",
            "language": "en",
            "published_at": "2022-08-12T15:37:40.000000Z",
            "source": "reddit.com",
            "categories": [
                "general",
                "politics"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "67c6b919-4997-4629-ab69-07eae8b05406",
            "title": "Salman Rushdie attacked on stage in New York : news",
            "description": "25.1m 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/wmnt0s/salman_rushdie_attacked_on_stage_in_new_york/",
            "image_url": "https://external-preview.redd.it/t-vy-MARJtaUKcHoQyQFHgCKq2nmMrFsBb1VlcwU0b0.jpg?auto=webp&s=4ed51d263230b790bdb9b31092d970a21240bcee",
            "language": "en",
            "published_at": "2022-08-12T15:37:40.000000Z",
            "source": "reddit.com",
            "categories": [
                "general",
                "politics"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "23004751-68b0-4bca-8a06-8fe60e6e7940",
            "title": "McGregor deletes insult aimed at Russian star",
            "description": "Conor McGregor's war of words with Dagestan-based fighters continues after the Irishman aimed a since-deleted insult at Islam Makhachev",
            "keywords": "",
            "snippet": "UFC star McGregor has again hit out at Russian fighter online\n\nConor McGregor hasn't been seen in the cage for more than a year but that hasn't stopped him from...",
            "url": "https://www.rt.com/sport/560724-conor-mcgregor-makhachev-insult/",
            "image_url": "https://cdni.russiatoday.com/files/2022.08/article/62f6720685f540740413c206.jpg",
            "language": "en",
            "published_at": "2022-08-12T15:34:51.000000Z",
            "source": "rt.com",
            "categories": [
                "general",
                "politics"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "c474e1e7-b487-41e1-9414-152957e11fb0",
            "title": "Curaleaf Forced To Remove Thousands Of Medical Marijuana Products From NY Dispensaries, Here's What Happened",
            "description": "Curaleaf (OTCQX: CURLF) has pulled tens of thousands of units of cannabis from dispensary shelves all over New York after the company switched to an unauthor...",
            "keywords": "",
            "snippet": "Curaleaf CURLF has pulled tens of thousands of units of cannabis from dispensary shelves all over New York after the company switched to an unauthorized method ...",
            "url": "https://www.benzinga.com/markets/cannabis/22/08/28475842/curaleaf-forced-to-remove-thousands-of-medical-marijuana-products-from-ny-dispensaries-heres-wha",
            "image_url": "https://cdn.benzinga.com/files/images/story/2022/08/12/thc_drawing.jpg?width=1200&height=800&fit=crop",
            "language": "en",
            "published_at": "2022-08-12T15:29:25.000000Z",
            "source": "benzinga.com",
            "categories": [
                "business"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "a318c835-3356-420e-884f-3c7949f3fb9b",
            "title": "Ethereum Co-Founder Vitalik Buterin: Millions Of People Have Crypto Wallets To Trade Monkey Pictures",
            "description": "Ethereum (CRYPTO: ETH) creator Vitalik Buterin has once again taken a dig at NFT project Bored Ape Yacht Club (BAYC) and its community of followers.",
            "keywords": "",
            "snippet": "Ethereum ETH/USD creator Vitalik Buterin has once again taken a dig at NFT project Bored Ape Yacht Club (BAYC) and its community of followers.\n\nWhat Happened: S...",
            "url": "https://www.benzinga.com/markets/cryptocurrency/22/08/28467020/ethereums-vitalik-buterin-millions-of-people-have-crypto-wallets-to-trade-monkey-pictures",
            "image_url": "https://cdn.benzinga.com/files/images/story/2022/08/12/screen_shot_2022-08-12_at_11.23.49_am.png?width=1200&height=800&fit=crop",
            "language": "en",
            "published_at": "2022-08-12T15:28:14.000000Z",
            "source": "benzinga.com",
            "categories": [
                "business"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "1f481bd9-28a6-4adc-83ba-a366f28eea02",
            "title": "‘The Satanic Verses’ Author Salman Rushdie Attacked Onstage In New York",
            "description": "The Satanic Verses author Salman Rushdie has been attacked while on stage in New York, according to the Associated Press. In the last few minutes, AP said its ...",
            "keywords": "",
            "snippet": "Blood stains mark a screen as author Salman Rushdie, behind screen, is tended to after he was attacked during a lecture, Friday, Aug. 12, 2022, at the Chautauqu...",
            "url": "https://deadline.com/2022/08/salman-rushdie-attacked-new-york-1235090885/",
            "image_url": "https://deadline.com/wp-content/uploads/2022/08/AP22224541927361.jpg?w=1024",
            "language": "en",
            "published_at": "2022-08-12T15:24:25.000000Z",
            "source": "deadline.com",
            "categories": [
                "entertainment"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "821c3f90-744c-4cf7-b065-708ce2c1dd06",
            "title": "Author Salman Rushdie was attacked on a lecture stage in New York",
            "description": "An Associated Press reporter witnessed a man storm the stage and begin punching or stabbing Rushdie as he was being introduced. The author was taken or fell to ...",
            "keywords": "",
            "snippet": "Author Salman Rushdie was attacked on a lecture stage in New York\n\nEnlarge this image toggle caption Grant Pollard/Invision/AP Grant Pollard/Invision/AP\n\nCHAUTA...",
            "url": "https://www.npr.org/2022/08/12/1117164727/author-salman-rushdie-was-attacked-on-a-lecture-stage-in-new-york",
            "image_url": "https://media.npr.org/assets/img/2022/08/12/ap22224541352863_wide-51eb932aef7ed53bef1be88a1bceaa88ef972503.jpg?s=1400",
            "language": "en",
            "published_at": "2022-08-12T15:23:32.000000Z",
            "source": "npr.org",
            "categories": [
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "c0a8b4e3-5d49-45cd-b053-fd91efe9554b",
            "title": "Russia's war in Ukraine pushes Ukrainian steel production to the brink",
            "description": "The Russian invasion has taken a toll on Ukrainian metalworks — the country's second-largest industry — and there's still no deal to ship iron and steel pro...",
            "keywords": "",
            "snippet": "Russia's war in Ukraine pushes Ukrainian steel production to the brink\n\nEnlarge this image toggle caption Jason Beaubien/NPR Jason Beaubien/NPR\n\nZAPORIZHZHIA, U...",
            "url": "https://www.npr.org/2022/08/12/1116312634/russia-ukraine-war-steel-iron-industry",
            "image_url": "https://media.npr.org/assets/img/2022/08/08/2022-07-22-ukraine-steel-jbeaubien-0007_edit_wide-e26ba125ff8bc8aebebae29c981dfe931b4f8143.jpg?s=1400",
            "language": "en",
            "published_at": "2022-08-12T15:20:50.000000Z",
            "source": "npr.org",
            "categories": [
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "eef57ba5-6820-4f3f-a52a-760529f35b0c",
            "title": "Cops Spend $400,000 to Save House Democrats’ Campaign Chair",
            "description": "The avalanche of spending comes at a vulnerable point in Rep. Sean Patrick Maloney’s campaign against state Sen. Alessandra Biaggi.",
            "keywords": "",
            "snippet": "“Alessandra Biaggi voted to release criminals without bail,” read an ad on the back of a truck with a New Jersey license plate driving through New York’s ...",
            "url": "https://theintercept.com/2022/08/12/sean-patrick-maloney-alessandra-biaggi-police-pac/",
            "image_url": "https://theintercept.imgix.net/wp-uploads/sites/1/2022/08/GettyImages-1239077763.jpg?auto=compress%2Cformat&q=90&fit=crop&w=1200&h=800",
            "language": "en",
            "published_at": "2022-08-12T15:18:48.000000Z",
            "source": "theintercept.com",
            "categories": [
                "general",
                "politics",
                "tech"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "9aa980b8-951f-46c4-bcba-c62ce0a10c48",
            "title": "A Bearish Sign Appears On Ameren's Chart",
            "description": "If history is any guide, there may be trouble ahead for shares of Ameren (NYSE:AEE). A so-called",
            "keywords": "",
            "snippet": "If history is any guide, there may be trouble ahead for shares of Ameren AEE. A so-called \"death cross\" has formed on its chart and, not surprisingly, this coul...",
            "url": "https://www.benzinga.com/markets/22/08/28475158/a-bearish-sign-appears-on-amerens-chart",
            "image_url": "https://cdn.benzinga.com/files/images/story/2022/analyst_ratings_image_24970.jpeg?width=1200&height=800&fit=crop",
            "language": "en",
            "published_at": "2022-08-12T15:18:19.000000Z",
            "source": "benzinga.com",
            "categories": [
                "business"
            ],
            "relevance_score": null,
            "locale": "us"
        }
    ]
}

All News Available on: All plans

Endpoint

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

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

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

All text data returned is UTF-8.

All dates are in UTC (GMT).

HTTP GET Parameters

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

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

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

For more advanced query examples, see our API Examples section.
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-08-12T15:43:21 | 2022-08-12T15:43 | 2022-08-12T15 | 2022-08-12 | 2022-08 | 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-08-12T15:43:21 | 2022-08-12T15:43 | 2022-08-12T15 | 2022-08-12 | 2022-08 | 2022
published_on false Find all articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2022-08-12
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": 67755486,
        "returned": 10,
        "limit": 10,
        "page": 1
    },
    "data": [
        {
            "uuid": "edbc213f-b0a7-4959-b584-6320d812b123",
            "title": "엔씨소프트, 하반기 숨고르기...",
            "description": "[디지털투데이 최지연 기자] 엔씨소프트가 신작 부재에도 리니지 지식재산권(IP)의 힘으로 무난한 2분기 성적을 받았다. ?...",
            "keywords": "엔씨소프트, 2분기, 실적발표, 리니지, TL, 출시",
            "snippet": "[디지털투데이 최지연 기자] 엔씨소프트가 신작 부재에도 리니지 지식재산권(IP)의 힘으로 무난한 2분기 성적을 받았다. ?...",
            "url": "http://www.digitaltoday.co.kr/news/articleView.html?idxno=457399",
            "image_url": "https://cdn.digitaltoday.co.kr/news/thumbnail/202208/457399_429582_5738_v150.jpg",
            "language": "ko",
            "published_at": "2022-08-12T15:43:49.000000Z",
            "source": "digitaltoday.co.kr",
            "categories": [
                "tech",
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "fb3c6f76-95f4-477d-b568-7f898d717159",
            "title": "KISA, ‘ICT분쟁조정제도 홍보 콘텐츠 공모전’ 개최",
            "description": "한국인터넷진흥원(KISA, 원장 이원태)은 ICT분쟁조정제도 활성화 및 분쟁 예방에 대한 국민들의 관심과 이해도를 높이기 ?...",
            "keywords": "KISA, ICT분쟁조정제도",
            "snippet": "분쟁조정제도에 관심있는 누구나 참여 가능... 9월 12일(월)까지 접수\n\n한국인터넷진흥원(KISA, 원장 이원태)은 ICT분쟁조정?...",
            "url": "https://www.dailysecu.com/news/articleView.html?idxno=138985",
            "image_url": "https://www.dailysecu.com/news/photo/202208/138985_163122_4340.jpg",
            "language": "ko",
            "published_at": "2022-08-12T15:43:46.000000Z",
            "source": "dailysecu.com",
            "categories": [
                "tech"
            ],
            "relevance_score": null
        },
        {
            "uuid": "bdb0e823-548f-47d5-bcbe-3b47685639e3",
            "title": "\"Para não me chatear, não sigo assim tanto a imprensa\"",
            "description": "Thomas Tuchel foi convidado a comentar sobre a alegada má imprensa de Aubameyang.",
            "keywords": "noticias, nacional, internacional, economia, politica, desporto, fama, mundo, pais, futebol, tecnologia, cultura",
            "snippet": "À margem de Frenkie de Jong, o Chelsea também está interessado em contratar Pierre-Emerick Aubameyang no Barcelona.\n\nNa conferência de antevisão à partida...",
            "url": "https://www.noticiasaominuto.com/desporto/2053580/para-nao-me-chatear-nao-sigo-assim-tanto-a-imprensa",
            "image_url": "https://media-manager.noticiasaominuto.com/1280/naom_62ed44d924e80.jpg",
            "language": "pt",
            "published_at": "2022-08-12T15:43:37.000000Z",
            "source": "noticiasaominuto.com",
            "categories": [
                "sports"
            ],
            "relevance_score": null
        },
        {
            "uuid": "5f8814c5-83cd-434c-a1b6-2a56261deb5d",
            "title": "香港海洋公园水上乐园9月将推“人鱼水上嘉年华”-中新网",
            "description": "8月12日，香港海洋公园水上乐园邀请来自五大慈善团体的市民，提前体验水上乐园9月推出的全新活动“人鱼水上嘉年华”...",
            "keywords": "香港海洋公园水上乐园9月将推“人鱼水上嘉年华”",
            "snippet": "1 / 5\n\n8月12日，香港海洋公园水上乐园邀请来自五大慈善团体的市民，提前体验水上乐园9月推出的全新活动“人鱼水上嘉?...",
            "url": "http://www.chinanews.com.cn/tp/hd2011/2022/08-12/1039863.shtml",
            "image_url": "http://i2.chinanews.com.cn/simg/hd/2022/08/12/wc930x592_b96da97ffcf74f57a76648d514a5b44f.jpeg",
            "language": "zh",
            "published_at": "2022-08-12T15:43:18.000000Z",
            "source": "chinanews.com",
            "categories": [
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "b45c4e75-6ea9-46b5-b619-71991f8657ec",
            "title": "‘Artificially Wes Anderson’ Dreams Up Picturesque Cinematic Scenes Using AI",
            "description": "Wes A.I.nderson.",
            "keywords": "‘Artificially Wes Anderson’ Dreams Up Picturesque Cinematic Scenes Using AI - DesignTAXI.com",
            "snippet": "Subscribe to newsletter\n\n**Please note: Link to free download will be included within the confirmation email\n\nsent to your email address subscribed.",
            "url": "https://designtaxi.com/news/419907/Artificially-Wes-Anderson-Dreams-Up-Picturesque-Cinematic-Scenes-Using-AI/",
            "image_url": "https://editorial.designtaxi.com/images/46420C70-5F8F-4B54-9776-DBD0014F12D1-1660303811.jpeg",
            "language": "en",
            "published_at": "2022-08-12T15:43:04.000000Z",
            "source": "designtaxi.com",
            "categories": [
                "entertainment"
            ],
            "relevance_score": null
        },
        {
            "uuid": "edbcbc04-5177-448b-a05b-081e5caaff25",
            "title": "Louth man raffling apartment to fund life-saving treatment for 18-year-old with brain cancer",
            "description": "A Louth man is raffling off his two-bedroom apartment to raise badly-needed funds for his friend's son who was recently diagnosed with stage 4 brain stem cancer...",
            "keywords": "IrishCentral, Irish news, Irish entertainment",
            "snippet": "A Louth man is raffling off his two-bedroom apartment to raise badly-needed funds for his friend's son who was recently diagnosed with stage 4 brain stem cancer...",
            "url": "https://www.irishcentral.com/news/louth-man-raffling-apartment-treatment-brain-cancer",
            "image_url": "https://www.irishcentral.com/uploads/article-v2/2022/8/153825/MI_Stephen_and_Jean_Woods_-_Raffall.jpg?t=1660287408",
            "language": "en",
            "published_at": "2022-08-12T15:43:00.000000Z",
            "source": "irishcentral.com",
            "categories": [
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "a1427b5b-24ca-401c-99de-b5b0c1b679b7",
            "title": "Minutes of BofE CBDC engagement forum",
            "description": "Item 1: Welcome\r\nCo-chairs Gwyneth Nurse and Jon Cunliffe welcomed Members to the fourth meeting of the CBDC Engagement Forum.",
            "keywords": "Finextra, news, online, bank, banking, technology, finance, financial, fin, tech, fintech, IT, breaking, latest, retail, transaction, trade, execution, headlines, blockchain, digital, investment, mobile, business, challenger, payments, regtech, insurtech, services",
            "snippet": "Source: Bank of England\n\nItem 1: Welcome Co-chairs Gwyneth Nurse and Jon Cunliffe welcomed Members to the fourth meeting of the CBDC Engagement Forum.\n\nItem 2: ...",
            "url": "https://www.finextra.com/pressarticle/93714/minutes-of-bofe-cbdc-engagement-forum",
            "image_url": "https://www.finextra.com/about/finextra-logo.png",
            "language": "en",
            "published_at": "2022-08-12T15:43:00.000000Z",
            "source": "finextra.com",
            "categories": [
                "business"
            ],
            "relevance_score": null
        },
        {
            "uuid": "f72c7252-5981-4952-ad5c-616c7255cbf1",
            "title": "Krimi „Der gute Bulle“ im ZDF: Wer ist der Babo?",
            "description": "Ein bisschen Alkoholrückfall, ein bisschen böse Migrantengang, ein bisschen Junkie: Im ZDF-Krimi „Friss oder stirb“ ist vieles vorhersehbar.",
            "keywords": "TV-Krimi, ZDF, öffentlich-rechtliches Fernsehen, Unterhaltungsfernsehen, Sommerloch, Medien, Gesellschaft, taz, tageszeitung",
            "snippet": "Krimi „Der gute Bulle“ im ZDF : Wer ist der Babo?\n\nEin bisschen Alkoholrückfall, ein bisschen böse Migrantengang, ein bisschen Junkie: Im ZDF-Krimi „Fri...",
            "url": "https://taz.de/Krimi-Der-gute-Bulle-im-ZDF/!5871504/",
            "image_url": "https://taz.de/picture/5723788/948/30800096-1.jpg",
            "language": "de",
            "published_at": "2022-08-12T15:43:00.000000Z",
            "source": "taz.de",
            "categories": [
                "general"
            ],
            "relevance_score": null
        },
        {
            "uuid": "f02e73ba-5521-422e-af07-58639c30203c",
            "title": "닥터슬럼프 : 클리앙",
            "description": "이북이 있었네요. 여전히 재밌네요 🤣",
            "keywords": "",
            "snippet": "공지\n\n모든 회원의 비밀번호를 초기화하였습니다.",
            "url": "https://www.clien.net/service/board/park/17482361",
            "image_url": "https://cdn.clien.net/web/api/file/F01/13249058/35ba696e2f6884.jpeg",
            "language": "ko",
            "published_at": "2022-08-12T15:42:48.000000Z",
            "source": "clien.net",
            "categories": [
                "tech"
            ],
            "relevance_score": null
        },
        {
            "uuid": "d9c9ee28-f6b3-4c50-ba61-09a930a2e8a6",
            "title": "新一批运粮船获准从乌克兰港口出发-中新网",
            "description": "",
            "keywords": "",
            "snippet": "据黑海港口外运农产品问题联合协调中心发布的声明称，当地时间12日，两艘装载总计超6.3万吨粮食的运粮船将从乌克兰?...",
            "url": "https://www.chinanews.com.cn/gj/2022/08-12/9825961.shtml",
            "image_url": "https://i2.chinanews.com.cn/simg/ypt/2022/220811/873c08b5-75ec-4b2a-b7cf-55de834e3a74_zsite_sl.jpg",
            "language": "zh",
            "published_at": "2022-08-12T15:42:29.000000Z",
            "source": "chinanews.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-08-12T15:43:21 | 2022-08-12T15:43 | 2022-08-12T15 | 2022-08-12 | 2022-08 | 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-08-12T15:43:21 | 2022-08-12T15:43 | 2022-08-12T15 | 2022-08-12 | 2022-08 | 2022
published_on false Find all articles published on the specified date. Supported formats include: Y-m-d.
Examples: 2022-08-12
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-08-05

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.