News

Retrieve news articles for any supported stock symbol.

Making Requests

Use the news() method on the stocks resource to fetch news articles. The method supports multiple output formats:

Output Format	Return Type	Description
DATAFRAME	pandas.DataFrame or polars.DataFrame	Returns a DataFrame with news articles indexed by symbol (default).
INTERNAL	list[StockNews] or list[StockNewsHumanReadable]	Returns a list of StockNews objects. When use_human_readable=True, returns a list of StockNewsHumanReadable objects with capitalized field names.
JSON	dict	Returns the raw JSON response as a dictionary.
CSV	str	Writes CSV data to file and returns the filename string.

news

def news(
    symbol: str,
    *,
    date: str | datetime.datetime = None,
    from_date: str | datetime.datetime = None,
    to_date: str | datetime.datetime = None,
    countback: int = None,
    output_format: OutputFormat = OutputFormat.DATAFRAME,
    date_format: DateFormat = None,
    columns: list[str] = None,
    add_headers: bool = None,
    use_human_readable: bool = False,
    mode: Mode = None,
    filename: str | Path = None,
) -> list[StockNews] | list[StockNewsHumanReadable] | dict | str | MarketDataClientErrorResult

Fetches news articles for a stock symbol. The symbol parameter can be passed as the first positional argument or as a keyword argument. All other parameters must be keyword-only.

Parameters

• symbol (str)

  The stock symbol for which to fetch news articles.

• date (str | datetime.datetime, optional)

  Specific date for the news articles.

• from_date (str | datetime.datetime, optional)

  Start date for the date range.

• to_date (str | datetime.datetime, optional)

  End date for the date range.

• countback (int, optional)

  Number of news articles to return, counting backwards from the to_date.

• output_format (OutputFormat, optional)

  The format of the returned data. Defaults to OutputFormat.DATAFRAME. See Settings for details.

• date_format (DateFormat, optional)

  The date format to use in the response. Defaults to DateFormat.UNIX. See Settings for details.

• columns (optional)

  Specify which columns to include in the response. See Settings for details.

• add_headers (optional)

  Whether to include headers in the response. See Settings for details.

• use_human_readable (optional)

  Whether to use human-readable format for values. Only applies when output_format=OutputFormat.INTERNAL. See Settings for details.

• mode (Mode, optional)

  The data feed mode to use. See Settings for details.

• filename (str | Path, optional)

  File path for CSV output (only used with output_format=OutputFormat.CSV).

Returns

• list[StockNews] | list[StockNewsHumanReadable] | dict | str | MarketDataClientErrorResult

  The news articles in the requested format, or a MarketDataClientErrorResult if an error occurred.

Example (DataFrame)

from marketdata.client import MarketDataClient

client = MarketDataClient()

# Get stock news as DataFrame (default)
# symbol can be passed positionally or as keyword
df = client.stocks.news("AAPL")
# or
df = client.stocks.news(symbol="AAPL")

print(df)

Example (Internal)

from marketdata.client import MarketDataClient
from marketdata.input_types.base import OutputFormat

client = MarketDataClient()

# Get stock news as internal objects
news_list = client.stocks.news("AAPL", output_format=OutputFormat.INTERNAL)

# Access individual news article properties
for news in news_list:
    print(f"Symbol: {news.symbol}")
    print(f"Headline: {news.headline}")
    print(f"Source: {news.source}")
    print(f"Publication Date: {news.publicationDate}")
    print(f"Updated: {news.updated}")

Example (JSON)

from marketdata.client import MarketDataClient
from marketdata.input_types.base import OutputFormat

client = MarketDataClient()

# Get stock news as JSON
news = client.stocks.news("AAPL", output_format=OutputFormat.JSON)

print(news)

Example (CSV)

from marketdata.client import MarketDataClient
from marketdata.input_types.base import OutputFormat
from pathlib import Path

client = MarketDataClient()

# Get stock news as CSV
csv_file = client.stocks.news(
    "AAPL",
    output_format=OutputFormat.CSV,
    filename=Path("news.csv")
)

print(f"CSV file saved to: {csv_file}")

Example (Human Readable)

from marketdata.client import MarketDataClient
from marketdata.input_types.base import OutputFormat

client = MarketDataClient()

# Get stock news in human-readable format
news_list = client.stocks.news(
    "AAPL",
    output_format=OutputFormat.INTERNAL,
    use_human_readable=True
)

# Access individual news article properties
for news in news_list:
    print(f"Symbol: {news.Symbol}")
    print(f"Headline: {news.headline}")
    print(f"Source: {news.source}")
    print(f"Publication Date: {news.publicationDate}")
    print(f"Date: {news.Date}")

StockNews

@dataclass
class StockNews:
    symbol: str
    headline: str
    content: str
    source: str
    publicationDate: datetime.datetime
    updated: datetime.datetime

StockNews represents a single news article for a stock, encapsulating headline, content, source, and publication information.

Properties

• symbol (str): The stock symbol.
• headline (str): The news headline.
• content (str): The news article content.
• source (str): The news source.
• publicationDate (datetime.datetime): The publication date (automatically converted from timestamp).
• updated (datetime.datetime): The time when the news was last updated (automatically converted from timestamp).

Notes

• The publicationDate and updated fields are automatically converted to datetime.datetime objects from Unix timestamps.

StockNewsHumanReadable

@dataclass
class StockNewsHumanReadable:
    Symbol: str
    headline: str
    content: str
    source: str
    publicationDate: datetime.datetime
    Date: datetime.datetime

StockNewsHumanReadable represents a news article in human-readable format with capitalized field names and formatted values.

Properties

• Symbol (str): The stock symbol.
• headline (str): The news headline.
• content (str): The news article content.
• source (str): The news source.
• publicationDate (datetime.datetime): The publication date (automatically converted from timestamp).
• Date (datetime.datetime): The time when the news was last updated (automatically converted from timestamp).

Notes

• The publicationDate and Date fields are automatically converted to datetime.datetime objects from Unix timestamps.
• Field names use capitalized format with underscores where applicable (e.g., Symbol instead of symbol, Date instead of updated).