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

# Company Search

> Search listed companies by name, ticker or keyword (Chinese/English) and return matching company profiles

## 公司搜索

**URL**: `/v1/stock/company-search`
**方法**: `POST`\
**描述**: 通过公司名称、股票代码或关键词（支持中英文）搜索上市公司，返回最匹配的公司信息列表。

### 请求参数

| 参数名    | 类型   | 必填 | 描述                                          |
| ------ | ---- | -- | ------------------------------------------- |
| query  | str  | 是  | 搜索关键词：公司名称 / 简称 / 股票代码 / 自由文本，如 `腾讯`、`AAPL` |
| top\_k | int  | 否  | 返回的最大公司数量，默认 `10`                           |
| strict | bool | 否  | 是否启用严格关键词匹配，默认 `true`                       |

### 响应参数

| 参数名                   | 类型    | 描述                                |
| --------------------- | ----- | --------------------------------- |
| companies             | array | 匹配到的公司列表，按相关度排序。                  |
|   id                  | int   | 公司 ID。                            |
|   symbol              | str   | 完整股票标识，如 `HK:00700`。              |
|   market              | str   | 市场代码，如 `HK` / `US` / `SH` / `SZ`。 |
|   region              | str   | 地区代码。                             |
|   ticker              | str   | 股票代码，如 `00700` / `AAPL`。          |
|   name                | str   | 公司显示名称。                           |
|   full\_name          | str   | 公司全称。                             |
|   chinese\_name       | str   | 中文名称。                             |
|   chinese\_full\_name | str   | 中文全称。                             |
|   english\_name       | str   | 英文名称。                             |
|   english\_full\_name | str   | 英文全称。                             |
|   synonyms            | str   | 别名/同义词（逗号分隔）。                     |
|   logo                | str   | 公司 Logo 地址。                       |
|   rank                | int   | 相关度排序值（越小越靠前）。                    |
| words                 | array | 从查询中抽取的关键词（严格匹配时返回）。              |

### 请求示例

**cURL**

```bash theme={null}
curl -X POST https://api.reportify.cn/v1/stock/company-search \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "query": "腾讯",
    "top_k": 3
}'
```

**Python**

```python theme={null}
import requests

url = "https://api.reportify.cn/v1/stock/company-search"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 支持中文名称、英文名称或股票代码
data = {"query": "腾讯", "top_k": 3}

response = requests.post(url, headers=headers, json=data)
print(response.json())
```

### 响应示例

```json theme={null}
{
  "companies": [
    {
      "id": 1407,
      "symbol": "HK:00700",
      "market": "HK",
      "region": "HK",
      "ticker": "00700",
      "name": "腾讯控股",
      "full_name": "腾讯控股有限公司",
      "chinese_name": "腾讯控股",
      "chinese_full_name": "腾讯控股有限公司",
      "english_name": "TENCENT",
      "english_full_name": "Tencent Holdings Limited",
      "synonyms": "腾讯,腾讯控股",
      "logo": "https://files.reportify.cn/logos_all/700.HK.svg",
      "rank": 1
    }
  ],
  "words": []
}
```

<Note>
  `query` 为空时返回空列表 `{"companies": [], "words": []}`。
</Note>

### 错误响应

| 状态码 | 描述                   |
| --- | -------------------- |
| 403 | 未认证（缺少或无效的 API Key）。 |
| 422 | 请求参数验证失败。            |


## OpenAPI

````yaml POST /v1/stock/company-search
openapi: 3.1.0
info:
  title: Reportify API
  version: 1.0.0
  description: API documentation for Reportify's document management and search services.
servers:
  - url: https://api.reportify.cn
    description: Production server
security:
  - BearerAuth: []
paths:
  /v1/stock/company-search:
    post:
      tags:
        - openapi-v2-stock
      summary: Company Search
      description: >-
        Search listed companies by name, ticker or keyword (Chinese/English) and
        return matching company profiles
      operationId: company_search_reportify_api_v2_stock_company_search_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyVectorSearchRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyVectorSearchResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - BearerAuth: []
components:
  schemas:
    CompanyVectorSearchRequest:
      properties:
        query:
          type: string
          title: Query
          description: Search keyword - company name, ticker or free text (Chinese/English)
          example: 腾讯
        top_k:
          type: integer
          title: Top K
          description: Max number of companies to return
          default: 10
        strict:
          type: boolean
          title: Strict
          description: Whether to apply strict keyword matching
          default: true
      type: object
      required:
        - query
      title: CompanyVectorSearchRequest
      description: Input schema for company search
    CompanyVectorSearchResponse:
      properties:
        companies:
          type: array
          items:
            $ref: '#/components/schemas/CompanyRead'
          title: Companies
          description: Matching companies ordered by relevance
        words:
          type: array
          items:
            type: string
          title: Words
          description: Extracted search keywords
      type: object
      title: CompanyVectorSearchResponse
      description: Response schema for company search
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CompanyRead:
      properties:
        id:
          type: integer
          title: Id
        symbol:
          type: string
          title: Symbol
          description: Full stock symbol, e.g. HK:00700
        market:
          type: string
          title: Market
          description: Market code, e.g. HK / US / SH / SZ
        region:
          type: string
          title: Region
        ticker:
          type: string
          title: Ticker
          description: Stock ticker, e.g. 00700 / AAPL
        name:
          type: string
          title: Name
          description: Company display name
        full_name:
          type: string
          title: Full Name
        chinese_name:
          type: string
          title: Chinese Name
        chinese_full_name:
          type: string
          title: Chinese Full Name
        english_name:
          type: string
          title: English Name
        english_full_name:
          type: string
          title: English Full Name
        synonyms:
          type: string
          title: Synonyms
        logo:
          type: string
          title: Logo
          description: Company logo URL
        rank:
          type: integer
          title: Rank
        following:
          type: boolean
          title: Following
        status:
          type: integer
          title: Status
      type: object
      title: CompanyRead
      description: Company profile returned by company search
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Enter your Bearer token

````