✓ 已複製代碼到剪貼簿
GeoCheck. DOCS v0.1
行銷儀表板 ↗ 回到首頁 API 控制台

GeoCheck Developer API & SDK 文件

面向現代產品與自動化系統的客觀 GEO 引用量測開發者指南。

快速開始

GeoCheck 提供兩種整合方式：官方 TypeScript SDK (@geocheck/sdk) 或標準 REST HTTP API。 SDK 內建型別推導、顯式冪等鍵與 Retry-After 智慧輪詢，推薦於 Node.js / Bun 專案中優先使用。

安裝官方 SDK

BASH 
npm install @geocheck/sdk

身分驗證

所有對 Developer API 的請求皆必須在 HTTP 標頭中帶入 Bearer API 金鑰：

HTTP HEADER 
Authorization: Bearer gck_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

您可以在 API 控制台 建立您的第一把 API 金鑰。金鑰以 gck_ 為前綴，建立時只展示一次。

核心概念

四引擎並行架構

不同於單純包裝單一模型的轉售 API，GeoCheck 每次觀測固定直接呼叫 4 大官方搜尋 API：

搜尋引擎模型識別碼搜尋機制
OpenAIgpt-5.6-luna原生 Web Search Tool
Google Geminigemini-3.5-flash-liteGoogle Search Grounding
Perplexitysonar即時網頁索引用量
Anthropic Claudeclaude-haiku-4.5官方 Web Search Capability

全成才扣量原則

保證零扣冤枉額度： 只有當上述 4 家官方引擎全數完成搜尋與回答時，任務狀態才標記為 succeeded 並扣除 1 輪配額。 若任一家模型發生超時或網路失敗，整個任務標記為 failed，不計費、不扣除額度，但系統仍會回傳已成功的 partial_results 供開發者排查。

顯式冪等鍵機制

建立觀測時必須傳入 Idempotency-Key 標頭（例如 UUID v4）。若因網路瞬斷重試發送相同請求，系統會安全重放原有任務，絕不會產生重複排程或重複扣量。

TypeScript SDK 使用手冊

官方客戶端 @geocheck/sdk 提供純淨、無副作用的封裝，不含多餘依賴。

完整程式碼範例

TYPESCRIPT 
import { GeoCheckClient, GeoCheckApiError } from "@geocheck/sdk";

const client = new GeoCheckClient({
  apiKey: process.env.GEOCHECK_API_KEY!,
  baseUrl: "https://api.geocheck.lisheng.cv" // 預設
});

try {
  // 1. 建立非同步觀測任務
  const job = await client.createMeasurement({
    input: { type: "url", url: "https://mybrand.com" },
    locale: "zh-TW"
  }, crypto.randomUUID());

  console.log(`任務建立成功: ${job.measurement_id}`);

  // 2. 自動輪詢結果 (尊重 Retry-After)
  const result = await client.pollMeasurement(job.measurement_id, {
    intervalMs: 2000,
    timeoutMs: 120000
  });

  // 3. 輸出四家引擎觀測結果
  result.engines.forEach(engine => {
    console.log(`[${engine.id}] 狀態: ${engine.status}`);
    console.log(`引用數: ${engine.citations?.length || 0}`);
  });

} catch (err) {
  if (err instanceof GeoCheckApiError) {
    console.error(`API 錯誤 (${err.status}): ${err.code} - ${err.message}`);
  }
}

錯誤處理與自定義重試

當發生非 2xx 回應時，SDK 會拋出 GeoCheckApiError，其中包含 status (HTTP 狀態碼)、code (錯誤碼字串) 以及伺服器建議的 retryAfterMs。

REST API 參考

建立觀測任務

POST /v1/measurements

接受網址或自訂問題，非同步發起四引擎平行搜尋觀測。

標頭名稱必填說明
Authorization是Bearer <API_KEY>
Idempotency-Key是隨機唯一字串 (UUID v4)
Content-Type是application/json
REQUEST BODY JSON
{
  "input": {
    "type": "url",
    "url": "https://example.com"
  },
  "locale": "zh-TW"
}
RESPONSE 202 ACCEPTED
{
  "job_id": "job_3f42b8...",
  "measurement_id": "msmt_81a2...",
  "status": "queued",
  "created_at": "2026-09-09T14:30:00.000Z"
}

取得觀測結果

GET /v1/measurements/:measurement_id

若任務仍在執行中，回傳 409 Conflict (附帶 Retry-After 標頭)；若已完成則回傳 200 OK 完整結構。

RESPONSE 200 OK
{
  "measurement_id": "msmt_81a2...",
  "status": "succeeded",
  "engines": [
    {
      "id": "openai",
      "model": "gpt-5.6-luna",
      "status": "succeeded",
      "answer": "...",
      "citations": [
        { "url": "https://example.com/about", "title": "Example Official" }
      ]
    },
    {
      "id": "gemini",
      "model": "gemini-3.5-flash-lite",
      "status": "succeeded",
      "answer": "...",
      "citations": [...]
    },
    {
      "id": "perplexity",
      "model": "sonar",
      "status": "succeeded",
      "answer": "...",
      "citations": [...]
    },
    {
      "id": "anthropic",
      "model": "claude-haiku-4.5",
      "status": "succeeded",
      "answer": "...",
      "citations": [...]
    }
  ],
  "created_at": "2026-09-09T14:30:00.000Z",
  "completed_at": "2026-09-09T14:30:11.850Z"
}

查詢任務狀態

GET /v1/jobs/:job_id

查詢任務輕量狀態 (queued, running, succeeded, failed)，不包含龐大的四引擎結果內容。

用量與配額查詢

GET /v1/usage

RESPONSE 200 OK
{
  "plan": "free",
  "used_rounds": 1,
  "reserved_rounds": 0,
  "remaining_rounds": 2,
  "quota_limit": 3,
  "window_strategy": "daily",
  "expires_at": "2026-09-16T14:30:00.000Z"
}

刪除觀測結果

DELETE /v1/measurements/:measurement_id

依個資與合規要求主動刪除結果內容，成功回傳 204 No Content。後續再查詢該 ID 將回傳 410 Gone。

HTTP 錯誤代碼表

狀態碼錯誤代碼說明與處置建議
400invalid_request請求參數不合法，請核對 JSON 結構與 URL 格式
401auth_required未帶入有效之 Bearer API 金鑰
402payment_required方案額度耗盡或所選付費方案尚未完成權益開通
403trial_not_started控制台尚未啟用，請先至 Console 選擇方案
404not_found找不到指定的 Job ID 或 Measurement ID
409result_not_ready四引擎正在量測中，請依 Retry-After 稍後再查詢
410content_deleted該觀測結果已依資料保存策略或主動指示刪除
429rate_limited呼叫超出速率限制，請稍候重試