Metadata-Version: 2.4
Name: aquery-sdk
Version: 1.0.1
Summary: A-Query Open API Python SDK - A股20年全量数据查询服务
Author: superxu520
License: MIT
Project-URL: Homepage, https://huggingface.co/spaces/superxu520/A-query
Project-URL: Documentation, https://huggingface.co/spaces/superxu520/A-query
Project-URL: Repository, https://huggingface.co/spaces/superxu520/A-query
Project-URL: Issues, https://huggingface.co/spaces/superxu520/A-query/discussions
Keywords: aquery,a-share,stock,finance,tushare,quant
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=1.3.0
Requires-Dist: requests>=2.25.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Dynamic: license-file

---
title: A-Query Open API
emoji: 📊
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
---

# A-Query Open API

A股20年全量数据查询服务 - 统一API接口

## 项目概述

基于Hugging Face数据集构建的A股数据查询服务，提供统一、高效、易用的数据查询接口。

**数据范围**: 2000年-2026年，覆盖全部A股上市公司  
**数据来源**: Tushare Pro  
**存储位置**: Hugging Face Datasets

## 快速开始

### 1. 安装客户端

```bash
pip install pandas requests
# 然后将client文件夹复制到你的项目中
```

### 2. 使用Python SDK

```python
from client import AQueryClient

# 初始化客户端
client = AQueryClient(token="your_token")

# 查询股票基础信息
df = client.stock_basic(market="主板")
print(df.head())

# 查询个股历史数据
df = client.daily_history(
    ts_code="000001.SZ",
    start_date=20240101,
    end_date=20241231,
    fields=["trade_date", "open", "close", "vol", "pe"]
)
print(df)

# 查询某日全市场数据
df = client.daily_all(
    trade_date=20240320,
    fields=["ts_code", "close", "pe", "net_mf_amount"]
)
print(df.head(10))
```

### 3. HTTP API调用

```bash
curl -X POST https://your-space.hf.space/api/v1/query \
  -H "Content-Type: application/json" \
  -H "X-Token: your_token" \
  -d '{
    "api_name": "daily_history",
    "params": {
      "ts_code": "000001.SZ",
      "start_date": 20240101,
      "end_date": 20240131
    },
    "fields": "trade_date,open,high,low,close,vol"
  }'
```

## 支持的API列表

| api_name | 数据集 | 说明 | 主要参数 |
|----------|--------|------|----------|
| stock_basic | A_meta_info | 股票基础信息 | ts_code, market |
| trade_cal | A_meta_info | 交易日历 | start_date, end_date |
| company_info | A_meta_info | 公司信息 | ts_code |
| industry_sw | A_meta_info | 申万行业映射 | ts_code, industry_level |
| industry_sw_class | A_meta_info | 申万行业分类 | level |
| fina_indicator | A_meta_info | 财务指标 | ts_code, end_date |
| daily | A_by_date | 日线行情 | ts_code, trade_date, start_date, end_date |
| daily_all | A_by_date | 某日全市场 | trade_date |
| daily_history | A_by_code | 个股历史 | ts_code, start_date, end_date |

## 统一接口规范

### 请求格式

```json
{
  "api_name": "daily_history",
  "token": "your_token",
  "params": {
    "ts_code": "000001.SZ",
    "start_date": 20240101,
    "end_date": 20241231
  },
  "fields": "trade_date,open,close,vol"
}
```

### 响应格式

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "fields": ["trade_date", "open", "close", "vol"],
    "items": [
      [20240102, 9.5, 9.7, 1000000],
      [20240103, 9.7, 9.8, 1200000]
    ],
    "count": 2,
    "has_more": false
  },
  "request_id": "req_abc123"
}
```

## 本地部署

### 1. 克隆项目

```bash
git clone <repository-url>
cd a-query
```

### 2. 安装依赖

```bash
pip install -r requirements.txt
```

### 3. 运行服务

```bash
python -m uvicorn app.main:app --host 0.0.0.0 --port 7860 --reload
```

### 4. Docker部署

```bash
docker build -t aquery-api .
docker run -p 7860:7860 aquery-api
```

## Hugging Face Space部署

1. 在Hugging Face创建新的Space，选择Docker模板
2. 将代码推送到Space仓库
3. 配置环境变量（如果需要）
4. 访问Space URL查看API文档

## 查询示例

### 示例1: 获取某股票历史数据

```python
df = client.daily_history(
    ts_code="000001.SZ",
    start_date=20240101,
    end_date=20241231
)
```

### 示例2: 获取某日全市场数据

```python
df = client.daily_all(
    trade_date=20240320,
    fields=["ts_code", "close", "pe", "net_mf_amount", "total_mv"]
)
```

### 示例3: 条件选股

```python
# 查询某日PE<20且净流入>1亿的股票
df = client.daily_all(trade_date=20240320)
df = df[(df['pe'] < 20) & (df['net_mf_amount'] > 1e8)]
```

### 示例4: 获取财务指标

```python
df = client.fina_indicator(
    ts_code="000001.SZ",
    fields=["end_date", "roe", "eps", "grossprofit_margin"]
)
```

## 性能指标

| 场景 | 数据量 | 响应时间 |
|------|--------|----------|
| 股票基础信息 | 5,200条 | < 50ms |
| 个股全历史 | 5,000条 | < 200ms |
| 单日全市场 | 5,200条 | < 100ms |
| 时间段截面 | 100万条 | < 2s |

## 项目结构

```
.
├── app/                    # FastAPI服务端
│   ├── main.py            # 应用入口
│   ├── core/              # 配置、认证
│   ├── routers/           # API路由
│   └── services/          # 查询服务
├── client/                 # Python SDK
│   └── aquery.py         # 客户端实现
├── tests/                  # 测试
├── Dockerfile             # 容器配置
├── requirements.txt       # Python依赖
└── README.md              # 本文档
```

## 技术栈

- **FastAPI**: 高性能Web框架
- **DuckDB**: 嵌入式OLAP查询引擎
- **Polars**: 极速数据处理
- **Hugging Face Datasets**: 数据存储

## 许可证

MIT License

## 联系方式

- 数据集: https://huggingface.co/datasets/superxu520/
- 问题反馈: 请提交GitHub Issue
