開発ユーティリティAPI

Distance

2地点間の距離を計算します。

MCPツール名: calculate_distance

GET /v1/distance

パラメータ:

パラメータ	型	必須	説明
p1	string	✓	地点1の緯度,経度（例: 35.681236,139.767125）
p2	string	✓	地点2の緯度,経度（例: 34.702485,135.495951）

リクエスト例:

curl "https://api.thousand-api.com/v1/distance?p1=35.681236,139.767125&p2=34.702485,135.495951" \
  -H "x-api-key: YOUR_API_KEY"

レスポンス例:

{
  "p1": { "lat": 35.681236, "lon": 139.767125 },
  "p2": { "lat": 34.702485, "lon": 135.495951 },
  "distance_km": 402.3
}

座標系変換

WGS84（GPS）・東京測地系（旧日本測地系）・JGD2011（測地成果2011）間の座標変換、および国土地理院タイル座標（XYZ）への変換を行います。外部ライブラリ不要・Molodensky近似パラメータを使用します。

MCPツール名: utility.convert_coordinates

WGS84はGPS端末の標準座標系です。東京測地系（tokyo）は国土地理院の旧地図や行政システムで使われていた座標系で、WGS84と最大約450mずれます。JGD2011（jgd2011）は測地成果2011で、WGS84と実用上ほぼ同一ですが、API上は別座標系として指定できます。タイル変換（to=tile）時は内部でWGS84に統一してからWebメルカトル投影のXYZタイル座標を計算します。

GET /v1/geo/convert

パラメータ:

パラメータ	型	必須	説明
lat	number	✓	緯度（-90〜90）
lng	number	✓	経度（-180〜180）
from	string	✓	変換元座標系: wgs84 / tokyo / jgd2011
to	string	✓	変換先座標系: wgs84 / tokyo / jgd2011 / tile
zoom	integer	-	to=tile のとき必須。ズームレベル（0〜25の整数）

レスポンスフィールド:

座標変換時（to が wgs84 / tokyo / jgd2011）の output

パラメータ	説明
lat	変換後の緯度（小数第8位まで）
lng	変換後の経度（小数第8位まで）

タイル変換時（to が tile）の output

パラメータ	説明
zoom	リクエストで指定したズームレベル
x	タイルのX座標（経度方向・0始まり）
y	タイルのY座標（緯度方向・北が小さい値）

リクエスト例:

例1: WGS84 → 東京測地系（GPSデータを旧日本測地系に変換）

curl "https://api.thousand-api.com/v1/geo/convert?lat=35.6812&lng=139.7671&from=wgs84&to=tokyo" \
  -H "x-api-key: YOUR_API_KEY"

{
  "from": "wgs84",
  "to": "tokyo",
  "input": { "lat": 35.6812, "lng": 139.7671 },
  "output": { "lat": 35.68109304, "lng": 139.76727453 }
}

例2: 東京測地系 → WGS84（旧システムのデータをGPS座標に変換）

curl "https://api.thousand-api.com/v1/geo/convert?lat=35.68109304&lng=139.76727453&from=tokyo&to=wgs84" \
  -H "x-api-key: YOUR_API_KEY"

{
  "from": "tokyo",
  "to": "wgs84",
  "input": { "lat": 35.68109304, "lng": 139.76727453 },
  "output": { "lat": 35.6812, "lng": 139.7671 }
}

例3: WGS84 → タイル座標（zoom=15・国土地理院タイル）

curl "https://api.thousand-api.com/v1/geo/convert?lat=35.6812&lng=139.7671&from=wgs84&to=tile&zoom=15" \
  -H "x-api-key: YOUR_API_KEY"

{
  "from": "wgs84",
  "to": "tile",
  "input": { "lat": 35.6812, "lng": 139.7671 },
  "output": { "zoom": 15, "x": 29105, "y": 12903 }
}

カラーパレット生成

基準カラーコードから補色・類似色などのカラーパレットを生成します。外部依存なし・HSL色空間で数学的に正確な計算を行います。

MCPツール名: utility.generate_color_palette

GET /v1/color/palette

パラメータ:

パラメータ	型	必須	説明
color	string	✓	基準カラーコード（#RRGGBB形式）
type	string	-	complementary / analogous / triadic / tetradic / shades

リクエスト例:

curl "https://api.thousand-api.com/v1/color/palette?color=%231976D2&type=complementary" \
  -H "x-api-key: YOUR_API_KEY"

レスポンス例:

{
  "base": "#1976D2",
  "type": "complementary",
  "palette": [
    {
      "hex": "#1976D2",
      "rgb": "rgb(25, 118, 210)",
      "hsl": "hsl(211, 79%, 46%)",
      "name": "base"
    },
    {
      "hex": "#D27619",
      "rgb": "rgb(210, 118, 25)",
      "hsl": "hsl(31, 79%, 46%)",
      "name": "complement"
    }
  ]
}

色空間変換

HEX・RGB・HSL・HSV・CMYK間の色空間変換を行います。すべての変換はRGBを中継点として一貫した結果を返します。外部依存なし・純粋な変換式のみを使用します。

MCPツール名: convert.color

変換結果の hex を utility.calc_color_contrast の foreground / background に渡すことで、HSLやCMYKから得た色のアクセシビリティをすぐに検証できます。utility.generate_color_palette と組み合わせれば、配色生成→形式変換→コントラスト検証の一連のワークフローを構築できます。

GET /v1/color/convert

パラメータ:

パラメータ	型	必須	説明
color	string	✓	変換元の色。from に応じた形式で指定
from	string	✓	変換元フォーマット: hex / rgb / hsl / hsv / cmyk
color (hex)	string	-	#1976D2 / 1976D2 / #FFF / FFF（3桁短縮可）
color (rgb)	string	-	25,118,210 / 25, 118, 210 / rgb(25, 118, 210) / {"r":25,"g":118,"b":210}
color (hsl)	string	-	210,79,46 / 210, 79, 46 / hsl(210, 79%, 46%)
color (hsv)	string	-	210,88,82 / 210, 88, 82
color (cmyk)	string	-	88,44,0,18 / 88, 44, 0, 18

レスポンスフィールド:

パラメータ	説明
input.format	入力フォーマット（hex / rgb / hsl / hsv / cmyk）
input.value	入力された色文字列（そのまま返却）
hex	正規化済みHEX（大文字 #RRGGBB）
rgb.r / g / b	RGB各成分（0〜255）
hsl.h	色相（0〜360）
hsl.s / l	彩度・明度（0〜100）
hsv.h	色相（0〜360）
hsv.s / v	彩度・輝度（0〜100）
cmyk.c / m / y / k	各インク成分（0〜100）

リクエスト例:

例1: HEXから全フォーマットへ変換（#1976D2）

curl "https://api.thousand-api.com/v1/color/convert?color=%231976D2&from=hex" \
  -H "x-api-key: YOUR_API_KEY"

レスポンス例:

{
  "input": { "format": "hex", "value": "#1976D2" },
  "hex": "#1976D2",
  "rgb": { "r": 25, "g": 118, "b": 210 },
  "hsl": { "h": 210, "s": 79, "l": 46 },
  "hsv": { "h": 210, "s": 88, "v": 82 },
  "cmyk": { "c": 88, "m": 44, "y": 0, "k": 18 }
}

例2: HSLからRGB・HEXへ変換（CSS変数からの変換）

curl "https://api.thousand-api.com/v1/color/convert?color=hsl(210%2C%2079%25%2C%2046%25)&from=hsl" \
  -H "x-api-key: YOUR_API_KEY"

{
  "input": { "format": "hsl", "value": "hsl(210, 79%, 46%)" },
  "hex": "#1975D2",
  "rgb": { "r": 25, "g": 117, "b": 210 },
  "hsl": { "h": 210, "s": 79, "l": 46 },
  "hsv": { "h": 210, "s": 88, "v": 82 },
  "cmyk": { "c": 88, "m": 44, "y": 0, "k": 18 }
}

例3: CMYKからWebカラーへ変換（印刷データ）

curl "https://api.thousand-api.com/v1/color/convert?color=88%2C44%2C0%2C18&from=cmyk" \
  -H "x-api-key: YOUR_API_KEY"

{
  "input": { "format": "cmyk", "value": "88,44,0,18" },
  "hex": "#1975D1",
  "rgb": { "r": 25, "g": 117, "b": 209 },
  "hsl": { "h": 210, "s": 79, "l": 46 },
  "hsv": { "h": 210, "s": 88, "v": 82 },
  "cmyk": { "c": 88, "m": 44, "y": 0, "k": 18 }
}

WCAGコントラスト比

前景色と背景色のWCAG 2.1コントラスト比を計算し、AA/AAAの適合判定と推奨メッセージを返します。外部依存なし・公式の相対輝度アルゴリズムを使用します。

MCPツール名: utility.calc_color_contrast

WCAG 2.1 基準: AA 通常テキスト 4.5:1、AA 大テキスト・UI 3:1、AAA 通常テキスト 7:1、AAA 大テキスト 4.5:1。大テキストは 18pt 以上、または 14pt 以上の太字を指します。

utility.generate_color_palette で得た palette 内の各 hex を foreground / background の組み合わせで本APIに渡すと、アクセシブルな配色候補だけをエージェント側でフィルタできます。

GET /v1/color/contrast

パラメータ:

パラメータ	型	必須	説明
foreground	string	✓	前景色HEX（#RRGGBB、RRGGBB、3桁短縮可）
background	string	✓	背景色HEX（#RRGGBB、RRGGBB、3桁短縮可）

リクエスト例:

curl "https://api.thousand-api.com/v1/color/contrast?foreground=%23FFFFFF&background=%231976D2" \
  -H "x-api-key: YOUR_API_KEY"

レスポンス例:

例1: 十分なコントラスト（#FFFFFF / #1976D2）

{
  "foreground": "#FFFFFF",
  "background": "#1976D2",
  "contrast_ratio": 4.6,
  "wcag_aa_normal": true,
  "wcag_aa_large": true,
  "wcag_aaa_normal": false,
  "wcag_aaa_large": true,
  "recommendation": "AA normal + AAA large: good for most use cases (ratio: 4.6:1)"
}

例2: コントラスト不足（Fail判定）

{
  "foreground": "#777777",
  "background": "#888888",
  "contrast_ratio": 1.26,
  "wcag_aa_normal": false,
  "wcag_aa_large": false,
  "wcag_aaa_normal": false,
  "wcag_aaa_large": false,
  "recommendation": "Fail: insufficient contrast for any WCAG level (ratio: 1.26:1)"
}

レスポンスフィールド:

パラメータ	説明
foreground	正規化済み前景色（大文字 #RRGGBB）
background	正規化済み背景色（大文字 #RRGGBB）
contrast_ratio	WCAGコントラスト比（小数第2位まで）
wcag_aa_normal	AA 通常テキスト適合（4.5:1 以上）
wcag_aa_large	AA 大テキスト・UI適合（3:1 以上）
wcag_aaa_normal	AAA 通常テキスト適合（7:1 以上）
wcag_aaa_large	AAA 大テキスト適合（4.5:1 以上）
recommendation	最高適合レベルの説明文（英語）

数式評価

数式・計算式を安全に評価します。四則演算・三角関数・統計・単位変換・変数バインディングに対応。JavaScript の eval は使用せず、mathjs のサンドボックス実行で危険な関数（import・parse 等）を無効化しています。100ms のタイムアウトで過大な計算も遮断します。

MCPツール名: utility.calc_expression

POST /v1/math/eval

パラメータ:

パラメータ	型	必須	説明
expression	string	必須	評価する数式文字列（最大500文字）
variables	object	-	変数バインディング（値は number / string / boolean）
precision	integer	-	小数点以下の桁数（0〜15、省略時は制限なし）

レスポンスフィールド:

パラメータ	説明
expression	入力した数式をそのまま返す
variables	使用した変数（未指定時は null）
result	評価結果（number / string / boolean）
result_str	result を文字列化したもの
precision	使用した precision（未指定時は null）

税込計算の例:

リクエスト例:

curl -X POST "https://api.thousand-api.com/v1/math/eval" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expression": "(100000 + 50000) * 1.1"
  }'

レスポンス例:

{
  "expression": "(100000 + 50000) * 1.1",
  "variables": null,
  "result": 165000,
  "result_str": "165000",
  "precision": null
}

変数バインディングを使った複利計算の例:

リクエスト例:

curl -X POST "https://api.thousand-api.com/v1/math/eval" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expression": "principal * (1 + rate)^years",
    "variables": {
      "principal": 1000000,
      "rate": 0.05,
      "years": 10
    },
    "precision": 0
  }'

レスポンス例:

{
  "expression": "principal * (1 + rate)^years",
  "variables": {
    "principal": 1000000,
    "rate": 0.05,
    "years": 10
  },
  "result": 1628895,
  "result_str": "1628895",
  "precision": 0
}

数学関数（ピタゴラスの定理）の例:

リクエスト例:

curl -X POST "https://api.thousand-api.com/v1/math/eval" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expression": "sqrt(x^2 + y^2)",
    "variables": {
      "x": 3,
      "y": 4
    }
  }'

レスポンス例:

{
  "expression": "sqrt(x^2 + y^2)",
  "variables": {
    "x": 3,
    "y": 4
  },
  "result": 5,
  "result_str": "5",
  "precision": null
}

消費税計算

日本の消費税（標準10%・軽減8%、または任意の税率）を計算します。税抜→税込・税込→税抜の双方向変換、端数処理（切り捨て/切り上げ/四捨五入）の選択、複数品目の合算に対応。整数（円単位）演算で浮動小数点誤差を回避します。

MCPツール名: utility.calc_tax

POST /v1/math/tax

パラメータ:

パラメータ	型	必須	説明
amount	number	-	単一計算用の金額（items と排他、いずれか必須）
rate	number	-	税率 %（デフォルト: 10、0〜100）
rounding	string	-	端数処理: floor / ceil / round（デフォルト: floor）
direction	string	-	exclusive_to_inclusive（税抜→税込・デフォルト）/ inclusive_to_exclusive（税込→税抜）
items	array	-	複数品目。指定時は amount/rate（トップレベル）は無視。各 item.rate 省略時はトップレベル rate（さらに省略時 10）

レスポンスフィールド:

パラメータ	説明
direction	変換方向
net	税抜金額（単一計算時）
tax	消費税額（単一計算時）
gross	税込金額（単一計算時）
rate	適用税率（単一計算時）
items	品目ごとの net / tax / gross / rate（複数品目時）
total_net	税抜合計（複数品目時）
total_tax	消費税合計（複数品目時）
total_gross	税込合計（複数品目時）
rounding	使用した端数処理モード

単一計算（税抜→税込）:

リクエスト例:

curl -X POST "https://api.thousand-api.com/v1/math/tax" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "rate": 10,
    "rounding": "floor"
  }'

レスポンス例:

{
  "direction": "exclusive_to_inclusive",
  "net": 1000,
  "tax": 100,
  "gross": 1100,
  "rate": 10,
  "rounding": "floor"
}

複数品目合算（標準10% + 軽減8%）:

リクエスト例:

curl -X POST "https://api.thousand-api.com/v1/math/tax" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "amount": 1000, "rate": 10 },
      { "amount": 500, "rate": 8 }
    ],
    "rounding": "floor"
  }'

レスポンス例:

{
  "direction": "exclusive_to_inclusive",
  "items": [
    { "net": 1000, "tax": 100, "gross": 1100, "rate": 10 },
    { "net": 500, "tax": 40, "gross": 540, "rate": 8 }
  ],
  "total_net": 1500,
  "total_tax": 140,
  "total_gross": 1640,
  "rounding": "floor"
}

税込→税抜の逆算:

リクエスト例:

curl -X POST "https://api.thousand-api.com/v1/math/tax" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1100,
    "rate": 10,
    "rounding": "floor",
    "direction": "inclusive_to_exclusive"
  }'

レスポンス例:

{
  "direction": "inclusive_to_exclusive",
  "net": 1000,
  "tax": 100,
  "gross": 1100,
  "rate": 10,
  "rounding": "floor"
}

ローン・金利計算

ローンの元利均等返済・元金均等返済の月次支払額・総支払額・総利息を計算します。複利と円単位の端数処理は LLM の暗算で誤りやすい領域のため、毎月 Math.round で確定し、最終月で残債務を強制清算して返済計画表の合計が借入金額と一致するようにしています。

MCPツール名: utility.calc_loan

POST /v1/math/loan

パラメータ:

パラメータ	型	必須	説明
principal	number	必須	借入金額（円、正の数）
annual_rate	number	必須	年利（%）。例: 3.5 = 年利 3.5%（0.035 ではない）
term_months	integer	必須	返済期間（月）。1〜600（50年）
method	string	-	equal_payment（元利均等・デフォルト）/ equal_principal（元金均等）
include_schedule	boolean	-	true のとき返済計画表（schedule）を返す（デフォルト: false）

レスポンスフィールド:

パラメータ	説明
method	適用した返済方式
monthly_payment	月次支払額（equal_payment）。equal_principal の場合は null（月ごとに変動）
total_payment	総支払額（円）
total_interest	総利息（total_payment − principal）
schedule	返済計画表（include_schedule: true のときのみ）。各要素: month / payment / principal / interest / balance

元利均等返済（equal_payment）— 月々の支払額固定:

リクエスト例:

curl -X POST "https://api.thousand-api.com/v1/math/loan" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "principal": 1000000,
    "annual_rate": 3,
    "term_months": 12,
    "method": "equal_payment"
  }'

レスポンス例:

{
  "method": "equal_payment",
  "monthly_payment": 84694,
  "total_payment": 1016325,
  "total_interest": 16325
}

元金均等返済（equal_principal）— 同じ条件で総支払額を比較:

リクエスト例:

curl -X POST "https://api.thousand-api.com/v1/math/loan" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "principal": 1200000,
    "annual_rate": 3,
    "term_months": 12,
    "method": "equal_principal"
  }'

レスポンス例:

{
  "method": "equal_principal",
  "monthly_payment": null,
  "total_payment": 1219500,
  "total_interest": 19500
}

返済計画表（include_schedule: true）:

リクエスト例:

curl -X POST "https://api.thousand-api.com/v1/math/loan" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "principal": 1000000,
    "annual_rate": 3,
    "term_months": 12,
    "method": "equal_payment",
    "include_schedule": true
  }'

レスポンス例:

{
  "method": "equal_payment",
  "monthly_payment": 84694,
  "total_payment": 1016325,
  "total_interest": 16325,
  "schedule": [
    { "month": 1, "payment": 84694, "principal": 82194, "interest": 2500, "balance": 917806 },
    { "month": 12, "payment": 84691, "principal": 84480, "interest": 211, "balance": 0 }
  ]
}

ページネーション計算

総件数・現在ページ・1ページあたり件数から、ページネーションに必要な値を一括計算します。offset / limit（SQL や API クエリにそのまま使える 0 始まり）と from / to（UI 表示用の 1 始まり）、has_prev / has_next、prev_page / next_page、page_range（ページ番号リスト）を返します。

MCPツール名: utility.calc_pagination（引数 page は current_page）

GET /v1/pagination/calc

パラメータ:

パラメータ	型	必須	説明
total_items	integer	必須	全件数（0 以上）
page	integer	必須	現在のページ番号（1 始まり）
per_page	integer	-	1ページあたりの件数（デフォルト: 20、最大: 1000）
window_size	integer	-	page_range に含めるページ数（デフォルト: 5、最大: 20）

レスポンスフィールド:

パラメータ	説明
total_items	入力した全件数
page	現在のページ番号（1 始まり）
per_page	1ページあたりの件数
total_pages	総ページ数（total_items=0 のとき 0）
offset	先頭からのオフセット（0 始まり。SQL OFFSET に相当）
limit	取得件数（per_page と同値。SQL LIMIT に相当）
from	表示開始アイテム番号（1 始まり）
to	表示終了アイテム番号（1 始まり。最終ページは total_items と一致）
has_prev	前ページが存在するか
has_next	次ページが存在するか
prev_page	前ページ番号（has_prev: false のとき null）
next_page	次ページ番号（has_next: false のとき null）
page_range	UI に表示するページ番号の配列

基本（total_items=234, page=3）:

リクエスト例:

curl "https://api.thousand-api.com/v1/pagination/calc?total_items=234&page=3" \
  -H "x-api-key: YOUR_API_KEY"

レスポンス例:

{
  "total_items": 234,
  "page": 3,
  "per_page": 20,
  "total_pages": 12,
  "offset": 40,
  "limit": 20,
  "from": 41,
  "to": 60,
  "has_prev": true,
  "has_next": true,
  "prev_page": 2,
  "next_page": 4,
  "page_range": [1, 2, 3, 4, 5]
}

最終ページ（page=12, has_next: false）:

リクエスト例:

curl "https://api.thousand-api.com/v1/pagination/calc?total_items=234&page=12" \
  -H "x-api-key: YOUR_API_KEY"

レスポンス例:

{
  "total_items": 234,
  "page": 12,
  "per_page": 20,
  "total_pages": 12,
  "offset": 220,
  "limit": 20,
  "from": 221,
  "to": 234,
  "has_prev": true,
  "has_next": false,
  "prev_page": 11,
  "next_page": null,
  "page_range": [8, 9, 10, 11, 12]
}

Semverバージョン比較

セマンティックバージョン（semver）の比較・ソート・レンジ判定を行います。1.10.0 > 1.9.0 のように文字列比較では誤るケースを正しく処理します。prerelease版や ^1.0.0 などのレンジ指定にも対応。

MCPツール名: utility.compare_versions

POST /v1/version/compare

パラメータ:

パラメータ	型	必須	説明
versions	string[]	-	ソート・latest取得対象のバージョン一覧（最大100件）
compare	string	-	比較元バージョン（against とセットで指定）
against	string	-	比較先バージョン（compare とセットで指定）
include_prerelease	boolean	-	sorted/latest に prerelease を含めるか（デフォルト: false）
satisfies	object	-	レンジパターンとチェック対象バージョンのマップ（キー=range、値=version）

レスポンスフィールド:

パラメータ	型	説明
compare	string	リクエストの compare（指定時のみ）
against	string	リクエストの against（指定時のみ）
result	number	比較結果: 1=compareが新しい / 0=同じ / -1=compareが古い（指定時のみ）
result_label	string	result の文字列表現: greater / equal / less（指定時のみ）
sorted	string[]	versions を昇順ソートした結果（versions 指定時のみ）
latest_stable	string \| null	最も新しい安定版（versions 指定時のみ）
satisfies	object	各 range を満たすかの判定結果（satisfies 指定時のみ）

2バージョンの大小比較:

リクエスト例:

curl -X POST "https://api.thousand-api.com/v1/version/compare" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "compare": "1.10.0",
    "against": "1.9.0"
  }'

レスポンス例:

{
  "compare": "1.10.0",
  "against": "1.9.0",
  "result": 1,
  "result_label": "greater"
}

ソート・比較・レンジ判定の複合例:

リクエスト例:

curl -X POST "https://api.thousand-api.com/v1/version/compare" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "versions": ["1.9.0", "1.10.0", "2.0.0-beta.1", "2.0.0"],
    "compare": "2.0.0",
    "against": "1.10.0",
    "include_prerelease": false,
    "satisfies": {
      "^1.9.0": "1.10.0",
      ">=2.0.0": "2.0.0-beta.1"
    }
  }'

レスポンス例:

{
  "compare": "2.0.0",
  "against": "1.10.0",
  "result": 1,
  "result_label": "greater",
  "sorted": ["1.9.0", "1.10.0", "2.0.0"],
  "latest_stable": "2.0.0",
  "satisfies": {
    "^1.9.0": true,
    ">=2.0.0": false
  }
}

複合バッチ実行

複数の API を 1 リクエストで順次実行します。MCP でツールを個別に連続呼び出しする前に data.execute_batch を検討してください。tools:[{id,tool,args}] 形式で MCP ツール名を指定でき、前ステップの結果を {{stepId.field}} 形式で後続ステップに渡せます。

MCPツール名: data.execute_batch

MCP 向けプリセット（data.execute_batch にそのまま渡す）

tool-catalog リソース（thousand-api://catalog/tools）の execute_batch_presets にも同じ JSON が含まれます。

今日の日付 → 祝日判定 → 為替レート

現在日時を取得し、その日が祝日かを判定したうえで USD/JPY レートを取得する定番チェーン。

{
  "tools": [
    {
      "id": "now",
      "tool": "datetime.get_current_datetime",
      "args": {
        "timezone": "Asia/Tokyo"
      }
    },
    {
      "id": "holiday",
      "tool": "datetime.is_holiday",
      "args": {
        "country": "JP",
        "date": "{{now.date}}"
      }
    },
    {
      "id": "rate",
      "tool": "network.get_exchange_rate",
      "args": {
        "from": "USD",
        "to": "JPY",
        "amount": 100
      }
    }
  ]
}

JSON 検証 → マージ → 統計計算

JSON を検証し、デフォルト値をマージしたうえで数値配列の統計を計算する。

{
  "tools": [
    {
      "id": "validate",
      "tool": "data.validate_json",
      "args": {
        "json_str": "{\"scores\":[10,20,30,40]}"
      }
    },
    {
      "id": "merge",
      "tool": "data.merge_json",
      "args": {
        "mode": "merge",
        "base": "{{validate.json}}",
        "patch": {
          "meta": {
            "source": "batch"
          }
        }
      }
    },
    {
      "id": "stats",
      "tool": "data.calc_stats",
      "args": {
        "values": [
          10,
          20,
          30,
          40
        ]
      }
    }
  ]
}

スラッグ生成 → Base64 → HMAC 署名

テキストからスラッグを生成し、Base64 エンコードして HMAC 署名を順次作成する。

{
  "tools": [
    {
      "id": "slug",
      "tool": "text.generate_slug",
      "args": {
        "text": "Hello World API"
      }
    },
    {
      "id": "b64",
      "tool": "convert.base64",
      "args": {
        "data": "{{slug.slug}}",
        "direction": "encode"
      }
    },
    {
      "id": "hmac",
      "tool": "security.generate_hmac",
      "args": {
        "mode": "sign",
        "algorithm": "sha256",
        "message": "{{b64.output}}",
        "secret": "my-secret-key"
      }
    }
  ]
}

POST /v1/batch/execute

パラメータ:

パラメータ	型	必須	説明
tools	object[]	-	MCPツール名ベースのステップ配列（最大10件）。steps の代替
tools[].id	string	必須	ステップID（英数字・ハイフン・アンダースコア、最大32文字）
tools[].tool	string	必須	MCPツール名（例: datetime.get_current_datetime）
tools[].args	object	必須	対象ツールの inputSchema に対応する引数（{{}} 参照可）
steps	object[]	-	HTTPパスベースのステップ配列（最大10件）。tools の代替
steps[].id	string	必須	ステップID（英数字・ハイフン・アンダースコア、最大32文字。他ステップから参照するキー）
steps[].method	string	必須	HTTPメソッド: GET / POST / PUT / PATCH / DELETE
steps[].path	string	必須	/v1/ で始まる API パス（最大200文字）
steps[].query	object	-	クエリパラメータ（{{}} 参照可）
steps[].body	object	-	リクエストボディ（POST 等。{{}} 参照可）
stop_on_error	boolean	-	true（既定）: 最初の失敗以降をスキップ / false: エラー後も続行

レスポンスフィールド:

パラメータ	型	説明
results	object[]	各ステップの実行結果
results[].id	string	ステップID
results[].status	number	HTTPステータス（スキップ時は 0）
results[].body	unknown	レスポンスボディ（JSON）
results[].skipped	boolean	stop_on_error によりスキップされたか
results[].error	string	status >= 400 のときのエラーメッセージ
total_steps	number	リクエストのステップ総数
executed_steps	number	実際に実行したステップ数
failed_step	string \| null	最初に失敗したステップID
timed_out	boolean	全体タイムアウト（28秒）が発生したか

ステップ間参照（ドット記法）

文字列値の query / body フィールドに {{stepId.path.to.field}} を指定します。値全体が {{...}} のみの場合は元の型（数値・真偽値など）を保持します。文字列の一部に埋め込む場合は文字列に変換されます。

バッチ実行不可のエンドポイント

例1: ステップ間参照あり（現在時刻 → 祝日判定 → 為替レート）

リクエスト例:

curl -X POST "https://api.thousand-api.com/v1/batch/execute" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "steps": [
      {
        "id": "now",
        "method": "GET",
        "path": "/v1/datetime/now",
        "query": { "timezone": "Asia/Tokyo" }
      },
      {
        "id": "holiday",
        "method": "GET",
        "path": "/v1/calendar/is-holiday",
        "query": { "country": "JP", "date": "{{now.date}}" }
      },
      {
        "id": "rate",
        "method": "GET",
        "path": "/v1/exchangerate",
        "query": { "from": "USD", "to": "JPY", "amount": "100" }
      }
    ]
  }'

レスポンス例:

{
  "results": [
    { "id": "now", "status": 200, "body": { "date": "2026-06-09", "time": "12:00:00" }, "skipped": false },
    { "id": "holiday", "status": 200, "body": { "datetime.is_holiday": false }, "skipped": false },
    { "id": "rate", "status": 200, "body": { "rate": 156.2 }, "skipped": false }
  ],
  "total_steps": 3,
  "executed_steps": 3,
  "failed_step": null,
  "timed_out": false
}

例1b: tools 形式（MCPツール名で指定）

リクエスト例:

curl -X POST "https://api.thousand-api.com/v1/batch/execute" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tools": [
      {
        "id": "now",
        "tool": "datetime.get_current_datetime",
        "args": { "timezone": "Asia/Tokyo" }
      },
      {
        "id": "holiday",
        "tool": "datetime.is_holiday",
        "args": { "country": "JP", "date": "{{now.date}}" }
      },
      {
        "id": "rate",
        "tool": "network.get_exchange_rate",
        "args": { "from": "USD", "to": "JPY", "amount": 100 }
      }
    ]
  }'

例2: stop_on_error: false で独立ステップを続行

リクエスト例:

curl -X POST "https://api.thousand-api.com/v1/batch/execute" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "stop_on_error": false,
    "steps": [
      { "id": "hash", "method": "GET", "path": "/v1/hash/generate", "query": { "text": "a", "algorithm": "sha256" } },
      { "id": "uuid", "method": "GET", "path": "/v1/uuid/generate" },
      { "id": "distance", "method": "GET", "path": "/v1/distance", "query": { "p1": "35.68,139.76", "p2": "35.65,139.74" } }
    ]
  }'

レスポンス例:

{
  "results": [
    { "id": "hash", "status": 200, "body": { "hash": "..." }, "skipped": false },
    { "id": "uuid", "status": 200, "body": { "uuids": ["..."] }, "skipped": false },
    { "id": "distance", "status": 200, "body": { "distance_meters": 3500 }, "skipped": false }
  ],
  "total_steps": 3,
  "executed_steps": 3,
  "failed_step": null,
  "timed_out": false
}

Health

MCP 自己診断用の軽量ヘルスチェック。認証不要・クォータ消費なし。

MCPツール名: utility.diagnose_mcp（内部で利用）

GET /v1/health

レスポンス例:

{
  "status": "ok",
  "timestamp": "2026-06-19T10:00:00.000Z"
}

Diagnose MCP

MCP サーバーと API スタックの自己診断。API 疎通（/v1/health）・API キー有効性・無効ツール一覧を一括確認します。いずれのチェックもクォータを消費しません。

MCPツール名: utility.diagnose_mcp

レスポンス例:

{
  "api_health": "ok",
  "api_key_valid": true,
  "disabled_tools_count": 2,
  "disabled_tools": ["network.dns_lookup", "utility.calc_expression"],
  "checked_at": "2026-06-19T10:00:00.000Z"
}