TheNewsAPI

https://www.thenewsapi.com/documentation
Admin
TheNewsAPI is a RESTful news API that provides access to global news articles and headlines from...
Tokens:25,111
Snippets:114
Trust Score:8
Update:1 month ago
Show doc for...
Tokens:
Raw
### Headlines Example Request

Source: https://www.thenewsapi.com/documentation

An example of a GET request to the headlines endpoint including locale, language, and API token parameters.

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

--------------------------------

### Example Similar News Request

Source: https://www.thenewsapi.com/documentation

A practical example of a GET request to the similar news endpoint, including an API token, language filter, and publication date.

```http
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 Request for News by UUID

Source: https://www.thenewsapi.com/documentation

Example GET request to retrieve a specific article by its UUID. Replace YOUR_API_TOKEN with your actual API token. The UUID in the URL is the article's unique identifier.

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

--------------------------------

### Example API Request

Source: https://www.thenewsapi.com/documentation

A sample GET request to the news endpoint, including the required API token, language filter, and limit parameter.

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

--------------------------------

### Example Sources Request

Source: https://www.thenewsapi.com/documentation

A sample request to the sources endpoint including an API token and language filter.

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

--------------------------------

### Example Request 3: AND Search

Source: https://www.thenewsapi.com/documentation

A request to return articles matching the search term 'usd' AND 'gbp'.

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

--------------------------------

### HTTP GET Parameters

Source: https://www.thenewsapi.com/documentation

Lists all query parameters for TheNewsAPI HTTP GET requests, including required and optional fields, their types, and usage examples.

```APIDOC
## HTTP GET Parameters

### Description
This endpoint accepts various query parameters to filter, search, sort, and paginate news articles.

### Method
GET

### Parameters
#### Query Parameters
- **api_token** (string) - Required - Your API token which can be found on your account dashboard.
- **search** (string) - Optional - Basic search tool or advanced query builder. Supports operators: + (AND), | (OR), - (negate), " (phrase), * (prefix), ( ) (precedence). Escape special characters with backslash. Must be URL-encoded when using special characters.
- **search_fields** (string) - Optional - Comma separated list of fields to apply the search parameter to. Supported fields: title, description, keywords, main_text. Default: title,main_text.
- **locale** (string) - Optional - Comma separated list of country codes to include. Default is all countries.
- **categories** (string) - Optional - Comma separated list of categories to include. Supported: general, science, sports, business, health, entertainment, tech, politics, food, travel.
- **exclude_categories** (string) - Optional - Comma separated list of categories to exclude.
- **domains** (string) - Optional - Comma separated list of domains to include.
- **exclude_domains** (string) - Optional - Comma separated list of domains to exclude.
- **source_ids** (string) - Optional - Comma separated list of source_ids to include.
- **exclude_source_ids** (string) - Optional - Comma separated list of source_ids to exclude.
- **language** (string) - Optional - Comma separated list of languages to include. Default is all.
- **published_before** (string) - Optional - Find articles published before the specified date. Supported formats: Y-m-d\TH:i:s, Y-m-d\TH:i, Y-m-d\TH, Y-m-d, Y-m, Y.
- **published_after** (string) - Optional - Find articles published after the specified date. Supported formats: Y-m-d\TH:i:s, Y-m-d\TH:i, Y-m-d\TH, Y-m-d, Y-m, Y.
- **published_on** (string) - Optional - Find articles published on the specified date. Supported format: Y-m-d.
- **sort** (string) - Optional - Sort by published_on or relevance_score (only with search). Default is published_at unless search is used and sorting by published_at is not included, then relevance_score.
- **limit** (integer) - Optional - Number of articles to return. Maximum based on plan. Default is plan maximum.
- **page** (integer) - Optional - Pagination page number. Default is 1. Max result set is 20,000.

### Request Example
GET /?api_token=YOUR_TOKEN&search=forex+%2B+%28usd+%7C+gbp%29+-cad&search_fields=title,description&locale=us,ca&categories=business,tech&language=en&published_after=2026-09-11T21:07:43&sort=published_on&limit=50&page=2

### Response
#### Success Response (200)
- **articles** (array) - List of news articles matching the query.
- **total** (integer) - Total number of articles found.
- **page** (integer) - Current page number.
- **limit** (integer) - Number of articles per page.

#### Response Example
{
  "articles": [
    {
      "title": "Example Article",
      "description": "Description of the article",
      "url": "https://example.com/article",
      "published_at": "2026-09-11T21:07:43"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 50
}
```

--------------------------------

### Example Sources Response

Source: https://www.thenewsapi.com/documentation

A sample JSON response from the sources endpoint showing meta information and a list of source objects.

```json
{
    "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"
            ]
        },
        ...

```

--------------------------------

### Example Request 2: OR Search

Source: https://www.thenewsapi.com/documentation

A request to return articles matching the search term 'usd' OR 'gbp'.

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

--------------------------------

### Example Response for News by UUID

Source: https://www.thenewsapi.com/documentation

Example JSON response returned by the News by UUID endpoint. Contains article details such as uuid, title, description, snippet, url, image_url, language, published_at, source, and categories. If no results are found, a resource_not_found error is returned.

```json
{
    "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"
    ]
}
```

--------------------------------

### Example Request for Top News

Source: https://www.thenewsapi.com/documentation

A GET request to the top news endpoint, filtered by locale and limited to 3 results.

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

--------------------------------

### Example API Response

Source: https://www.thenewsapi.com/documentation

A sample JSON response containing meta information and a list of article data objects.

```json
{
    "meta": {
        "found": 54938280,
        "returned": 10,
        "limit": 10,
        "page": 1
    },
    "data": [
        {
            "uuid": "72d37421-5314-4440-9737-d53bb685282e",
            "title": "메타플래닛, 홍콩에 자산운용 자회사 설립",
            "description": "일본상장BTC전략매집기업메타플래닛이홍콩에100%자회사인메타플래닛애셋매니지먼트아시아를설립한다고발표했다.초기?...",
            "keywords": "",
            "snippet": "",
            "url": "https://www.coinreaders.com/257820",
            "image_url": "http://www.coinreaders.com/data/coinreaders_com/banner/favicon.ico",
            "language": "ko",
            "published_at": "2026-09-11T21:06:20.000000Z",
            "source": "coinreaders.com",
            "categories": [],
            "relevance_score": null
        },
        {
            "uuid": "594aae5e-fdfa-4b9e-8b12-b7d9e648bfe0",
            "title": "Deixar de tomar banho para atrair mulheres? O que é a trend 'pheromone maxxing'",
            "description": "Veja as últimas notícias do UOL em um novo formato de consumir conteúdo em Flash. Confira vídeos e stories do que está acontecendo no mundo.",
            "keywords": "",
            "snippet": "Tudo Eleições 2026 Caso Master Libertadores Guerra no Irã Tênis UOL 30 anos",
            "url": "https://www.uol.com.br/flash/?c=6a99768494e243f140913bed",
            "image_url": "https://conteudo.imguol.com.br/c/flash/geral/2a/2026/09/03/capa-2-1788452472021_v2_1080x1350.jpg",
            "language": "pt",
            "published_at": "2026-09-11T21:05:34.000000Z",
            "source": "uol.com.br",
            "categories": [
                "tech",
                "science"
            ],
            "relevance_score": null
        },
        {
            "uuid": "517cc9a6-7871-498e-9450-0a79cc01fee2",
            "title": "Court Finds Administration Out of Line on Coal Plant Order",
            "description": "In a defeat for the Trump administration, a federal court on Friday ruled that the Energy Department exceeded its authority when it forced a Michigan coal-fired...",
            "keywords": "coal power, Department of Energy, Chris Wright, Trump administration, Michigan",
            "snippet": "In a defeat for the Trump administration, a federal court on Friday ruled that the Energy Department exceeded its authority when it forced a Michigan coal-fired...",
            "url": "https://www.newser.com/story/396307/court-finds-administration-out-of-line-on-coal-plant-order.html",
            "image_url": "https://cdn.newser.com/image/1711200-12-20260911153103.jpeg",
            "language": "en",
            "published_at": "2026-09-11T21:05:00.000000Z",
            "source": "newser.com",
            "categories": [
                "general",
                "politics"
            ],
            "relevance_score": null
        },
        {
            "uuid": "269f3728-c48a-47a3-9320-0239187ea56f",
            "title": "Mercato agosto: in crescita l’usato delle due ruote",
            "description": "I passaggi di proprietà dei motocicli sono stati 40.968, rispetto ai 40.104 di agosto 2025, con un aumento del 2,2%. Nel complesso, i passaggi di proprietà pe...",
            "keywords": "Attualità",
            "snippet": "Ad agosto 2026, il mercato dell’usato auto registra un lievissimo calo nei volumi assoluti. I passaggi di proprietà delle autovetture sono stati 179.397, con...",
            "url": "https://www.moto.it/news/mercato-agosto-in-crescita-l-usato-delle-due-ruote.html"
```

--------------------------------

### Example Response JSON

Source: https://www.thenewsapi.com/documentation

A sample JSON response showing the meta object and a list of news articles in the data array.

```json
{
   "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
      }
   ]
}
```

--------------------------------

### Headlines Example Response

Source: https://www.thenewsapi.com/documentation

A sample JSON response structure returned by the headlines endpoint.

```json
{
    "data": {
        "general": [
            {
                "uuid": "4e91cc47-cae2-4415-af30-1a3326574df8",
                "title": "How George W. Bush reacted to the 9/11 attacks",
                "description": "Former President George W. Bush was in a classroom at a Florida elementary school when he was informed of the 9/11 attacks. Chief Washington correspondent Major Garrett was traveling with Bush that day, 25 years ago.",
                "keywords": "9/11",
                "snippet": "How George W. Bush reacted to the 9/11 attacks Former President George W. Bush was in a classroom at a Florida elementary school when he was informed of the 9/1...",
                "url": "https://www.cbsnews.com/video/how-george-w-bush-reacted-to-the-911-attacks/",
                "image_url": "https://assets2.cbsnewsstatic.com/hub/i/r/2026/09/11/c360d0eb-a82f-4a59-a5e5-e06331daa22d/thumbnail/1200x630/afb8d380b8f116b82f75393dc4cc8697/cbsn-fusion-how-george-w-bush-reacted-to-the-911-attacks-thumbnail.jpg",
                "language": "en",
                "published_at": "2026-09-11T13:05:31.000000Z",
                "source": "cbsnews.com",
```

--------------------------------

### Example Error Response

Source: https://www.thenewsapi.com/documentation

The standard JSON structure returned when an API request is unsuccessful.

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

--------------------------------

### Example Request 4: AND/NOT Search

Source: https://www.thenewsapi.com/documentation

A request to return articles matching 'usd' AND 'gbp' while excluding articles mentioning 'cad'.

```http
GET https://api.thenewsapi.com/v1/news/all?api_token=YOUR_API_TOKEN&search=usd + gbp -cad
```

--------------------------------

### Example Request 1: Basic Search

Source: https://www.thenewsapi.com/documentation

A basic request to return articles matching the search term 'usd' in the title or body.

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

--------------------------------

### Fetch news with Python http.client

Source: https://www.thenewsapi.com/documentation

Uses the standard library http.client to perform a GET request.

```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'))
```

--------------------------------

### Fetch news with C# RestSharp

Source: https://www.thenewsapi.com/documentation

Uses the RestSharp library to execute a GET request.

```csharp
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);
```

--------------------------------

### All News Endpoint Request

Source: https://www.thenewsapi.com/documentation

The base HTTP GET request to retrieve all news articles.

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

--------------------------------

### Example JSON Response

Source: https://www.thenewsapi.com/documentation

The structure of the JSON response returned by the API, containing meta information and a list of article data objects.

```json
{
    "meta": {
        "found": 1702284,
        "returned": 10,
        "limit": 10,
        "page": 1
    },
    "data": [
        {
            "uuid": "d2ed63df-1aa4-4610-8615-9d61b227ab8b",
            "title": "Lawyer fined $5K over AI-hallucinated witnesses in a murder case",
            "description": "A New Mexico lawyer was fined $5,000 after submitting a court brief that contained fake witnesses and police testimony generated by ChatGPT.",
            "keywords": "",
            "snippet": "New Mexico’s Supreme Court is punishing a lawyer for including AI-fabricated witnesses and fake police testimony in an appeal for his client’s murder convic...",
            "url": "https://www.theverge.com/ai-artificial-intelligence/994207/chatgpt-new-mexico-lawyer-fined-murder-appeal",
            "image_url": "https://platform.theverge.com/wp-content/uploads/sites/2/chorus/uploads/chorus_asset/file/25384193/STK470_AI_LAW_CVIRGINIA_C.jpg?quality=90&strip=all&crop=0,10.732984293194,100,78.534031413613&w=1200",
            "language": "en",
            "published_at": "2026-09-11T21:02:56.000000Z",
            "source": "theverge.com",
            "categories": [
                "tech"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "3d928952-d3ff-4ab4-bd7a-c50c4fc2ce6d",
            "title": "August was brutal for consumers. September could be worse",
            "description": "Two new reports paint a stark picture of the U.S. economy, with no relief in sight",
            "keywords": "",
            "snippet": "Data from the Bureau of Labor Statistics released on Friday painted a grim picture for American consumers and is predicted to shape how the Federal Reserve rule...",
            "url": "https://www.salon.com/2026/09/11/august-was-brutal-for-consumers-september-could-be-worse/",
            "image_url": "https://www.salon.com/app/uploads/2026/09/diesel-oil-gas-prices-GettyImages-2294762200.jpg",
            "language": "en",
            "published_at": "2026-09-11T20:58:37.000000Z",
            "source": "salon.com",
            "categories": [
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        },
        {
            "uuid": "bc63b48e-6566-4d8f-bd2c-1ac7f553e79b",
            "title": "‘Secret Lives of Mormon Wives’ Star Jessi Draper and Ex Jordan Ngatikaura Finalize Divorce: Report",
            "description": "'Secret Lives of Mormon Wives’ star Jessi Draper has reportedly finalized her divorce from ex Jordan Ngatikaura amid her new romance with Marciano Brunette",
            "keywords": "",
            "snippet": "The Secret Lives of Mormon Wives star Jessi Draper and her ex Jordan Ngatikaura have reportedly finalized their divorce.\n\nThe former couple signed off on their ...",
            "url": "https://www.usmagazine.com/celebrity-news/news/jessi-draper-and-ex-jordan-ngatikaura-finalize-divorce/",
            "image_url": "https://www.usmagazine.com/wp-content/uploads/2026/09/Jessi-Draper-and-Ex-Jordan-Ngatikaura-Finalize-Divorce.jpg?crop=0px,0px,2000px,1051px&resize=1200,630&quality=86&strip=all",
            "language": "en",
            "published_at": "2026-09-11T20:50:33.000000Z",
            "source": "usmagazine.com",
            "categories": [
                "entertainment",
                "general"
            ],
            "relevance_score": null,
            "locale": "us"
        }
    ]
}
```

--------------------------------

### Example Request 6: Advanced Filtered Search

Source: https://www.thenewsapi.com/documentation

A request combining complex search logic with language, category, and date filters.

```http
GET https://api.thenewsapi.com/v1/news/all?api_token=YOUR_API_TOKEN&search=forex + (usd | gbp) -cad&language=en&categories=business,tech&exclude_categories=travel&published_after=2026-09-04
```

--------------------------------

### Top Stories GET Request

Source: https://www.thenewsapi.com/documentation

The HTTP GET request format for accessing the top stories endpoint. Ensure all GET parameters are URL-encoded.

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

--------------------------------

### Fetch news with Go net/http

Source: https://www.thenewsapi.com/documentation

Uses the net/http package to construct a request with URL parameters.

```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))
}
```

--------------------------------

### Fetch news with Java OkHttp

Source: https://www.thenewsapi.com/documentation

Uses the OkHttp library to build and execute a request.

```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();
```

--------------------------------

### Sources Endpoint Request

Source: https://www.thenewsapi.com/documentation

The base endpoint for retrieving available news sources. Ensure all GET parameters are URL-encoded.

```http
GET https://api.thenewsapi.com/v1/news/sources HTTP/1.1
```
Tokens:
Raw