概述

Acuris 是一個商業地址驗證、地理編碼、反向地理編碼和自動補全 API，位於 https://api.acuris-geo.com。此技能教導代理如何透過已發布的 SDK 套件，在 TypeScript / JavaScript 程式碼中正確整合它，以及如何從其他地址驗證 (AV) 供應商進行遷移。

涵蓋完整整合層面的兩個 npm 套件如下：

套件	說明
`@acuris-geo/av-sdk`	與平台無關的 TypeScript SDK。零執行時期相依性。可在 Node 18+、現代瀏覽器（僅伺服器端角色）、具備 `fetch` 的邊緣執行時期使用。
`@acuris-geo/centra-checkout`	React 組件庫：`<AcurisAddressInput>`（提前輸入）、`<AcurisAddressValidator>`（無頭模式）、結帳型 hooks。

後端或非 React 前端請直接使用 SDK。若需要即用型 React UI，請使用組件套件；它會呼叫您的 API 代理路由，而這些路由則在伺服器端呼叫 SDK。

使用時機

當使用者正在進行以下操作時，請使用此技能：

建置地址輸入 UI（表單中的自動補全、結帳步驟、註冊流程）。
在提交表單前驗證地址，再進行持久化儲存。
將地址進行正向地理編碼為緯度/經度（運送區域、距離、服務區域檢查）。
將座標進行反向地理編碼為最近的已知地址。
清理批量地址資料集以進行資料品質工作。
從其他地址驗證供應商（Informatica AddressDoctor / Loqate / Experian QAS / Melissa / Smarty）遷移 — 請參閱遷移參考。

請勿將此技能用於：

路線規劃、導航、等時線、地點搜尋或一般興趣點 (POI) 查詢。 Acuris 僅處理地址；這些功能屬於 Google Maps、Mapbox 或 Amazon Location。
渲染地圖。Acuris SDK 會回傳緯度/經度，但並未提供地圖渲染器 — 請根據使用者偏好，將座標與 MapLibre / Leaflet / Google Maps 搭配使用。

API 一覽

四個端點。全部位於 https://api.acuris-geo.com。驗證方式為單一標頭 — X-Acuris-Key: <ACURIS_API_KEY>。

操作	SDK 函數	HTTP
驗證	`validateAddress(client, input, opts)`	`POST /validate`
正向地理編碼	`geocodeAddress(client, input, opts)`	`GET /geocode`（或字串 → `/validate`）
反向地理編碼	`reverseGeocode(client, {lat,lng}, opts)`	`GET /reverse`
自動補全	`suggestAddress(client, q, opts)`	`GET /suggest`

國家代碼必須是 ISO-3 小寫格式（"usa"、"deu"、"gbr"）。如果您有 ISO-2 代碼，請先轉為小寫並進行對應（"us" → "usa"、"de" → "deu"）後再呼叫。

詳細的請求/回應結構、錯誤階層和重試語義，請參閱 references/api-reference.md。

快速入門

# 鎖定目前已發布的版本 — 這些套件仍處於 1.0 版本之前
# 且 `^1.x` 範圍將無法解析。
npm install @acuris-geo/av-sdk@^0.1.2
# （可選，適用於 React 商店前端 — 0.1.2+ 版本可顯示下拉式預設值）
npm install @acuris-geo/centra-checkout@^0.1.2

import { AcurisClient, validateAddress } from "@acuris-geo/av-sdk";

const client = new AcurisClient({ apiKey: process.env.ACURIS_API_KEY });

const result = await validateAddress(client, {
  country: "deu",
  street: "Friedrichstraße",
  house_number: "43",
  city: "Berlin",
  postcode: "10117",
});

result.accuracy_type;  // "rooftop" | "parcel" | "street_interpolated" | ...
result.confidence;     // 0..1
result.standardized?.formatted_address;
result.lat;  result.lng;

如果在環境中已設定 ACURIS_API_KEY，則可以完全省略 apiKey 選項。

預設值

當使用者未特別指定時，偏好使用下列設定：

API 金鑰在環境變數中。 從 process.env.ACURIS_API_KEY 讀取。切勿內嵌金鑰，也切勿將其暴露給瀏覽器。若要進行本地評估，可透過一次呼叫取得免費的開發金鑰：
```
curl -X POST https://api.acuris-geo.com/dev-key \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]"}'
# → {"api_key":"<token>","validation_credits":100,
#     "geocode_credits":100,"expires_at":"...","tier":"dev",...}
export ACURIS_API_KEY=<api_key>
```
開發金鑰在 7 天內限制為 100 次驗證 + 100 次地理編碼（速率限制為每個電子郵件每天 1 次發行，每個 IP 每天 1 次）。它適用於所有端點 — /validate、/geocode、/reverse、/suggest。如果需要更多空間，請在 https://api.acuris-geo.com/register 執行完整的 28 天試用（1000 次驗證 + 1000 次地理編碼）。生產環境請參閱 https://acuris-geo.com/acuris-pricing/。
伺服器端呼叫。 SDK 適用於 Node / 邊緣 / 伺服器執行時期。在瀏覽器應用程式中，請透過您自己的後端進行路由（Next.js API 路由、Express 處理器、Cloudflare Worker — 請參閱 references/nextjs-proxy.md）。
React UI 的組件庫。 使用 @acuris-geo/centra-checkout（<AcurisAddressInput> 用於提前輸入，<AcurisAddressValidator> 用於表單提交驗證），而非自行撰寫 fetch 迴圈。
針對暫時性失敗進行重試。 SDK 會自動重試 5xx、429、網路錯誤和逾時（3 次嘗試，指數型退避）。請勿在其上層新增重試層。
每個程序一個客戶端。 new AcurisClient(...) 的建立成本低廉，但長效的實例能保持 keep-alive 連線的活躍狀態，並避免重新讀取環境變數。

常見錯誤

這些是我們在客戶程式碼或生成的程式碼中最常看到的錯誤。請避免它們。

從瀏覽器傳送 API 金鑰。 SDK 適用於任何啟用 fetch 的執行時期，但 apiKey 是伺服器端的憑證。瀏覽器必須透過代理路由。@acuris-geo/centra-checkout 組件預期一個 endpoints 物件指向您自己的 URL，而非直接指向 Acuris API。
ISO-2 國家代碼。 API 會拒絕 "US" 和 "de"。請使用 ISO-3 小寫格式："usa"、"deu"、"gbr"、"fra"、"fin"。如果您只有 ISO-2，請在邊界處進行對應。
使用 Authorization: Bearer … 而非 X-Acuris-Key 標頭。 SDK 會自動設定正確的標頭；如果您因任何原因自行撰寫 HTTP，標頭名稱很重要。
將 accuracy_type 視為封閉式列舉。 隨著時間推移會新增新的層級（street_interpolated、street_center、locality_centroid、...）。請始終明確處理已記錄的值，並將未知值視為不透明傳遞，而非拋出錯誤。
以相同方式捕捉所有錯誤。 SDK 會拋出具型別的子類別（AcurisAuthError、AcurisRateLimitError、AcurisValidationError、AcurisNotFoundError、AcurisServerError、AcurisTimeoutError、AcurisNetworkError）。4xx 是您的程式碼錯誤；5xx 和速率限制是執行時期問題；驗證錯誤表示部署配置錯誤。它們需要不同的處理方式。
在 /suggest 和 /reverse 上忘記加入 country。 與 /validate 不同，這些端點需要明確的國家選項（它們沒有可用於推斷的輸入）。
在輸出時手動解析自由格式字串。 SDK 會回傳一個帶有 formatted_address 的 standardized 物件。請顯示該值，不要從個別欄位重新組合 — 地區特定的排序已內建。
持久化儲存 Acuris 的原始回應時，未同時快照請求輸入。 如果您儲存了 result.standardized，也請一併儲存使用者輸入的內容。否則，您之後將無法判斷信心度下降是用戶的錯誤還是 Acuris 的問題。
當使用者要求自動補全時，卻建置了一個「結構化欄位表單」。 自動補全是一個輸入框 + 下拉選單 + 選取 — 建議內容已包含已解析的欄位，因此您不應將它們渲染為單獨的方塊。如果使用者要求「自動補全」，只需提供 <AcurisAddressInput> 和一個狀態列；街道 / 門牌號碼 / 郵遞區號 / 城市等子欄位屬於提交時驗證的作法，而非自動補全的作法。請參閱 references/autocomplete.md — 最上方的「自動補全是什麼、不是什麼」章節涵蓋了這一點。
從國家選取器中遺漏英國 (gbr)。 此技能的早期版本曾說 Acuris 缺乏皇家郵政 PAF（郵遞區號地址檔案）授權，並告訴您在所有地方都排除英國。那已經過時了：英國的覆蓋範圍現在由 PAF 支援，且是旗艦資料集 — /validate 和 /suggest 完全支援 gbr（街道型自動補全；standardized 包含 udprn、uprn 和傳統的 county），而 POST /postcode-lookup 會回傳英國郵遞區號的每個投遞點。請在示範和國家選取器中包含 gbr。適用 PAF 使用條款：https://api.acuris-geo.com/legal/paf-terms。
在自動補全選取器中列出一個未接線 /suggest 的國家。 這是最常見的尷尬示範來源。**/suggest（自動補全）和 /validate / /geocode / /reverse 涵蓋不同的國家集合。**驗證和地理編碼適用於 200 多個 ISO-3 代碼；自動補全需要每個國家專屬的 NORM 欄位和索引（一個單獨的工程步驟），並且目前僅在 7 個國家運作：

// 唯一已接線 /suggest 的國家：
const AUTOCOMPLETE_COUNTRIES = [
  { code: "usa", label: "United States" },
  { code: "gbr", label: "United Kingdom" },  // 皇家郵政 PAF（街道型）
  { code: "deu", label: "Germany" },
  { code: "nld", label: "Netherlands" },
  { code: "fin", label: "Finland" },
  { code: "swe", label: "Sweden" },
  { code: "jpn", label: "Japan" },
];

在自動補全選取器中列出 fra、esp、ita 等國家，比省略它們更糟糕 — 使用者輸入時沒有任何反應，這會讓人覺得「產品壞了」。對於這些國家，/suggest 會默默地回傳 []。

用於驗證 / 地理編碼 / 反向地理編碼示範的更廣泛國家選取器則可以包含它們：

// 適用於 /validate、/geocode、/reverse（不適用於 /suggest）：
const VALIDATION_COUNTRIES = [
  // 已啟用自動補全的子集：
  { code: "usa", label: "United States" },
  { code: "gbr", label: "United Kingdom" },
  { code: "deu", label: "Germany" },
  { code: "nld", label: "Netherlands" },
  { code: "fin", label: "Finland" },
  { code: "swe", label: "Sweden" },
  { code: "jpn", label: "Japan" },
  // 僅限驗證/地理編碼（非自動補全）：
  { code: "fra", label: "France" },
  { code: "esp", label: "Spain" },
  { code: "ita", label: "Italy" },
  { code: "nor", label: "Norway" },
  { code: "dnk", label: "Denmark" },
  { code: "aut", label: "Austria" },
  { code: "che", label: "Switzerland" },
  { code: "bel", label: "Belgium" },
  { code: "prt", label: "Portugal" },
  { code: "aus", label: "Australia" },
  { code: "nzl", label: "New Zealand" },
  { code: "sgp", label: "Singapore" },
  { code: "bra", label: "Brazil" },
  { code: "mex", label: "Mexico" },
  { code: "can", label: "Canada" },
];

經驗法則：

如果 UI 使用 <AcurisAddressInput>（提前輸入）：使用 AUTOCOMPLETE_COUNTRIES（這 7 個）。
如果 UI 使用 <AcurisAddressValidator> 或任何會呼叫 /validate / /geocode / /reverse 的結構化表單：任一清單均可。
混合使用（同一表單中同時有自動補全和驗證，且使用同一個國家選取器）：使用 AUTOCOMPLETE_COUNTRIES。驗證集合是超集；使用者仍然可以驗證這 7 個國家中的任何一個。

隨著新國家獲得 NORM 欄位，已啟用自動補全的集合會持續成長。如果此清單看起來過時，請在擴充前先詢問。

實作模式

實作範例位於 references/。請載入與任務相符的範例：

遷移

Acuris 的商業切入點 — 這些是將程式碼從既有供應商移植的範例。每個範例都將舊版 API 對應到 Acuris 的等效項目，並附帶可執行的範例。

遷移範例是根據供應商文件撰寫的，而非使用者的實際整合。請將它們視為起點 — 在發布前，請針對您的特定配置檢閱對應關係。

定價與限制

正式 API 按請求計費。測試金鑰 test 可讓開發人員在評估期間執行端點，而不會消耗額度。定價已發布於 https://acuris-geo.com/acuris-pricing/。SDK 會遵循伺服器的速率限制（HTTP 429 附帶 retry_after）；預設重試策略會在重新擲回 AcurisRateLimitError 之前，進行指數退避並最多重試 3 次。

其他資源

SDK 原始碼：<https://github.com/Acuris-GmbH/acuris-centra-connector/tree/main/packages/acuris

…

[已截斷以進行翻譯]

Acuris-GmbH/acuris-agent-context

acuris-agent-context 是什麼？

在你喜歡的 AI 中提問

說明文件

概述

使用時機

API 一覽

快速入門

預設值

常見錯誤

實作模式

遷移

定價與限制

其他資源

相關技能

steipete/sag

steipete/oracle

steipete/peekaboo

mattpocock/design-an-interface

mattpocock/prototype

mattpocock/grill-me