gf-api-client 0.1.3

广发证券开放平台 API 客户端

广发证券 API 客户端

这是一个用于访问广发证券开放平台 API 的 Python 客户端实现。

功能特点

• 支持自动分页获取数据
• 可以返回 DataFrame 或原始数据格式
• 实现了完整的 API 签名认证
• 提供了灵活的条件构建器
• 包含错误处理和请求重试机制

安装

pip install gf-api-client

使用示例

from gf_api_client import APIConfig, GFAPIClient, Condition

# API配置
config = APIConfig(
    key="your_key_here",
    app_id="your_app_id_here"
)

# 创建API客户端
client = GFAPIClient(config)

# 查询参数
secu_ids = ['000948.SH']
fields = ['cir_mval', 'pric_open']
endpoint = "/dsp/ds/service/news/news_idx_mkt_quot_gfzh_nc"
conditions = [
    Condition.in_list("secu_id", secu_ids),
    Condition.gt("trd_dt", '20240101')
]

# 执行查询
result = client.query(endpoint, conditions, fields, auto_paging=True, return_dataframe=True)
print(result)

条件构建器

提供了多种条件构建方法：

• eq: 等于
• lt: 小于
• gt: 大于
• le: 小于等于
• ge: 大于等于
• begin_with: 以...开始
• end_with: 以...结束
• contain: 包含
• in_list: 在列表中
• or_conditions: 或条件

条件构建器使用示例

Condition 类提供了多种条件构建方法，以下是每个方法的详细示例：

1. 等于条件 (eq)

# 查询股票代码等于 000001.SZ 的数据
condition = Condition.eq("secu_id", "000001.SZ")
# 结果: "eq,secu_id,'000001.SZ'"

2. 小于条件 (lt)

# 查询价格小于 10 的数据
condition = Condition.lt("price", 10)
# 结果: "lt,price,10"

3. 大于条件 (gt)

# 查询日期大于 2024-01-01 的数据
condition = Condition.gt("trd_dt", "20240101")
# 结果: "gt,trd_dt,'20240101'"

4. 小于等于条件 (le)

# 查询成交量小于等于 1000000 的数据
condition = Condition.le("volume", 1000000)
# 结果: "le,volume,1000000"

5. 大于等于条件 (ge)

# 查询市值大于等于 1000000000 的数据
condition = Condition.ge("market_value", 1000000000)
# 结果: "ge,market_value,1000000000"

6. 以...开始条件 (begin_with)

# 查询以 "沪" 开头的股票名称
condition = Condition.begin_with("stock_name", "沪")
# 结果: "beginWith,stock_name,'沪'"

7. 以...结束条件 (end_with)

# 查询以 "银行" 结尾的股票名称
condition = Condition.end_with("stock_name", "银行")
# 结果: "endWith,stock_name,'银行'"

8. 包含条件 (contain)

# 查询名称中包含 "科技" 的股票
condition = Condition.contain("stock_name", "科技")
# 结果: "contain,stock_name,'科技'"

9. 在列表中条件 (in_list)

# 查询多个股票代码的数据
secu_ids = ["000001.SZ", "000002.SZ", "000003.SZ"]
condition = Condition.in_list("secu_id", secu_ids)
# 结果: "in,secu_id,'000001.SZ;000002.SZ;000003.SZ'"

10. 或条件 (or_conditions)

# 查询沪深300或上证50的股票
condition1 = Condition.eq("index_code", "000300.SH")  # 沪深300
condition2 = Condition.eq("index_code", "000016.SH")  # 上证50
condition = Condition.or_conditions(condition1, condition2)
# 结果: "or,eq#index_code#'000300.SH',eq#index_code#'000016.SH'"

组合条件示例

# 组合多个条件：查询 2024年1月1日 之后的 沪深300 成分股的数据
conditions = [
    Condition.gt("trd_dt", "20240101"),
    Condition.eq("index_code", "000300.SH")
]

result = client.query(
    endpoint="/your/endpoint",
    conditions=conditions,
    fields=["secu_id", "stock_name", "close_price"]
)

注意事项

• 条件值如果是字符串类型，会自动添加单引号
• 数值类型（整数、浮点数）不会添加引号
• 日期格式推荐使用 "YYYYMMDD" 格式
• 多个条件可以组合使用，形成一个条件列表
• 使用 or_conditions 时，内部的逗号会被替换为 '#' 符号

依赖要求

• Python >= 3.6
• requests >= 2.31.0
• pandas >= 2.0.0