国际货币汇率

查询货币对汇率，支持最新公布数据与指定历史日期。汇率方向为 1 单位源币对应的目标币金额；不是盘中实时行情。latest 接受当前 UTC 日期至前两日的公布数据，历史日期需精确匹配。支持范围随来源与日期变化，目标不存在或数据损坏返回 503，不补零。一小时缓存读取不延长有效期；不提供更旧备用结果。全量查询 dataTotalCount 仍为顶层对象数量 1，不是币种数量。

当前接口契约

接口详情：https://www.gugudata.com/api/details/currencyexchange

功能说明

指定源币种和目标币种，查询 EUR/CNY、USD/CNY 等货币对的汇率；

目标币种留空时，一次返回该源币种在公布日期支持的全部目标汇率；

默认查询来源最新公布的数据，并返回对应的日期标识；

指定历史日期查询，适合为历史订单和财务记录补充换算参考；

支持来源在指定日期提供的数字资产代码，如 BTC；实际可用性以当日数据为准；

兼容来源公布的特殊代码，如 $MYRO 和 BTC.B，可查询其已提供的历史汇率；

汇率表示 1 单位源币对应的目标币金额，便于明确换算方向；

返回公布日期的 UTC 零点毫秒时间戳，便于按日期保存汇率记录；

目标汇率以数组返回，每项包含源币种、目标币种、数值汇率和日期标识；

可为跨币种商品价格展示提供换算参考，展示时保留汇率日期；

可用于跨币种报表的数据整理，统一说明报表采用的币种和汇率日期；

支持同币种查询，可与其他货币对使用一致的返回结构；

请求参数

参数	类型	必填	默认值	说明
appkey	string	否	无	支持 appkey/appKey Query、X-GUGUDATA-APPKEY/X-API-Key Header 或 Bearer；多处提供须一致，同名参数不得重复。 AppKey 整体必填；在本操作已声明支持的鉴权位置任选一个提供，本位置无需重复填写。多处填写时须一致。
source	string	是	无	必填源币种代码，如 EUR、USD。忽略首尾空白并转大写，最多 20 个字符，允许字母、数字、$、.；是否支持以指定日期来源数据为准。
target	string	否	无	目标币种代码，如 CNY；不传或留空返回全部目标币种，代码规则与 source 相同。
date	string	否	latest	默认 latest，空字符串同 latest；或 YYYY-MM-DD，如 2024-03-06。历史可用性以来源实际提供为准，历史结果必须匹配请求日期。

正常响应字段

字段	类型	说明
dataStatus.requestParameter	string	真实可读的 source、target、date，不含凭据。
dataStatus.statusCode	integer	成功 200；参数错误 400；依赖失败 503。公共鉴权错误保持。
dataStatus.status	string	成功为 SUCCESS，错误为相应业务状态。
dataStatus.statusDescription	string	业务状态说明。
dataStatus.responseDateTime	string	接口响应时间，不是汇率公布时间。
dataStatus.dataTotalCount	integer	成功顶层对象数量为 1，含全量查询；不是目标币种数量。
data.sourceCurrency	string	归一化后的源币种代码。
data.targetCurrency	array	目标汇率数组，保持来源顺序。
data.targetCurrency[].sourceCurrency	string	源币种代码。
data.targetCurrency[].targetCurrency	string	目标币种代码。
data.targetCurrency[].exchangeRate	number	1 单位源币对应的目标币金额，有限正数；不代表交易成交价。
data.targetCurrency[].lastUpdateTimestamp	string	来源公布日期的 UTC 零点毫秒时间戳字符串，不是请求时间或盘中更新时间。
data.lastUpdateTimestamp	string	来源公布日期的 UTC 零点毫秒时间戳字符串，不是请求时间或盘中更新时间。

业务状态说明

业务状态码	业务状态码解释	备注
200	成功	SUCCESS
400	参数错误	PARAMETER_ERROR
402	凭据缺失或无效	APPKEY_NOT_SUPPLIED / APPKEY_NOT_EXISTED
403	订单过期或无权限	APPKEY_EXPIRED
429	请求频率超限	REQUEST_FREQUENCY_LIMIT
500	内部错误	FAILED
503	解析或鉴权服务暂时不可用	UPSTREAM_UNAVAILABLE / AUTH_SERVICE_UNAVAILABLE
505	调用包额度不可用	APPKEY_CALL_CREDITS_EXHAUSTED

请求示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

返回响应

🟢200成功

application/json

返回一个汇率对象，targetCurrency 为数组。

Bodyapplication/json

示例

{
  "dataStatus": {
    "requestParameter": "source=EUR&target=CNY&date=latest",
    "statusCode": 200,
    "status": "SUCCESS",
    "statusDescription": "successfully / 成功",
    "responseDateTime": "2026-10-10 17:28:49",
    "dataTotalCount": 1
  },
  "data": {
    "sourceCurrency": "EUR",
    "targetCurrency": [
      {
        "sourceCurrency": "EUR",
        "targetCurrency": "CNY",
        "exchangeRate": 7.52694217,
        "lastUpdateTimestamp": "1791504000000"
      }
    ],
    "lastUpdateTimestamp": "1791504000000"
  }
}

🟠400业务错误；结合六字段 dataStatus 判断。

🟠401业务错误；结合六字段 dataStatus 判断。

🟠403业务错误；结合六字段 dataStatus 判断。

🟠429业务错误；结合六字段 dataStatus 判断。

🔴500业务错误；结合六字段 dataStatus 判断。

🔴503业务错误；结合六字段 dataStatus 判断。

当前接口契约#

功能说明#

请求参数#

正常响应字段#

业务状态说明#

请求参数

请求示例代码

返回响应

当前接口契约

功能说明

请求参数

正常响应字段

业务状态说明