# News (PHP SDK)

Retrieve news articles for a stock symbol.

> [!CAUTION]
> **Beta Endpoint**
>
> The news endpoint is currently in beta. Features and response formats may change.

## Making Requests

Use the `news()` method on the `stocks` resource to fetch news articles:

| Output Format | Return Type | Description                                                      |
|---------------|-------------|------------------------------------------------------------------|
| **JSON**      | `News`      | Returns a News object containing news articles (default).        |
| **CSV**       | `News`      | Returns a News object with CSV data accessible via `getCsv()`.   |
| **HTML**      | `News`      | Returns a News object with HTML data accessible via `getHtml()`. |

> [!WARNING]
> **HTML Not Yet Available**
>
> `Format::HTML` is included for forward compatibility, but HTML responses are not currently implemented by the Market Data API.

<a name="news"></a>
## news

```php
public function news(
    string $symbol,
    ?string $from = null,
    ?string $to = null,
    ?int $countback = null,
    ?string $date = null,
    ?Parameters $parameters = null
): News
```

Retrieve news articles for a given stock symbol.

### Parameters

- `symbol` (string)

  The stock ticker symbol (e.g., "AAPL").

- `from` (string, optional)

  The earliest news to include. If omitted without `countback`, returns recent news. Accepted formats: ISO 8601, Unix timestamp.

- `to` (string, optional)

  The latest news to include. Accepted formats: ISO 8601, Unix timestamp.

- `countback` (int, optional)

  Number of news articles to return before `to`. Use instead of `from`.

- `date` (string, optional)

  Retrieve news for a specific day. Accepted formats: ISO 8601, Unix timestamp.

- `parameters` ([Parameters](https://www.marketdata.app/docs/sdk/php/parameters), optional)

  Universal parameters for customizing the output format. See [Parameters](https://www.marketdata.app/docs/sdk/php/parameters) for details.

### Returns

- `News`

  A News response object containing an array of Article objects.

### Example (Quick Display)

```php
<?php

use MarketDataApp\Client;

$client = new Client();

// Get news and display with a single line
$news = $client->stocks->news('AAPL', from: '2024-01-01');
echo $news;

// Or display individual articles
foreach ($news->articles as $article) {
    echo $article . "\n\n";
}
```

**Output**

```
News: 3 articles (status: ok)
AAPL: Apple Reports Record Q1 Earnings
  Published: Jan 25, 2024 4:30 PM  Source: https://www.reuters.com/...
  Content: Apple Inc reported record quarterly earnings on Thursday...

AAPL: Apple Reports Record Q1 Earnings
  Published: Jan 25, 2024 4:30 PM  Source: https://www.reuters.com/...
  Content: Apple Inc reported record quarterly earnings on Thursday...
```

### Example (Recent News)

```php
<?php

use MarketDataApp\Client;

$client = new Client();

// Get recent news for AAPL
$news = $client->stocks->news('AAPL');

foreach ($news->articles as $article) {
    echo "Symbol: " . $article->symbol . "\n";
    echo "Title: " . $article->headline . "\n";
    echo "Source: " . $article->source . "\n";
    echo "Published: " . $article->publication_date->format('Y-m-d H:i') . "\n";
    echo "Content: " . substr($article->content, 0, 100) . "...\n\n";
}
```

**Output**

```
Symbol: AAPL
Title: Apple Reports Record Q1 Earnings
Source: https://www.reuters.com/technology/...
Published: 2024-01-25 16:30
Content: Apple Inc reported record quarterly earnings on Thursday...
```

### Example (Date Range)

```php
<?php

use MarketDataApp\Client;

$client = new Client();

// Get news for a specific date range
$news = $client->stocks->news(
    symbol: 'AAPL',
    from: '2024-01-01',
    to: '2024-01-31'
);

if ($news->status === 'ok') {
    echo "Found " . count($news->articles) . " articles:\n\n";

    foreach ($news->articles as $article) {
        echo "- " . $article->headline . "\n";
        echo "  Published: " . $article->publication_date->format('Y-m-d H:i') . "\n\n";
    }
}
```

### Example (Specific Date)

```php
<?php

use MarketDataApp\Client;

$client = new Client();

// Get news for a specific date
$news = $client->stocks->news(
    symbol: 'AAPL',
    date: '2024-01-25'
);

echo "News for January 25, 2024:\n";
echo "==========================\n\n";

foreach ($news->articles as $article) {
    echo "* " . $article->headline . "\n";
    echo "  " . $article->source . " | " . $article->publication_date->format('H:i') . "\n\n";
}
```

### Example (CSV)

```php
<?php

use MarketDataApp\Client;
use MarketDataApp\Endpoints\Requests\Parameters;
use MarketDataApp\Enums\Format;

$client = new Client();

// Get news as CSV
$news = $client->stocks->news(
    symbol: 'AAPL',
    from: '2024-01-01',
    parameters: new Parameters(format: Format::CSV)
);

echo $news->getCsv();
```

<a name="News"></a>
## News

```php
class News extends ResponseBase
{
    public string $status;
    /** @var Article[] */
    public array $articles;
}
```

Represents news articles for a stock. Contains an array of `Article` objects, each representing a single news article.

### Properties

- `status` (string): Response status (`"ok"` or `"no_data"`).
- `articles` (Article[]): Array of Article objects containing individual news article data.

### Methods

- `getCsv()`: Returns the raw CSV data (when using `Format::CSV`).
- `getHtml()`: Returns the raw HTML data (when using `Format::HTML`).
- `isJson()`: Returns `true` if the response contains JSON data.

<a name="Article"></a>
## Article

```php
class Article
{
    public string $symbol;
    public string $headline;
    public string $content;
    public string $source;
    public Carbon $publication_date;
}
```

Represents a single news article.

### Properties

- `symbol` (string): The stock ticker symbol this article relates to.
- `headline` (string): The article headline/title.
- `content` (string): The content of the article, if available. May include captions, copyright notices, and other elements that may need filtering.
- `source` (string): The source URL where the news appeared.
- `publication_date` (Carbon): The date the news was published on the source website.