# Yahoo Finance

## Overview

| Property | Value |
|----------|-------|
| **Status** | private |
| **Method** | `GET` |
| **Endpoint** | `/v2/yahoo/finance` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 1 credit per call |
| **Documentation** | https://www.piloterr.com/library/yahoo-finance |

## Description

Retrieve a real-time stock quote from Yahoo Finance by ticker symbol, with price, market cap, PE ratio, EPS, volume, and analyst data as structured JSON.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/yahoo/finance' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Stock quote for AAPL

```json
{
  "ask": 269.58,
  "bid": 268.16,
  "beta": 1.11,
  "name": "Apple Inc.",
  "sector": "Technology",
  "symbol": "AAPL",
  "currency": "USD",
  "exchange": "NasdaqGS",
  "industry": "Consumer Electronics",
  "forward_pe": 31.55,
  "market_cap": 3950000000000,
  "quote_type": "EQUITY",
  "total_cash": 66910000000,
  "total_debt": 101350000000,
  "eps_forward": 8.53,
  "revenue_ttm": 435620000000,
  "trailing_pe": 34.1,
  "market_state": "REGULAR",
  "payout_ratio": 0.1318,
  "dividend_rate": 1.04,
  "earnings_date": "2026-04-30T00:00:00.000Z",
  "price_to_book": 44.98,
  "profit_margin": 0.2704,
  "average_volume": 44334911,
  "dividend_yield": 0.0038,
  "net_income_ttm": 117780000000,
  "price_to_sales": 9.25,
  "enterprise_value": 3990000000000,
  "ex_dividend_date": "2026-02-09T00:00:00.000Z",
  "return_on_equity": 1.5202,
  "target_low_price": 215,
  "target_high_price": 350,
  "target_mean_price": 297.88,
  "fifty_two_week_low": 193.25,
  "recommendation_key": "buy",
  "fifty_two_week_high": 288.62,
  "recommendation_mean": 2.1,
  "regular_market_open": 270.5,
  "regular_market_price": 269.08,
  "regular_market_change": -1.09,
  "regular_market_volume": 2320771,
  "average_volume_3_month": 52180000,
  "regular_market_day_low": 268.75,
  "regular_market_day_high": 270.91,
  "eps_trailing_twelve_months": 7.89,
  "number_of_analyst_opinions": 42,
  "regular_market_change_percent": -0.4,
  "regular_market_previous_close": 270.17
}
```

## Documentation

## Overview

Yahoo Finance protects its data with Cloudflare, which blocks virtually all automated HTTP clients. Piloterr handles the bypass in full, so you send one GET request with a ticker symbol and receive a complete, structured JSON quote in return. No proxy management, no browser automation, no parsing.

The endpoint returns price data, volume, key fundamentals (PE ratio, EPS, market cap), dividend details, and analyst consensus for any equity, ETF, index, or crypto ticker available on Yahoo Finance.

## Quickstart

```
GET https://api.piloterr.com/v2/yahoo/finance?query=AAPL
```

## Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Ticker symbol (e.g. `AAPL`, `TSLA`, `^GSPC`, `BTC-USD`) |

## Response fields

| Field | Type | Description |
|---|---|---|
| `symbol` | string | Ticker symbol |
| `name` | string | Full company or asset name |
| `exchange` | string | Exchange where the asset trades |
| `regular_market_price` | number | Current or last session price |
| `regular_market_change_percent` | number | Percentage price change |
| `fifty_two_week_high` | number | 52-week high |
| `fifty_two_week_low` | number | 52-week low |
| `market_cap` | integer | Market capitalisation |
| `trailing_pe` | number | Trailing P/E ratio |
| `eps_trailing_twelve_months` | number | Trailing EPS |
| `recommendation_key` | string | Analyst consensus |
| `target_mean_price` | number | Mean 12-month price target |

## Notes

- Indices and crypto tickers do not return all fundamental fields.
- Yahoo Finance applies Cloudflare protection. Piloterr handles the bypass transparently.

## Main use cases

- Monitor live stock prices and trigger alerts when positions move beyond thresholds
- Pull fundamentals into a valuation model or dashboard without a paid data vendor
- Track analyst consensus changes to inform quantitative strategies
- Enrich investment research records with fresh Yahoo Finance data in real time
- Build a fintech data feed without managing scraping infrastructure