Name: Real-Time Stock Price API | Global Market Quotes
Brand: viv-data
SKU: api-viv-data-stock
Availability: InStock
Author: API Market

gia ly bui

# Stock Price API — Real-Time Quotes, Global Markets

## Overview
The Stock Price API provides developers with instant, real-time access to stock market data from global exchanges. This powerful API allows you to retrieve up-to-the-minute stock quotes, including crucial metrics such as current price, daily change, trading volume, and market capitalization for a wide range of symbols. Designed for reliability and speed, it integrates data from reputable financial sources like Yahoo Finance with Alpha Vantage fallback, ensuring high availability and accuracy. Results are intelligently cached for 5 minutes to optimize performance and reduce redundant data fetches.

## Features
*   **Real-Time Stock Quotes**: Access current stock prices and performance metrics instantly.
*   **Global Market Coverage**: Supports all major stock exchanges worldwide, including NYSE, NASDAQ, LSE, TSE, and many more.
*   **Comprehensive Data Points**: Retrieve price, daily change, percentage change, open, high, low, volume, previous close, market cap, and currency.
*   **Reliable Data Sources**: Utilizes Yahoo Finance with Alpha Vantage as a fallback to ensure data consistency and availability.
*   **Performance Optimized**: Results are cached for 5 minutes to provide fast responses and efficient resource usage.
*   **Simple Integration**: Easy-to-use API with clear, JSON-formatted responses.

## Use Cases
1.  **Financial Portfolio Tracking Applications**: Developers can integrate the API into personal finance apps, allowing users to monitor their stock investments with real-time data, track gains/losses, and make informed decisions based on current market conditions. This enhances user engagement and provides critical financial insights.
2.  **Algorithmic Trading Bots & Tools**: Power automated trading systems with precise, up-to-date stock quotes. Trading algorithms can react swiftly to market movements by incorporating real-time price, volume, and change data, enabling better execution strategies and risk management.
3.  **News & Media Financial Reporting**: Financial news platforms, blogs, and content management systems can display live stock prices and market summaries, enriching their content with dynamic data. This helps keep audiences informed with the latest market trends and company valuations.
4.  **Market Research & Analysis Platforms**: Data analysts and researchers can leverage the API to build comprehensive market analysis tools. By fetching historical and real-time data, they can conduct trend analysis, identify trading opportunities, and build predictive models for various industries.
5.  **Educational Financial Simulations**: Create engaging educational platforms or simulation games that mirror real-world stock market dynamics. Students or users can practice trading and investment strategies using live data, providing a practical learning experience without financial risk.


## Pricing
This API operates on a request-based pricing model. One API unit equals one stock quote request. Different pricing tiers are available based on usage volume:
*   **Free Tier**: 500 requests per month.
*   **Pro Tier**: $19.99 per month for 5,000 requests.

## API Documentation

### Base URL
All API requests should be made to: `https://prod.api.market/api/v1/viv-data/stock`

### Authentication
Authentication is handled via API key. Include your API key in the request header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```
### Endpoints

#### Get Real-Time Stock Quote

Retrieve real-time stock information for a given symbol.

**`GET /api/v1/viv-data/stock/quote`**

**Summary:** Quote

**Operation ID:** `quote_quote_get`

**Parameters:**

| Name     | In    | Type   | Required | Description                     |
| :------- | :---- | :----- | :------- | :------------------------------ |
| `symbol` | query | string | true     | Stock symbol, e.g., `AAPL`, `TSLA`, `0700.HK` |

**Responses:**

*   **`200 OK`**: Successful Response
    *   **Content:** `application/json`
    *   **Schema (`StockResult`):**
        ```json
        {
          "symbol": "AAPL",
          "name": "Apple Inc.",
          "price": 195.32,
          "change": 2.15,
          "change_percent": 1.11,
          "open": 193.50,
          "high": 196.10,
          "low": 193.20,
          "volume": 52400000,
          "previous_close": 193.17,
          "exchange": "NASDAQ",
          "currency": "USD",
          "error": null
        }
        ```
    *   **Description of `StockResult` fields:**
        *   `symbol` (string): The stock symbol (e.g., AAPL).
        *   `name` (string, nullable): The company name.
        *   `price` (number, nullable): The current trading price of the stock.
        *   `change` (number, nullable): The absolute change in price since the previous close.
        *   `change_percent` (number, nullable): The percentage change in price since the previous close.
        *   `open` (number, nullable): The opening price of the stock for the current trading day.
        *   `high` (number, nullable): The highest price reached during the current trading day.
        *   `low` (number, nullable): The lowest price reached during the current trading day.
        *   `volume` (integer, nullable): The total number of shares traded during the current day.
        *   `previous_close` (number, nullable): The closing price from the previous trading day.
        *   `exchange` (string, nullable): The stock exchange where the stock is traded (e.g., NASDAQ, NYSE).
        *   `currency` (string): The currency in which the stock is traded (default: USD).
        *   `error` (string, nullable): An error message if the stock symbol could not be found or data retrieved.
*   **`422 Unprocessable Entity`**: Validation Error
    *   **Content:** `application/json`
    *   **Schema (`HTTPValidationError`):** Contains details about why the request input was invalid.

**Example Request (cURL):**

```bash
curl -X GET "https://prod.api.market/api/v1/viv-data/stock/quote?symbol=AAPL" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Example Response (200 OK):**

```json
{
  "symbol": "AAPL",
  "name": "Apple Inc.",
  "price": 195.32,
  "change": 2.15,
  "change_percent": 1.11,
  "open": 193.50,
  "high": 196.10,
  "low": 193.20,
  "volume": 52400000,
  "previous_close": 193.17,
  "exchange": "NASDAQ",
  "currency": "USD",
  "error": null
}
```

---

#### Health Check

Check the health status of the API.

**`GET /api/v1/viv-data/stock/health`**
**`HEAD /api/v1/viv-data/stock/health`**

**Summary:** Health

**Operation ID:** `health_health_get`

**Responses:**

*   **`200 OK`**: Successful Response (usually an empty JSON object or "OK")

**Example Request (cURL):**

```bash
curl -X GET "https://prod.api.market/api/v1/viv-data/stock/health" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Example Response (200 OK):**

```json
{}
```

---

#### Root Endpoint

A basic root endpoint for the API.

**`GET /api/v1/viv-data/stock/`**

**Summary:** Root

**Operation ID:** `root__get`

**Responses:**

*   **`200 OK`**: Successful Response (usually an empty JSON object or a simple message)

**Example Request (cURL):**

```bash
curl -X GET "https://prod.api.market/api/v1/viv-data/stock/" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Example Response (200 OK):**

```json
{}
```

## Status Codes
*   **`200 OK`**: The request was successful, and the API returned the requested data. This is the expected response for successful quote retrievals or health checks.
*   **`400 Bad Request`**: The request could not be understood or processed due to invalid syntax or parameters. Check your request body, query parameters, and headers for correctness.
*   **`401 Unauthorized`**: Authentication failed because the API key was missing, invalid, or expired. Ensure your `x-api-market-key` header is correctly set with a valid API key.
*   **`403 Forbidden`**: The request was valid, but the API key does not have the necessary permissions to access the resource or perform the action.
*   **`404 Not Found`**: The requested resource (e.g., the specific endpoint path) does not exist. Verify the API endpoint URL.
*   **`422 Unprocessable Entity`**: The request was well-formed but could not be processed due to semantic errors in the provided data (e.g., missing required query parameter like `symbol`). The response body will contain details about the validation errors.
*   **`429 Too Many Requests`**: You have sent too many requests in a given amount of time. Implement exponential backoff or respect the rate limit headers if provided.
*   **`500 Internal Server Error`**: An unexpected error occurred on the API server. This typically indicates a problem on our end. Please report the issue if it persists.
*   **`503 Service Unavailable`**: The API service is temporarily unable to handle the request, usually due to maintenance or overload. Retry the request after a short delay.



## Implementation Guide

This section provides practical code examples to integrate with the Stock Price API. Since the API is synchronous, a single request directly returns the desired stock quote.

### Example Code

#### JavaScript

```javascript
// JavaScript example for synchronous API call
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/viv-data/stock";

async function getStockQuote(symbol) {
  try {
    const response = await fetch(`${baseUrl}/quote?symbol=${symbol}`, {
      method: "GET",
      headers: {
        "x-api-market-key": apiKey,
        "Content-Type": "application/json"
      }
    });

    if (response.status === 401) {
      throw new Error("Authentication failed: Invalid API key.");
    }
    if (response.status === 429) {
      throw new Error("Rate limit exceeded. Please try again later.");
    }
    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`API error: ${response.status} ${response.statusText} - ${JSON.stringify(errorData)}`);
    }

    const data = await response.json();
    
    if (data.error) {
        throw new Error(`API returned an error for symbol ${symbol}: ${data.error}`);
    }

    console.log(`Stock quote for ${symbol}:`);
    console.log(data);
    return data;

  } catch (error) {
    console.error("Error fetching stock quote:", error);
    throw error; // Re-throw to allow further handling
  }
}

// Example usage:
getStockQuote("AAPL");
// getStockQuote("TSLA");
// getStockQuote("0700.HK");
// getStockQuote("INVALID_SYMBOL"); // Example of an invalid symbol
```

#### Python

```python
# Python example for synchronous API call
import requests
import json

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/viv-data/stock"

def get_stock_quote(symbol):
    headers = {
        "x-api-market-key": API_KEY,
        "Content-Type": "application/json"
    }
    params = {
        "symbol": symbol
    }

    try:
        response = requests.get(
            f"{BASE_URL}/quote",
            headers=headers,
            params=params,
            timeout=30 # Recommended timeout for synchronous requests
        )

        if response.status_code == 401:
            raise Exception("Authentication failed: Invalid API key.")
        if response.status_code == 429:
            raise Exception("Rate limit exceeded. Please try again later.")
        if not response.ok:
            error_data = response.json()
            raise Exception(f"API error: {response.status_code} {response.reason} - {json.dumps(error_data)}")

        data = response.json()
        
        if data.get("error"):
            raise Exception(f"API returned an error for symbol {symbol}: {data['error']}")

        print(f"Stock quote for {symbol}:")
        print(json.dumps(data, indent=2))
        return data

    except requests.exceptions.Timeout:
        print(f"Request timed out for symbol {symbol}. Please try again.")
    except requests.exceptions.ConnectionError:
        print(f"Connection error for symbol {symbol}. Check network connectivity.")
    except Exception as e:
        print(f"Error fetching stock quote: {e}")
    return None

# Example usage:
get_stock_quote("AAPL")
# get_stock_quote("TSLA")
# get_stock_quote("0700.HK")
# get_stock_quote("INVALID_SYMBOL") # Example of an invalid symbol
```

#### cURL

```bash
# cURL example for synchronous API call

# Get quote for Apple (AAPL)
curl -X GET "https://prod.api.market/api/v1/viv-data/stock/quote?symbol=AAPL" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY"

# Get quote for Tesla (TSLA)
curl -X GET "https://prod.api.market/api/v1/viv-data/stock/quote?symbol=TSLA" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY"

# Get quote for Tencent (0700.HK) - Hong Kong Exchange
curl -X GET "https://prod.api.market/api/v1/viv-data/stock/quote?symbol=0700.HK" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY"

# Example of an invalid symbol (might return an error in the JSON response)
curl -X GET "https://prod.api.market/api/v1/viv-data/stock/quote?symbol=INVALID_SYMBOL" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

### Performance Optimization
*   **Client-Side Caching**: Although the API caches results for 5 minutes, you can implement additional client-side caching for frequently requested symbols to further reduce API calls and improve application responsiveness.
*   **Batching Requests**: If your application needs quotes for multiple symbols, consider if your use case allows for sequential requests with small delays rather than overwhelming the API with many parallel requests.
*   **Optimize Query Parameters**: Only request the data you need. For the `/quote` endpoint, this means ensuring your `symbol` parameter is accurate to avoid unnecessary API calls for invalid symbols.
*   **Monitor Usage**: Keep an eye on your API usage through the API.market dashboard to ensure you stay within your tier limits and upgrade if necessary.

## FAQ
**Q: What exchanges are supported by the API?**

A: The API supports all major stock exchanges worldwide, including NYSE, NASDAQ, LSE, TSE, and many more. If you have a specific symbol, try querying it; if it's not found, you'll receive an appropriate error message.

**Q: What data sources does the API use?**

A: The API primarily sources data from Yahoo Finance, with Alpha Vantage as a fallback mechanism to ensure high availability and reliability.

**Q: How up-to-date is the stock data?**

A: The API provides real-time quotes. Results are cached for 5 minutes to balance data freshness with performance and prevent excessive load on upstream providers.

**Q: Is there a free tier available for testing?**

A: Yes, a free tier is available, offering 500 requests per month, perfect for development and testing.

**Q: What happens if I exceed my API request limit?**

A: If you exceed your monthly request limit, you will receive a `429 Too Many Requests` HTTP status code. You can upgrade your plan or wait until the next billing cycle.

**Q: How do I handle errors from the API?**

A: Always check the HTTP status code and the response body for error details. Implement try-catch blocks and conditional logic to manage different error types, such as invalid symbols, authentication failures, or rate limits.

**Q: Can I request historical data using this API?**

A: No, this API is specifically designed for real-time stock quotes. It does not provide historical data.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.

Access real-time stock prices, daily changes, volume, and market cap for global exchanges. Integrate reliable financial data into your applications with ease.