非价量数据服务
==========================

用途
----

提供宏观/经济指标(EDB)目录与指标数值查询接口,返回 JSON,适合数据平台,研究系统,策略脚本按需拉取并消费.

权限与访问方式
^^^^^^^^^^^^^^

- 本服务需购买专业版访问权限方可使用;如需购买,请前往 ``https://www.shinnytech.com/`` 用户中心购买.
- 获取专业版权限后,请访问 :doc:`token 服务 <token_server>` 获取 token,并在请求头携带 ``Authorization: Bearer <token>`` 调用接口.
- 可视化与 SDK:可直接访问 `https://edb.shinnytech.com/ <https://edb.shinnytech.com/>`_ 可视化使用,也可通过 tqsdk 量化接入(参考 `TqApi.query_edb_data <https://doc.shinnytech.com/tqsdk/latest/reference/tqsdk.api.html#tqsdk.TqApi.query_edb_data>`_).

典型使用场景
^^^^^^^^^^^^

- 数据平台集成:同步/检索指标目录,用于前端搜索,指标卡片展示与数据服务编排.
- 研究与因子开发:按指标与时间区间拉取序列数据,用于相关性分析,因子构建与回测输入.
- 报表与看板:定时拉取并落库,生成周报/月报或 BI 仪表盘.
- 大模型/智能体应用:让大模型按需检索指标并拉取区间数据,生成分析结论与 Python 脚本(建议提示词明确:指标关键词或 ID,起止日期).

基础信息
--------

- 协议:HTTPS
- 返回类型:``application/json; charset=utf-8``
- 地址示例:``https://edb.shinnytech.com/data/``
- 认证:所有业务接口均要求 JWT(``Authorization: Bearer <token>``)

统一响应格式
------------

所有业务接口返回统一结构:

成功:

.. code-block:: json

  {"error_code": 0, "error_msg": "", "data": {}}

失败(HTTP 200):

.. code-block:: json

  {"error_code": 1001, "error_msg": "错误描述", "data": {}}

接口:POST /index_table
-----------------------

查询指标目录.

请求体(JSON)
^^^^^^^^^^^^^

- ``ids`` (可选,数组):指定指标 ID 列表;可重复;不存在的 id 会被忽略.指标的 ID 可访问 ``https://edb.shinnytech.com/`` 查看.
- ``search`` (可选,字符串):关键词搜索(匹配 ``cn_name``,``table_name``).

处理规则(优先级)
^^^^^^^^^^^^^^^^^^

1. 若 ``ids`` 非空:按 ``ids`` 查询(去重后返回).
2. 若 ``ids`` 为空或未提供,且 ``search`` 非空:按关键词匹配.
3. 若两者均为空:返回全部目录.

返回字段
^^^^^^^^

``data`` 为数组,每项包含(类型为语义类型,JSON 传输层面不区分 int/float):

- ``id`` (int):指标 ID
- ``cn_name`` (string):指标中文名
- ``table_name`` (string):指标表名/展示名
- ``frequency`` (string):频率(如 日/周/月)
- ``unit`` (string):单位
- ``start_date`` (string):起始日期(``YYYY-MM-DD``)
- ``end_date`` (string):结束日期(``YYYY-MM-DD``)

空结果仍视为成功,``data=[]``.

返回示例
^^^^^^^^

.. code-block:: json

  {
    "error_code": 0,
    "error_msg": "",
    "data": [
      {
        "id": 1,
        "cn_name": "可用库容量:铜",
        "table_name": "可用库容量:铜",
        "frequency": "周",
        "unit": "吨",
        "start_date": "2010-01-01",
        "end_date": "2026-01-16"
      },
      {
        "id": 2,
        "cn_name": "可用库容量:白银",
        "table_name": "可用库容量:白银",
        "frequency": "周",
        "unit": "千克",
        "start_date": "2012-07-06",
        "end_date": "2026-01-16"
      }
    ]
  }

接口:POST /index_data
----------------------

按时间范围查询指标数值.

请求体(JSON)
^^^^^^^^^^^^^

- ``ids`` (必填,数组,长度 1-100):指标 ID 列表(去重后按请求顺序返回).
- ``start`` (可选,``YYYY-MM-DD``):起始日期,闭区间.
- ``end`` (可选,``YYYY-MM-DD``):结束日期,闭区间.

返回结构
^^^^^^^^

``data`` 包含:

- ``ids``:数组,列顺序(去重后保持请求顺序).
- ``values``:对象,键为日期(``YYYY-MM-DD``,降序),值为与 ``ids`` 对齐的数值数组;缺失值为 ``null``;数值为 JSON number(建议按 ``float`` 解析).

返回示例
^^^^^^^^

.. code-block:: json

  {
    "error_code": 0,
    "error_msg": "",
    "data": {
      "ids": [
        1,
        60,
        3
      ],
      "values": {
        "2025-12-05": [
          957664.000000,
          null,
          1007959.000000
        ],
        "2025-12-12": [
          956037.000000,
          null,
          1008703.000000
        ],
        "2025-12-19": [
          942861.000000,
          null,
          991716.000000
        ],
        "2025-12-26": [
          929953.000000,
          null,
          991958.000000
        ]
      }
    }
  }

注意事项
^^^^^^^^

- ``start`` 与 ``end`` 需满足 ``start <= end``.
- 若任一 ``id`` 不存在,返回错误.
- 时间范围内无数据时,``values`` 为 ``{}``,仍视为成功.

错误码
------

- 1001: ``ids`` 不能为空
- 1002: ``ids`` 数量超过限制(<=100)
- 1003: 包含不存在的指标 id
- 1004: ``start`` 必须小于等于 ``end``
- 1005: ``start/end`` 日期格式非法(``YYYY-MM-DD``)
- 1006: 数据库日期错误(非 ``YYYY-MM-DD``)

调用示例
--------

查询目录(关键词):

.. code-block:: python

  import requests

  token_resp = requests.post(
      "https://edb.shinnytech.com/token",
      json={"username": "shinny_user", "password": "pw123"},
      timeout=5,
  )
  token_resp.raise_for_status()
  token = token_resp.json()["token"]

  url = "https://edb.shinnytech.com/data/index_table"
  headers = {"Authorization": f"Bearer {token}"}
  payload = {"search": "库存"}

  resp = requests.post(url, headers=headers, json=payload, timeout=10)
  print(resp.json())

查询指标数值:

.. code-block:: python

  import requests

  token_resp = requests.post(
      "https://edb.shinnytech.com/token",
      json={"username": "shinny_user", "password": "pw123"},
      timeout=5,
  )
  token_resp.raise_for_status()
  token = token_resp.json()["token"]

  url = "https://edb.shinnytech.com/data/index_data"
  headers = {"Authorization": f"Bearer {token}"}
  payload = {"ids": [1, 2], "start": "2010-01-01", "end": "2010-12-31"}

  resp = requests.post(url, headers=headers, json=payload, timeout=10)
  print(resp.json())