> ## Documentation Index
> Fetch the complete documentation index at: https://finance.chiefpriest.design/llms.txt
> Use this file to discover all available pages before exploring further.

# Symbol Search

> Search for stocks, ETFs, mutual funds, and other securities

Search for financial instruments by company name, symbol, or keywords. This endpoint helps you find the correct ticker symbols for your analysis.

## Parameters

<ParamField query="q" type="string" required>
  Search query (company name, symbol, or keywords)
</ParamField>

## Response

<ResponseField name="bestMatches" type="array">
  Array of search results matching the query

  <Expandable title="Search result properties">
    <ResponseField name="symbol" type="string">
      Stock ticker symbol
    </ResponseField>

    <ResponseField name="name" type="string">
      Company or security name
    </ResponseField>

    <ResponseField name="type" type="string">
      Type of security (Equity, ETF, Mutual Fund, etc.)
    </ResponseField>

    <ResponseField name="region" type="string">
      Geographic region
    </ResponseField>

    <ResponseField name="marketOpen" type="string">
      Market open time
    </ResponseField>

    <ResponseField name="marketClose" type="string">
      Market close time
    </ResponseField>

    <ResponseField name="timezone" type="string">
      Market timezone
    </ResponseField>

    <ResponseField name="currency" type="string">
      Trading currency
    </ResponseField>

    <ResponseField name="matchScore" type="string">
      Relevance score for the search result
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://stocks-dev.up.railway.app/api/v1/search?q=apple" \
    -H "X-API-Key: your_api_key"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('/api/v1/search?q=apple', {
    headers: {
      'X-API-Key': 'your_api_key'
    }
  });
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://stocks-dev.up.railway.app/api/v1/search',
      params={'q': 'apple'},
      headers={'X-API-Key': 'your_api_key'}
  )
  data = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "bestMatches": [
      {
        "symbol": "AAPL",
        "name": "Apple Inc.",
        "type": "Equity",
        "region": "United States",
        "marketOpen": "09:30",
        "marketClose": "16:00",
        "timezone": "UTC-04",
        "currency": "USD",
        "matchScore": "1.0000"
      },
      {
        "symbol": "APLE",
        "name": "Apple Hospitality REIT, Inc.",
        "type": "Equity",
        "region": "United States",
        "marketOpen": "09:30",
        "marketClose": "16:00",
        "timezone": "UTC-04",
        "currency": "USD",
        "matchScore": "0.8571"
      },
      {
        "symbol": "APLD",
        "name": "Applied Digital Corporation",
        "type": "Equity",
        "region": "United States",
        "marketOpen": "09:30",
        "marketClose": "16:00",
        "timezone": "UTC-04",
        "currency": "USD",
        "matchScore": "0.7500"
      }
    ]
  }
  ```
</ResponseExample>

## Search Tips

### Company Names

Search by full or partial company names:

* `apple` → Apple Inc. (AAPL)
* `microsoft` → Microsoft Corporation (MSFT)
* `tesla` → Tesla, Inc. (TSLA)

### Ticker Symbols

Search by exact or partial symbols:

* `AAPL` → Apple Inc.
* `MSFT` → Microsoft Corporation
* `QQQ` → Invesco QQQ Trust

### Keywords

Search by industry or business keywords:

* `electric vehicle` → Tesla, Rivian, etc.
* `cloud computing` → Amazon, Microsoft, etc.
* `semiconductor` → NVIDIA, Intel, AMD, etc.

## Security Types

* **Equity**: Common stocks
* **ETF**: Exchange-traded funds
* **Mutual Fund**: Mutual funds
* **Index**: Market indices
* **Cryptocurrency**: Digital assets
* **Forex**: Currency pairs
* **Commodity**: Commodity futures

## Use Cases

* **Symbol Lookup**: Find correct ticker symbols
* **Company Discovery**: Discover companies in specific sectors
* **Investment Research**: Explore similar companies
* **Data Validation**: Verify symbol accuracy before analysis

## Data Source

This endpoint uses Alpha Vantage search functionality with comprehensive coverage of global markets.

## Notes

* Results are ranked by relevance (matchScore)
* Search is case-insensitive
* Supports partial matches for flexible searching
* Maximum 10 results returned per query
* Includes both US and international securities