shield_lock
JinDaGe
← Back to skills
extension
Category: Data & AnalyticsAPI key required

连为全球贸易数据

经 Conforx OpenAPI 查询国际贸易年度、伙伴与增长数据。支持一次性获取多年份、进出口全量数据，避免重复查询。

personAuthor: user_d3a7b408hubcommunity
downloadDownload package

🌍 Global Trade Data Lookup Skill

本 Skill 用于通过 Conforx OpenAPI 精确查询国际贸易统计数据。它具备智能参数构建能力，能根据用户意图决定是进行精确查询还是一次性获取更广泛的数据（如多年份、进出口全量），非常适合分析进出口趋势、贸易伙伴等场景。

Base URL: http://114.80.39.94:18080/cbscap-boot

Authentication & Setup

业务查询前必须完成鉴权。临时密钥体系如下：

  1. 检查是否已有临时 Key
    • Endpoint: GET /openapi/v1/currentTempKey
    • 说明: 本机回环地址（127.0.0.1 / ::1）无法查询。
  2. 如无 Key 或不存在，则申请
    • Endpoint: POST /openapi/v1/applyTempKey
    • Body: {"clientName": "Skill-User", "applyReason": "trade_data_analysis"}
    • 从响应 result.apiKey 取出 sk-...
  3. 后续请求统一携带 Header
    • Authorization: Bearer <apiKey>

临时 Key 规则: 同一 IP 同时仅 1 个生效；每天限申 1 次；最多调用 10 次后失效。

Core Capabilities & Workflows

1. Annual Trade Data (By Country)

用于查询某国在特定年份或所有可用年份的进出口总额。

  • Endpoint: GET /openapi/v1/trade/annual/by-country
  • Parameters:
    • reporterIso (必填): 报告国 ISO2，如 CN、US、TH（支持逗号多值 CN,TH）。
    • flowCode (必填): X=出口，M=进口。
    • year (可选): >= 2020。
      • 策略: 如果用户询问趋势（如“过去几年”、“历年”）或未指定年份，请勿传递此参数，API 将返回该国自 2020 年以来的所有可用数据。
  • 示例问句:
    • "中国 2023 年出口总额是多少？" -> reporterIso=CN, flowCode=X, year=2023
    • "泰国历年的进口数据" -> reporterIso=TH, flowCode=M (省略 year)

2. Annual Trade Data (By Year)

用于查询某一年全部报告国的贸易总额，或查询某国所有年份的进出口数据。

  • Endpoint: GET /openapi/v1/trade/annual/by-year
  • Parameters:
    • year (可选): >= 2020。
      • 策略: 如果用户未指定年份，请勿传递此参数，API 将返回所有年份的数据。
    • flowCode (可选): X / M。
      • 策略: 如果用户想同时看进出口，请勿传递此参数，API 将同时返回出口与进口数据。
  • 示例问句:
    • "2023 年全球贸易情况" -> year=2023 (省略 flowCode)
    • "美国历年的进出口总额" -> reporterIso=US (此接口可能不适用，应优先使用 by-country 并省略 year)

3. Trade Partners Analysis

用于分析某国主要贸易伙伴。

  • Endpoint: GET /openapi/v1/trade/partner/by-country
  • Parameters:
    • reporterIso (必填): 报告国 ISO2。
    • flowCode (必填): X（出口到谁）/ M（从谁进口）。
    • partnerIso (可选): 伙伴国 ISO2。
    • year (可选): >= 2020。
      • 策略: 如果用户未指定年份，请勿传递此参数，以获取最新的或 aggregated 的伙伴数据。
  • 示例问句:
    • "美国主要进口来源国有哪些？" -> reporterIso=US, flowCode=M (省略 year)

4. Trade Growth Trends

用于分析贸易同比增长率。

  • Endpoint: GET /openapi/v1/trade/annual-growth/by-country
  • Parameters:
    • reporterIso (必填): ISO2。
    • flowCode (必填): X / M。
    • year (可选): >= 2020。
      • 策略: 如果用户询问“增长趋势”，请勿传递此参数，API 将返回多年的增长率数据以便分析趋势。
  • 示例问句:
    • "德国出口增长率如何？" -> reporterIso=DE, flowCode=X (省略 year)

🧠 Smart Query Strategy (智能查询策略)

为了减少 API 调用次数（限额 10 次）并提供更全面的视角，请遵循以下策略：

  1. 年份模糊时，不传 year:
    • 当用户问“历年数据”、“过去几年”、“趋势如何”或未提及具体年份时，务必省略 year 参数。
    • 好处: 一次性获取 2020 年至今的所有数据，便于 AI 自行总结趋势，无需多次追问或查询。
  2. 进出口未分时，不传 flowCode (仅限支持的接口):
    • 当用户问“贸易总额”且未区分进出口，或明确说“进出口数据都要”时，在 by-year 接口中省略 flowCode。
    • 好处: 一次调用同时拿到 Import 和 Export 数据。
  3. 优先使用 by-country 接口获取时间序列:
    • 如果用户关注某个国家的随时间变化的数据，优先使用 annual/by-country 并省略 year，而不是循环调用 by-year。

Data Interpretation

Country codes (必须 ISO2)

国家名必须转换为 ISO 3166-1 alpha-2 两位代码，禁止使用三字码（如 CHN、USA）。

| 国家/地区 | ISO2 | 错误示例 | | :--- | :--- | :--- | | 中国 | CN | CHN | | 美国 | US | USA | | 泰国 | TH | THA | | 德国 | DE | DEU | | 日本 | JP | JPN | | 韩国 | KR | KOR | | 越南 | VN | VNM | | 新加坡 | SG | SGP | | 马来西亚 | MY | MYS | | 印度尼西亚 | ID | IDN | | 印度 | IN | IND | | 英国 | GB | GBR |

Year

  • 最新数据: 指 2025年 的数据。
  • 全部数据: 指 2020年 - 2025年 的数据范围。
  • 仅支持 2020 年及以后 (year >= 2020)。
  • 传入 2019 及更早会返回参数错误。
  • 核心策略: 除非用户明确指定查询某一年（如“2023年”），否则一律不传递 year 参数，以查询全部年份（2020-2025）的数据。

Flow codes

  • X: Export (报告国出口)
  • M: Import (报告国进口)

Values

  • primaryValue: 贸易额
  • growthRate: 同比增长率
  • 响应统一信封: { success, code, message, result }；贸易接口 result 含分页 records/total/size/current

Constraints

  • 临时 Key 限额 10 次；达限后提示用户 Key 已失效，可申请正式 Key。
  • 不能在 127.0.0.1 上申请/查询临时 Key。
  • 可下载规范: GET /openapi/v1/openapi.json 或 openapi.yaml。
  • 脚本辅助: scripts/fetch_trade_demo.py、scripts/apply_temp_key.sh。
  • 更多细节见 references/workflows.md、references/error-codes.md、assets/config.json。