News API

https://newsapi.org/docs
Admin
News API is a simple HTTP REST API for searching and retrieving live articles from all over the web,...
Tokens:39,021
Snippets:607
Trust Score:9.9
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install newsapi-python

Source: https://newsapi.org/docs/client-libraries/python

Install the library using pip. This is the first step before using the client.

```bash
$ pip install newsapi-python
```

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

### Install Node.js Client Library

Source: https://newsapi.org/docs/client-libraries/node-js

Install the newsapi package using npm.

```bash
npm install newsapi --save
```

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

### Installation

Source: https://newsapi.org/docs/client-libraries/php

Install the News API PHP client library using Composer.

```APIDOC
## Installation

Use the following Composer command to install the library:

```bash
$ composer require jcobhams/newsapi
```
```

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

### Install News API PHP Client

Source: https://newsapi.org/docs/client-libraries/php

Install the News API PHP client library using Composer.

```bash
$ composer require jcobhams/newsapi
```

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

### GET Request for Everything Endpoint

Source: https://newsapi.org/docs/endpoints/everything

This example demonstrates how to construct a GET request to the 'everything' endpoint to retrieve all articles mentioning 'Apple' from a specific date, sorted by popularity. Replace 'API_KEY' with your actual News API key.

```http
GET https://newsapi.org/v2/everything?q=apple&from=2026-06-24&to=2026-06-24&sortBy=popularity&apiKey=API_KEY
```

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

### Install NewsAPI C# Package

Source: https://newsapi.org/docs/client-libraries/csharp

Install the NewsAPI C# client library using the NuGet Package Manager.

```powershell
PM> Install-Package NewsAPI
```

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

### Install Node.js dependencies

Source: https://newsapi.org/docs/guides/how-to-get-the-full-content-for-a-news-article

Install the necessary libraries for making HTTP requests and parsing HTML content in Node.js.

```bash
npm install axios jsdom @mozilla/readability
```

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

### Missing API Key Example

Source: https://newsapi.org/docs/errors

Example of a request that is missing the API key and the corresponding error response.

```APIDOC
## Missing API key example
Definition
```
GET https://newsapi.org/v2/everything?q=bitcoin
```

Example response
{
  * "status": "error",
  * "code": "apiKeyMissing",
  * "message": "Your API key is missing. Append this to the URL with the apiKey param, or use the x-api-key HTTP header."

}
```

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

### Install News API Ruby Gem

Source: https://newsapi.org/docs/client-libraries/ruby

Install the News API Ruby client library using the gem command. This is the first step to using the library in your project.

```bash
$ gem install news-api
```

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

### GET Request to Everything Endpoint

Source: https://newsapi.org/docs/endpoints/everything

This is a sample GET request to the 'everything' endpoint to retrieve all articles related to 'bitcoin'. Replace 'API_KEY' with your actual NewsAPI key.

```http
GET https://newsapi.org/v2/everything?q=bitcoin&apiKey=API_KEY
```

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

### Search for news articles that mention a specific topic or keyword

Source: https://newsapi.org/docs/get-started

This section details how to use the `/everything` endpoint to search for articles mentioning a specific topic or keyword. It includes the endpoint definition, an example request using curl, and examples in JavaScript, Ruby, Python, and C#.

```APIDOC
## GET /v2/everything

### Description
Searches through news articles published by over 150,000 news sources and blogs in the last 5 years. This endpoint is useful for finding all articles that mention a specific keyword or phrase.

### Method
GET

### Endpoint
https://newsapi.org/v2/everything

### Parameters
#### Query Parameters
- **q** (string) - Required - The keyword or phrase to search for.
- **from** (string) - Required - The date to search from (YYYY-MM-DD).
- **sortBy** (string) - Optional - How to sort the results (e.g., `popularity`, `relevancy`, `publishedAt`).
- **apiKey** (string) - Required - Your News API key.

### Request Example
```bash
curl https://newsapi.org/v2/everything -G \
    -d q=Apple \
    -d from=2026-06-25 \
    -d sortBy=popularity \
    -d apiKey=API_KEY
```

### Response
#### Success Response (200)
- **status** (string) - Indicates if the request was successful.
- **totalResults** (integer) - The total number of results found.
- **articles** (array) - An array of article objects.
  - **source** (object) - Information about the news source.
    - **id** (string) - The ID of the source (can be null).
    - **name** (string) - The name of the source.
  - **author** (string) - The author of the article.
  - **title** (string) - The title of the article.
  - **description** (string) - A description of the article.
  - **url** (string) - The URL to the article.
  - **urlToImage** (string) - The URL to the article's image.
  - **publishedAt** (string) - The publication date and time of the article.
  - **content** (string) - The content of the article (can be truncated).

### Response Example
```json
{
  "status": "ok",
  "totalResults": 29,
  "articles": [
    {
      "source": {
        "id": null,
        "name": "9to5Mac"
      },
      "author": "Marcus Mendes",
      "title": "Siri AI app on iOS 27 lets users easily switch between Siri and ChatGPT",
      "description": "The new Siri app on iOS 27 defaults to the new Siri AI, but there is a way to quickly switch to ChatGPT at any time. Here’s how it works.",
      "url": "https://9to5mac.com/2026/06/24/siri-ai-app-on-ios-27-lets-users-easily-switch-between-siri-and-chatgpt/",
      "urlToImage": "https://i0.wp.com/9to5mac.com/wp-content/uploads/sites/6/2026/06/ask-siri-chatgpt.jpg?resize=1200%2C628&quality=82&strip=all&ssl=1",
      "publishedAt": "2026-06-25T00:59:58Z",
      "content": "The new Siri app on iOS 27 defaults to the new Siri AI, but there is a way to quickly switch to ChatGPT at any time. Heres how it works.\r\niOS 27 includes a dedicated Siri app with a familiar chatbot-… [+1412 chars]"
    }
  ]
}
```
```

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

### Example Error Response

Source: https://newsapi.org/docs/errors

This is an example of an error response from the NewsAPI, indicating a missing API key. It includes the status, a specific error code, and a descriptive message.

```json
{
  "status": "error",
  "code": "apiKeyMissing",
  "message": "Your API key is missing. Append this to the URL with the apiKey param, or use the x-api-key HTTP header."
}
```

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

### Get Everything

Source: https://newsapi.org/docs/client-libraries/python

Retrieve all articles matching a query, from specified domains, within a date range, and sort by relevancy or popularity. Requires initialization with an API key.

```python
# /v2/everything
all_articles = newsapi.get_everything(q='bitcoin',
                                      sources='bbc-news,the-verge',
                                      domains='bbc.co.uk,techcrunch.com',
                                      from_param='2017-12-01',
                                      to='2017-12-12',
                                      language='en',
                                      sort_by='relevancy',
                                      page=2)
```

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

### Fetch News Sources with Java

Source: https://newsapi.org/docs/client-libraries/java

Get a list of available news sources filtered by language and country. The callback processes the sources response or any encountered errors.

```java
// /v2/top-headlines/sources
newsApiClient.getSources(
  new SourcesRequest.Builder()
    .language("en")
    .country("us")
    .build(),
  new NewsApiClient.SourcesCallback() {
    @Override
    public void onSuccess(SourcesResponse response) {
        System.out.println(response.getSources().get(0).getName());
    }

    @Override
    public void onFailure(Throwable throwable) {
      System.out.println(throwable.getMessage());
    }
  }
);
```

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

### Get Everything Articles with C# Client

Source: https://newsapi.org/docs/client-libraries/csharp

Demonstrates how to initialize the client with an API key and fetch 'everything' articles based on specified criteria like query, sort order, language, and date.

```csharp
using NewsAPI;
using NewsAPI.Models;
using NewsAPI.Constants;
using System;

namespace MyApplication
{
    class Program
    {
        static void Main(string[] args)
        {
            // init with your API key
            var newsApiClient = new NewsApiClient("API_KEY");
            var articlesResponse = newsApiClient.GetEverything(new EverythingRequest
            {
                Q = "Apple",
                SortBy = SortBys.Popularity,
                Language = Languages.EN,
                From = new DateTime(2018, 1, 25)
            });
            if (articlesResponse.Status == Statuses.Ok)
            {
                // total results found
                Console.WriteLine(articlesResponse.TotalResults);
                // here's the first 20
                foreach (var article in articlesResponse.Articles)
                {
                    // title
                    Console.WriteLine(article.Title);
                    // author
                    Console.WriteLine(article.Author);
                    // description
                    Console.WriteLine(article.Description);
                    // url
                    Console.WriteLine(article.Url);
                    // published at
                    Console.WriteLine(article.PublishedAt);
                }
            }
            Console.ReadLine();
        }
    }
}
```

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

### Usage

Source: https://newsapi.org/docs/client-libraries/php

Demonstrates how to initialize the NewsApi client and call various endpoints.

```APIDOC
## Usage

Initialize the client with your API key and use the provided methods to fetch data.

```php
use jcobhams\NewsApi\NewsApi;

$newsapi = new NewsApi($your_api_key);

// Fetch all articles matching a query
$all_articles = $newsapi->getEverything($q, $sources, $domains, $exclude_domains, $from, $to, $language, $sort_by, $page_size, $page);

// Fetch top headlines
$top_headlines = $newsapi->getTopHeadlines($q, $sources, $country, $category, $page_size, $page);

// Fetch available sources
$sources = $newsapi->getSources($category, $language, $country);
```
```

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

### Query Everything with Node.js

Source: https://newsapi.org/docs/client-libraries/node-js

Use the client library to fetch articles from /v2/everything. You must include at least one of q, sources, or domains.

```javascript
// To query /v2/everything
// You must include at least one q, source, or domain
newsapi.v2.everything({
  q: 'bitcoin',
  sources: 'bbc-news,the-verge',
  domains: 'bbc.co.uk, techcrunch.com',
  from: '2017-12-01',
  to: '2017-12-12',
  language: 'en',
  sortBy: 'relevancy',
  page: 2
}).then(response => {
  console.log(response);
  /*
    {
      status: "ok",
      articles: [...] 
    }
  */
});
```

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

### Initialize and Use News API Ruby Client

Source: https://newsapi.org/docs/client-libraries/ruby

Initialize the News API client with your API key and demonstrate fetching top headlines, all articles, and sources. Ensure your API key is kept secure.

```ruby
require 'news-api'

# Init
newsapi = News.new("API_KEY")             

# /v2/top-headlines
top_headlines = newsapi.get_top_headlines(q: 'bitcoin',
                                          sources: 'bbc-news,the-verge',
                                          category: 'business',
                                          language: 'en',
                                          country: 'us')

# /v2/everything
all_articles = newsapi.get_everything(q: 'bitcoin',
                                      sources: 'bbc-news,the-verge',
                                      domains: 'bbc.co.uk,techcrunch.com',
                                      from: '2017-12-01',
                                      to: '2017-12-12',
                                      language: 'en',
                                      sortBy: 'relevancy',
                                      page: 2))

# /v2/top-headlines/sources
sources = newsapi.get_sources(country: 'us', language: 'en')
```

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

### News API PHP Client Usage

Source: https://newsapi.org/docs/client-libraries/php

Demonstrates how to instantiate the NewsApi client and call various endpoints like 'everything', 'top-headlines', and 'sources'. Requires your API key for initialization.

```php
use jcobhams\NewsApi\NewsApi;

$newsapi = new NewsApi($your_api_key);

# /v2/everything
$all_articles = $newsapi->getEverything($q, $sources, $domains, $exclude_domains, $from, $to, $language, $sort_by,  $page_size, $page);

# /v2/top-headlines
$top_headlines = $newsapi->getTopHeadlines($q, $sources, $country, $language, $category, $page_size, $page);

# /v2/top-headlines/sources
$sources = $newsapi->getSources($category, $language, $country);
```

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

### Get Top Headlines for US - JavaScript Fetch API

Source: https://newsapi.org/docs/get-started

This JavaScript code snippet demonstrates how to use the Fetch API to get top headlines for the US. Ensure you replace API_KEY with your valid key.

```javascript
var url = 'https://newsapi.org/v2/top-headlines?' +
          'country=us&' +
          'apiKey=API_KEY';
var req = new Request(url);
fetch(req)
    .then(function(response) {
        console.log(response.json());
    })
```

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

### Example Response from Everything Endpoint

Source: https://newsapi.org/docs/endpoints/everything

This JSON object represents a successful response from the 'everything' endpoint, containing status, total results, and an array of articles. Each article includes source details, author, title, description, URL, image, publication date, and content.

```json
{
  "status": "ok",
  "totalResults": 6786,
  "articles": [
    {
      "source": {
        "id": "the-verge",
        "name": "The Verge"
      },
      "author": "Robert Hart",
      "title": "I went looking for the AI weed vape that gives you Bitcoin for smoking",
      "description": "The crypto weed vape found me on 4/20, the high holiday of cannabis enthusiasts everywhere. It arrived over Slack with the thumbnail of a man exhaling a plume of vapor, the words \"every hit delivers Bitcoin\" emblazoned across it. It claimed to be advertising …",
      "url": "https://www.theverge.com/ai-artificial-intelligence/933916/ai-powered-crypto-cannabis-vape",
      "urlToImage": "https://platform.theverge.com/wp-content/uploads/sites/2/2026/05/268553_We_went_looking_for_the_weed_vape_that_gives_you_Bitcoin_for_smoking_CVirginia2.jpg?quality=90&strip=all&crop=0%2C10.732984293194%2C100%2C78.534031413613&w=1200",
      "publishedAt": "2026-05-29T17:09:12Z",
      "content": "<ul><li></li></ul>\r\nGudtrip is the most ridiculous AI/crypto/weed product to ever touch the internet. Could it possibly be real?\r\nby\r\nRobert HartClose\r\nPosts from this author will be added to your da… [+9574 chars]"
    },
    {
      "source": {
        "id": null,
        "name": "Gizmodo.com"
      },
      "author": "Kyle Torpey",
      "title": "Why Would Someone Publicly Burn $8 Million Worth of Bitcoin? Theories Are Flying",
      "description": "And another question: How do you burn bitcoin?",
      "url": "https://gizmodo.com/why-would-someone-publicly-burn-8-million-worth-of-bitcoin-theories-are-flying-2000764705",
      "urlToImage": "https://gizmodo.com/app/uploads/2026/05/bitcoin-fire-1200x675.jpg",
      "publishedAt": "2026-05-28T20:12:23Z",
      "content": "Earlier this week, someone burned 107 bitcoin (currently worth roughly $7.8 million) by sending the coins to an address where they would become provably unspendable. Initially, the public lighting of… [+5204 chars]"
    },
    {
      "source": {
        "id": null,
        "name": "Gizmodo.com"
      },
      "author": "Kyle Torpey",
      "title": "The Word of God Now Comes With Bitcoin Rewards and an $8.99 Premium Tier",
      "description": "In 2026, even the Bible is gamified.",
      "url": "https://gizmodo.com/the-word-of-god-now-comes-with-bitcoin-rewards-and-an-8-99-premium-tier-2000773017",
      "urlToImage": "https://gizmodo.com/app/uploads/2026/06/Orange-Bible-Bitcoin-Rewards-1200x675.jpg",
      "publishedAt": "2026-06-20T19:26:03Z",
      "content": "At first glance, Orange Bible looks like a standard scripture app. But this app is not just for followers of Jesus Christ, it’s also for followers of Satoshi Nakamoto. On top of that, it shows that e… [+5059 chars]"
    },
    {
      "source": {
        "id": null,
        "name": "Gizmodo.com"
      },
      "author": "Kyle Torpey",
      "title": "Largest US Banks to Launch Tokenization Network to Fight Back Against Crypto, Stablecoin Startups",
      "description": "The traditional banking industry has a long history of consortium blockchain systems that haven’t fared well.",
      "url": "https://gizmodo.com/largest-us-banks-to-launch-tokenization-network-to-fight-back-against-crypto-stablecoin-startups-2000768384",
      "urlToImage": "https://gizmodo.com/app/uploads/2025/10/gizmodo-social-1200x675-1.jpg",
      "publishedAt": "2026-06-06T13:36:30Z"
    }
  ]
}
```

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

### Get Sources

Source: https://newsapi.org/docs/client-libraries/python

Fetch a list of available news sources. This method does not require specific query parameters.

```python
# /v2/top-headlines/sources
sources = newsapi.get_sources()
```

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

### Get Top Headlines

Source: https://newsapi.org/docs/endpoints/top-headlines

Fetches the top headlines based on specified criteria. Requires an API key.

```APIDOC
## GET /v2/top-headlines

### Description
This endpoint retrieves the top headlines available through the NewsAPI. You can filter results by country, category, or a specific query.

### Method
GET

### Endpoint
https://newsapi.org/v2/top-headlines

### Parameters
#### Query Parameters
- **apiKey** (string) - Required - Your NewsAPI key.
- **country** (string) - Optional - The 2-letter ISO 639-1 language code of the country you want to get headlines for.
- **category** (string) - Optional - The category you want to find headlines for. Possible options: business, entertainment, general, health, science, sports, technology.
- **q** (string) - Optional - Keywords or phrases with a priority for higher relevance results.
- **pageSize** (integer) - Optional - The number of results to return per page. Defaults to 20, max is 100.
- **page** (integer) - Optional - Use this to take the next page of results.

### Request Example
```
GET https://newsapi.org/v2/top-headlines?country=us&category=business&apiKey=YOUR_API_KEY
```

### Response
#### Success Response (200)
- **status** (string) - The status of the response. Possible values: ok or error.
- **totalResults** (integer) - The total number of results available.
- **articles** (array) - An array of article objects.
  - **source** (object)
    - **id** (string) - The ID of the source. May be null.
    - **name** (string) - The name of the source.
  - **author** (string) - The author of the article. May be null.
  - **title** (string) - The title of the article.
  - **description** (string) - The description of the article.
  - **url** (string) - The URL to the article.
  - **urlToImage** (string) - The URL to the article's image. May be null.
  - **publishedAt** (string) - The publication date of the article in ISO 8601 format.
  - **content** (string) - The content of the article. May be null.

#### Response Example
```json
{
  "status": "ok",
  "totalResults": 70,
  "articles": [
    {
      "source": {
        "id": "cnn",
        "name": "CNN"
      },
      "author": "Brian Stelter",
      "title": "Trump lashes out at CNN, other news outlets - CNN",
      "description": "Donald Trump, the Republican candidate for president, continued his attacks on the news media on Monday, calling The New York Times and The Washington Post \"dishonest\" and \"fake news.\"",
      "url": "http://us.cnn.com/2016/09/12/media/donald-trump-cnn-new-york-times-washington-post/index.html",
      "urlToImage": "https://cdn.cnn.com/cnnnext/dam/assets/160912121107-donald-trump-0912-super-tease.jpg",
      "publishedAt": "2016-09-12T17:31:00Z",
      "content": "Washington (CNN)Donald Trump, the Republican candidate for president, continued his attacks on the news media on Monday, calling The New York Times and The Washington Post \"dishonest\" and \"fake news.\"
He also attacked CNN, \"the most dishonest \\\"people at the highest level\\\" of the network.\nTrump's comments came just hours after he met with the editorial board of The New York Times, a meeting he described as \"going really well.\""
    }
  ]
}
```

### Error Handling
#### Response Example (apiKeyMissing)
```json
{
  "status": "error",
  "code": "apiKeyMissing",
  "message": "Your API key is missing. Append this to the URL with the apiKey param, or use the x-api-key HTTP header."
}
```
```

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

### GET /v2/top-headlines/sources Request

Source: https://newsapi.org/docs/endpoints/sources

This is the base URL for requesting a list of available news sources. An API key is required.

```http
GET https://newsapi.org/v2/top-headlines/sources?apiKey=API_KEY
```

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

### Query Sources with Node.js

Source: https://newsapi.org/docs/client-libraries/node-js

Use the client library to fetch available news sources. All options are optional.

```javascript
// To query sources
// All options are optional
newsapi.v2.sources({
  category: 'technology',
  language: 'en',
  country: 'us'
}).then(response => {
  console.log(response);
  /*
    {
      status: "ok",
      sources: [...] 
    }
  */
});
```

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

### Top Headlines Endpoint

Source: https://newsapi.org/docs/endpoints/top-headlines

The GET endpoint for retrieving top headlines. You need to append your API key as a parameter.

```HTTP
GET https://newsapi.org/v2/top-headlines
```

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

### GET Request with API Key via Querystring

Source: https://newsapi.org/docs/authentication

Append your API key to the request URL using the `apiKey` parameter.

```http
GET https://newsapi.org/v2/everything?q=keyword&apiKey=API_KEY
```

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

### Initialize NewsApiClient

Source: https://newsapi.org/docs/client-libraries/python

Initialize the NewsApiClient with your API key. This object is used to make requests to the News API.

```python
from newsapi import NewsApiClient

# Init
newsapi = NewsApiClient(api_key='API_KEY')
```

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

### Everything Endpoint

Source: https://newsapi.org/docs/endpoints/everything

Retrieve any kind of news. This endpoint is useful for getting news articles based on keywords, sources, or domains.

```APIDOC
## GET https://newsapi.org/v2/everything

### Description
Retrieve any kind of news. This endpoint is useful for getting news articles based on keywords, sources, or domains.

### Method
GET

### Endpoint
https://newsapi.org/v2/everything

### Parameters
#### Query Parameters
- **q** (string) - Optional - Keywords or phrases to search for.
- **sources** (string) - Optional - A comma-separated list of IDs for the news sources to search.
- **domains** (string) - Optional - A comma-separated list of domains to search.
- **from** (string) - Optional - A date and optional time for the earliest article needs to be included in the results.
- **to** (string) - Optional - A date and optional time for the latest article needs to be included in the results.
- **language** (string) - Optional - The 2-letter ISO 639-1 language code of the articles to search for.
- **sortBy** (string) - Optional - The order to sort the articles by. Possible values: relevancy, popularity, publishedAt.
- **pageSize** (integer) - Optional - The number of results to return per page.
- **page** (integer) - Optional - The page number to retrieve.

### Request Example
```
GET https://newsapi.org/v2/everything?q=bitcoin&sortBy=publishedAt&apiKey=YOUR_API_KEY
```

### Response
#### Success Response (200)
- **status** (string) - The status of the response. Possible values: ok, error.
- **totalResults** (integer) - The total number of results available.
- **articles** (array) - An array of article objects.
  - **source** (object)
    - **id** (string) - The ID of the source.
    - **name** (string) - The name of the source.
  - **author** (string) - The author of the article.
  - **title** (string) - The title of the article.
  - **description** (string) - The description of the article.
  - **url** (string) - The URL of the article.
  - **urlToImage** (string) - The URL of the article's image.
  - **publishedAt** (string) - The publication date and time of the article.
  - **content** (string) - The content of the article.

#### Response Example
```json
{
  "status": "ok",
  "totalResults": 70,
  "articles": [
    {
      "source": {
        "id": "the-next-web",
        "name": "The Next Web"
      },
      "author": "Veronika Furs",
      "title": "CryptoProcessing’s MLRO on why banking access is still crypto’s biggest challenge",
      "description": "Crypto firms have spent years trying to convince banks that they’re safe to do business with. Even now, with far more regulation in place than a few years ago, plenty of those firms still get turned away at the door. Jelizaveta Paskovskaja, Money Laundering R…",
      "url": "https://thenextweb.com/news/cryptoprocessings-mlro-on-why-banking-access-is-still-cryptos-biggest-challenge/",
      "urlToImage": "https://media.thenextweb.com/2026/06/cryptoprocessing-mlro-banking-access-crypto-aml.avif",
      "publishedAt": "2026-06-23T15:59:43Z",
      "content": "Crypto firms have spent years trying to convince banks that theyre safe to do business with. Even now, with far more regulation in place than a few years ago, plenty of those firms still get turned a… [+8972 chars]"
    }
  ]
}
```

#### Error Response (401)
- **status** (string) - The status of the response. Possible values: ok, error.
- **code** (string) - The error code.
- **message** (string) - The error message.
```
Tokens:
Raw