API 使用教學

親戚稱謂計算機後端 API（`/api/calculate.php`）使用說明

← 回首頁 JSON API POST

1. 請求格式

{
  "codes": ["爸爸", "姐姐"]
}

2. 回應格式

成功範例：

{
  "ok": true,
  "shortTitle": "姑媽",
  "detailedTitle": null,
  "historySaved": true
}

成功但歷史寫入失敗範例：

{
  "ok": true,
  "shortTitle": "姑媽",
  "detailedTitle": null,
  "historySaved": false,
  "historyError": "permission denied"
}

失敗範例：

{
  "ok": false,
  "error": "含有不支援的稱謂：阿公"
}

3. 快速測試

curl（Windows PowerShell）：

curl -X POST "https://guagua5487.xyz/api/calculate.php" ^
  -H "Content-Type: application/json" ^
  -d "{\"codes\":[\"爸爸\",\"姐姐\"]}"

JavaScript fetch：

const res = await fetch("/api/calculate.php", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ codes: ["爸爸", "姐姐"] })
});
const data = await res.json();
console.log(data);

PHP cURL：

$payload = json_encode(array("codes" => array("爸爸", "姐姐")), JSON_UNESCAPED_UNICODE);

$ch = curl_init("https://guagua5487.xyz/api/calculate.php");
curl_setopt_array($ch, array(
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => array("Content-Type: application/json"),
  CURLOPT_POSTFIELDS => $payload,
));
$response = curl_exec($ch);
curl_close($ch);

echo $response;

Python requests：

import requests

url = "https://guagua5487.xyz/api/calculate.php"
payload = {"codes": ["爸爸", "姐姐"]}
headers = {"Content-Type": "application/json"}

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

Go (net/http)：

package main

import (
  "bytes"
  "fmt"
  "io"
  "net/http"
)

func main() {
  url := "https://guagua5487.xyz/api/calculate.php"
  body := []byte(`{"codes":["爸爸","姐姐"]}`)

  req, _ := http.NewRequest("POST", url, bytes.NewBuffer(body))
  req.Header.Set("Content-Type", "application/json")

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()

  data, _ := io.ReadAll(resp.Body)
  fmt.Println(string(data))
}

C# (HttpClient)：

using System.Net.Http;
using System.Text;

var url = "https://guagua5487.xyz/api/calculate.php";
var json = "{\"codes\":[\"爸爸\",\"姐姐\"]}";

using var client = new HttpClient();
using var content = new StringContent(json, Encoding.UTF8, "application/json");
var res = await client.PostAsync(url, content);
var text = await res.Content.ReadAsStringAsync();

Console.WriteLine(text);

Java (HttpClient)：

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
  public static void main(String[] args) throws Exception {
    String url = "https://guagua5487.xyz/api/calculate.php";
    String json = "{\"codes\":[\"爸爸\",\"姐姐\"]}";

    HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create(url))
      .header("Content-Type", "application/json")
      .POST(HttpRequest.BodyPublishers.ofString(json))
      .build();

    HttpClient client = HttpClient.newHttpClient();
    HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
  }
}

4. 關係對照表（代碼 / 中文稱謂）

代碼代表
F爸爸
M媽媽
B+哥哥
B-弟弟
Z+姐姐
Z-妹妹
S兒子
D女兒
H老公
W老婆

5. 常見錯誤排查

若看到「Unexpected token '<'」通常是 API 回傳了 HTML 錯誤頁，請檢查 API URL 是否正確、`/api/calculate.php` 是否可直接打開。