POSTPublicexchange-rate-history

Historical Exchange Rate API

Provides historical exchange rate data for specified currencies over a specific time period. Supports retrieval by month or custom date ranges.

Documentation

API Overview

The Historical Exchange Rate API allows developers to retrieve exchange rate fluctuations for specific currencies over a past period. By providing a currency code or name, along with a target month or custom start and end dates, the API returns detailed daily exchange rate data for that timeframe. This includes the TT (Telegraphic Transfer) buying/selling rates, cash buying/selling rates, and the BOC (Bank of China) conversion rate.

Use Cases

Financial Settlement & Auditing: Cross-border enterprises can verify historical exchange rates for specific dates during transaction settlements or financial audits.
Data Analysis & Trend Forecasting: Financial analysts and researchers can use historical forex data for market trend analysis and model building.
Cross-Border E-Commerce Platforms: Provide users with exchange rate references for historical orders or use the data for internal cost accounting.
Travel & Currency Exchange Services: Display historical exchange rate trends to help users formulate currency exchange strategies.

Request & Response Details

Request Parameter Highlights:

You must specify the target currency using either code (currency code, e.g., USD) or name (currency name, e.g., US Dollar). At least one is required.
You must specify the time range using either month (format: yyyyMM) or a combination of startDate and endDate (format: yyyyMMdd). Note: Month-based and date-range-based queries cannot both be empty.

Response Highlights:

The response includes a status code (code), a description message (msg), and a unique request ID (taskNo).
The core data is located in the data object, which contains the queried currency information and time range.
The list array contains daily exchange rate details for the specified period. Specific fields include:
publish_time: Publish date.
middle_rate: BOC conversion rate.
buying_rate: TT buying rate.
selling_rate: TT selling rate.
cash_buying_rate: Cash buying rate.
cash_selling_rate: Cash selling rate.

Integration Suggestions

It is highly recommended to use the currency code for queries to avoid failures caused by spelling variations in the currency name.
When building the request, ensure the time parameters are formatted correctly (yyyyMM or yyyyMMdd) and note the mutually exclusive logic between month-based and date-range-based queries.
For large-scale historical data queries, we recommend executing them during off-peak hours or caching the results locally to reduce API call frequency and improve response times.
Please ensure you handle non-200 status codes returned by the API and implement appropriate error prompts or retry logic based on the msg field.

Integration Examples

Includes ready-to-use Shell, Python, Go, Java, and PHP examples for direct integration.

Request Example

{
  "code": "货币编号，货币编号或货币名称必须输入其中一个",
  "name": "货币名称，货币编号或货币名称必须输入其中一个",
  "month": "查询年月（yyyyMM），month和startDate、endDate不能同时为空",
  "startDate": "查询起始时间yyyyMMdd，month和startDate、endDate不能同时为空",
  "endDate": "查询结束时间yyyyMMdd，month和startDate、endDate不能同时为空"
}

Response Example

{
  "msg": "成功",
  "code": 200,
  "taskNo": "687882815162227863699691",
  "data": {
    "currencyCode": "USD",
    "currencyName": "美元",
    "startDate": "20191001",
    "endDate": "20191101",
    "month": "201910",
    "list": [
      {
        "middle_rate": "705.33",
        "selling_rate": "705.55",
        "cash_buying_rate": "696.86",
        "buying_rate": "702.58",
        "cash_selling_rate": "705.55",
        "publish_time": "2019-10-31"
      },
      {
        "middle_rate": "705.82",
        "selling_rate": "707.26",
        "cash_buying_rate": "698.54",
        "buying_rate": "704.27",
        "cash_selling_rate": "707.26",
        "publish_time": "2019-10-30"
      }
    ]
  }
}

Request Fields

The fields below are derived from example JSON for integration reference only.

Path	Type	Sample
type	string	object
properties	object	{...}
properties.code	object	{...}
properties.code.type	string	string
properties.code.description	string	货币编号，货币编号或货币名称必须输入其中一个
properties.name	object	{...}
properties.name.type	string

Response Fields

The fields below are derived from example JSON for integration reference only.

Path	Type	Sample
type	string	object
properties	object	{...}
properties.msg	object	{...}
properties.msg.type	string	string
properties.msg.example	string	成功
properties.msg.description	string	code对应的描述
properties.code	object	{...}

curl --request POST \ --url 'https://openapi.toolkk.com/v1/exchange-rate-history' \ --header 'Content-Type: application/json' \ --header 'X-API-Key: YOUR_API_KEY' \ --data '{\n "code": "货币编号，货币编号或货币名称必须输入其中一个",\n "name": "货币名称，货币编号或货币名称必须输入其中一个",\n "month": "查询年月（yyyyMM），month和startDate、endDate不能同时为空",\n "startDate": "查询起始时间yyyyMMdd，month和startDate、endDate不能同时为空",\n "endDate": "查询结束时间yyyyMMdd，month和startDate、endDate不能同时为空"\n}'

import os import requests url = "https://openapi.toolkk.com/v1/exchange-rate-history" payload = { "code": "货币编号，货币编号或货币名称必须输入其中一个", "name": "货币名称，货币编号或货币名称必须输入其中一个", "month": "查询年月（yyyyMM），month和startDate、endDate不能同时为空", "startDate": "查询起始时间yyyyMMdd，month和startDate、endDate不能同时为空", "endDate": "查询结束时间yyyyMMdd，month和startDate、endDate不能同时为空" } headers = { "Content-Type": "application/json", "X-API-Key": os.getenv("TOOLKK_API_KEY", "YOUR_API_KEY"), } response = requests.request("POST", url, headers=headers, json=payload, timeout=30) response.raise_for_status() print(response.json())

package main import ( "bytes" "fmt" "io" "net/http" ) func main() { endpoint := "https://openapi.toolkk.com/v1/exchange-rate-history" payload := []byte("{\n \"code\": \"货币编号，货币编号或货币名称必须输入其中一个\",\n \"name\": \"货币名称，货币编号或货币名称必须输入其中一个\",\n \"month\": \"查询年月（yyyyMM），month和startDate、endDate不能同时为空\",\n \"startDate\": \"查询起始时间yyyyMMdd，month和startDate、endDate不能同时为空\",\n \"endDate\": \"查询结束时间yyyyMMdd，month和startDate、endDate不能同时为空\"\n}") req, err := http.NewRequest("POST", endpoint, bytes.NewBuffer(payload)) if err != nil { panic(err) } req.Header.Set("Content-Type", "application/json") req.Header.Set("X-API-Key", "YOUR_API_KEY") resp, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer resp.Body.Close() body, err := io.ReadAll(resp.Body) if err != nil { panic(err) } fmt.Println(string(body)) }

import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; public class ToolkkExample { public static void main(String[] args) throws Exception { String payload = "{\n \"code\": \"货币编号，货币编号或货币名称必须输入其中一个\",\n \"name\": \"货币名称，货币编号或货币名称必须输入其中一个\",\n \"month\": \"查询年月（yyyyMM），month和startDate、endDate不能同时为空\",\n \"startDate\": \"查询起始时间yyyyMMdd，month和startDate、endDate不能同时为空\",\n \"endDate\": \"查询结束时间yyyyMMdd，month和startDate、endDate不能同时为空\"\n}"; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://openapi.toolkk.com/v1/exchange-rate-history")) .method("POST", HttpRequest.BodyPublishers.ofString(payload)) .header("Content-Type", "application/json") .header("X-API-Key", "YOUR_API_KEY") .build(); HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body()); } }

<?php $endpoint = 'https://openapi.toolkk.com/v1/exchange-rate-history'; $payload = "{\n \"code\": \"货币编号，货币编号或货币名称必须输入其中一个\",\n \"name\": \"货币名称，货币编号或货币名称必须输入其中一个\",\n \"month\": \"查询年月（yyyyMM），month和startDate、endDate不能同时为空\",\n \"startDate\": \"查询起始时间yyyyMMdd，month和startDate、endDate不能同时为空\",\n \"endDate\": \"查询结束时间yyyyMMdd，month和startDate、endDate不能同时为空\"\n}"; $ch = curl_init($endpoint); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'Content-Type: application/json', 'X-API-Key: YOUR_API_KEY', ], CURLOPT_POSTFIELDS => $payload, ]); $response = curl_exec($ch); if ($response === false) { throw new RuntimeException(curl_error($ch)); } curl_close($ch); echo $response;

Historical Exchange Rate API

Documentation

API Overview

Use Cases

Request & Response Details

Integration Suggestions

Integration Examples

Request Example

Response Example

Request Fields

Response Fields

Shell Example

Python Example

Go Example

Java Example

PHP Example

Try it online