GBG Loqate - Reach

Loqate 命令行工具

使用 Loqate 的 API 验证地址、电子邮件和电话号码。
通过一条命令获取置信度评分、考虑策略的建议和完整的可审计性。
为需要判断联系数据是否足以胜任任务的 Agent 提供实时验证决策。
属于 GBG Reach。

lqt verify  ·  lqt parse  ·  lqt mcp

---

安装

macOS

# Apple Silicon (M1/M2/M3/M4)
curl -sL https://github.com/gbgplc/lqt/releases/latest/download/lqt_darwin_arm64.tar.gz | tar xz
sudo mv lqt /usr/local/bin/

# Intel
curl -sL https://github.com/gbgplc/lqt/releases/latest/download/lqt_darwin_amd64.tar.gz | tar xz
sudo mv lqt /usr/local/bin/

Linux

# x86_64
curl -sL https://github.com/gbgplc/lqt/releases/latest/download/lqt_linux_amd64.tar.gz | tar xz
sudo mv lqt /usr/local/bin/

# ARM64
curl -sL https://github.com/gbgplc/lqt/releases/latest/download/lqt_linux_arm64.tar.gz | tar xz
sudo mv lqt /usr/local/bin/

Windows

1. 从最新版本下载 lqt_windows_amd64.zip
2. 解压 lqt.exe
3. 将其移至 PATH 中的目录，或直接运行

验证安装

lqt version

所有下载

请参阅发布版本，查看所有版本和平台。每个发布版本都包含 SHA-256 校验和。

平台	压缩包
macOS（Apple Silicon）	lqt_*_darwin_arm64.tar.gz
macOS（Intel）	lqt_*_darwin_amd64.tar.gz
Linux（x86_64）	lqt_*_linux_amd64.tar.gz
Linux（ARM64）	lqt_*_linux_arm64.tar.gz
Windows（x86_64）	lqt_*_windows_amd64.zip

---

快速开始

API 密钥

验证需要 Loqate API 密钥。parse 命令还可选使用 Anthropic API 密钥。

macOS / Linux：

export LOQATE_API_KEY=your-key-here

# Optional — for lqt parse
export ANTHROPIC_API_KEY=your-key-here

Windows（PowerShell）：

$env:LOQATE_API_KEY="your-key-here"

# Optional — for lqt parse
$env:ANTHROPIC_API_KEY="your-key-here"

首次验证

macOS / Linux：

# Verify an address
lqt verify --address "125 Summer Street, Boston, MA 02110, US"

# Verify address + email + phone with a policy
lqt verify -a "10 Downing St, London, GB" \
           -e "[email protected]" \
           -p "+442071234567" \
           --policy shipping

# Parse and standardize without calling Loqate (uses Claude)
lqt parse --address "125 summer street boston ma 02110 us"

Windows（PowerShell）：

# Verify an address
.\lqt.exe verify --address "125 Summer Street, Boston, MA 02110, US"

# Verify address + email + phone with a policy
.\lqt.exe verify -a "10 Downing St, London, GB" -e "[email protected]" -p "+442071234567" --policy shipping

# Parse and standardize without calling Loqate (uses Claude)
.\lqt.exe parse --address "125 summer street boston ma 02110 us"

---

命令

verify

使用 Loqate 的 API 验证地址、电子邮件和/或电话号码。返回置信度评分，以及由策略驱动的建议（接受、复核或拒绝）。

lqt verify [flags]

标志：

标志	短选项	描述
--address	-a	要验证的完整地址
--locality		城市/城镇
--admin-area		州/省
--postcode		邮政编码/ZIP 代码
--country	-c	ISO 两字母国家/地区代码
--detect-country		未提供国家/地区时，根据地址推测国家/地区，并在结果中标记此推测。仅适用于地址；默认关闭。
--suggest		地址未通过策略（review 或 reject）时，查询 Loqate 推荐的其他地址，并将其返回到 address.suggestions 中。已接受的地址不会调用此功能。**需要在账户中启用单独授权的 Loqate 功能。**仅适用于地址；默认关闭；不能与 --batch 同时使用。
--suggest-limit		要返回的建议数量上限，范围为 1–10（默认值为 5）。需要使用 --suggest。
--suggest-below		建议的置信度下限：置信度低于此值的已接受地址也会获得建议。默认使用当前策略的值（standard 为 0.85）。0 表示禁用此下限。需要使用 --suggest。
--suggestion-id		根据用户选择的建议，通过 address.suggestions 中的 id 验证该建议。此选项会将 id 解析为清理后的地址组成部分，并对其进行验证。请用此选项代替 --address。**会消耗 Loqate 额度。**不能与 --batch 或 --dry-run 同时使用。
--email	-e	要验证的电子邮件地址
--phone	-p	电话号码（E.164 格式）
--key	-k	Loqate API 密钥（覆盖环境变量）
--policy		策略名称：strict、shipping、standard、permissive
--policy-file		自定义策略 JSON 文件的路径
--batch	-b	CSV/TSV/管道分隔文件的路径（或使用 - 表示标准输入）
--delimiter	-d	批处理分隔符：comma、tab、pipe（未指定时自动检测）
--output	-o	输出格式：json、jsonl、table
--summary	-s	显示批处理摘要统计信息
--field		额外的 Loqate 输入字段 Key=Value（可重复使用）
--option		Loqate API 选项 Key=Value（可重复使用；嵌套时使用点号表示法）
--jsonl		JSON Lines 输出（每行一个对象）
--no-color		禁用彩色输出
--verify-url		自定义地址验证端点 URL（覆盖 LOQATE_VERIFY_URL 环境变量）
--verify-key		自定义地址验证 API 密钥（覆盖 LOQATE_VERIFY_KEY 环境变量）。设置此选项后，仅验证地址时无需指定 --key。
--verbose	-v	显示推理日志

示例：

# Simple address verification
lqt verify -a "1600 Amphitheatre Parkway, Mountain View, CA 94043, US"

# Multi-field verification with strict policy
lqt verify -a "221B Baker St, London, GB" \
           -e "[email protected]" \
           -p "+442071234567" \
           --policy strict

# Email-only or phone-only (no address required)
lqt verify -e "[email protected]"
lqt verify -p "+442071234567"

# Guess a missing country from the address (opt-in, address-only)
lqt verify -a "10 Downing St, London SW1A 2AA" --detect-country
# → result includes: country_guessed, detected_country, country_confidence

# Suggest alternatives when the address does not clear the policy (opt-in, address-only)
lqt verify -a "10 downin st london" -c GB --suggest
lqt verify -a "10 downin st london" -c GB --suggest --suggest-limit 3
# → result includes: address.suggestions with a list of candidate addresses

# Accepted but not confident: a street-level match accepted at 0.55 still gets alternatives
lqt verify -a "marsh wall, E14 9TN" -c GB --suggest
# Move or disable the confidence floor
lqt verify -a "marsh wall, E14 9TN" -c GB --suggest --suggest-below 0.95
lqt verify -a "marsh wall, E14 9TN" -c GB --suggest --suggest-below 0

# JSON output for piping to other tools
lqt verify -a "10 Downing St, London, GB" -o json | jq '.address.confidence'

# Extended input fields
lqt verify -a "125 Summer St" --field Organization="Acme Corp" --field Building="Suite 200"

# API options (dot notation for nesting)
# GeoCode is sent at the request root as a JSON boolean (where Loqate expects it);
# ServerOptions values are sent as strings (use Loqate's exact casing).
lqt verify -a "125 Summer St, Boston, MA 02110, US" --option GeoCode=true
lqt verify -a "125 Summer St, Boston, MA 02110, US" --option ServerOptions.OutputCasing=Upper

输入字段和 API 选项的完整列表：Loqate International Batch Cleanse API

地址建议（--suggest）

许可。 建议功能使用 Loqate 的一项功能，其许可与地址验证分开提供，并且必须在你的账户上启用。如果未启用，不会影响其他功能：验证仍会返回正常结果和退出代码，原因会显示在 suggestions.error 中（通常是 Loqate 返回的未知密钥或许可消息）。请联系你的 Loqate 账户联系人为你启用该功能。

验证会告诉你地址有误，而建议会告诉你正确地址可能是什么。添加 --suggest 后，lqt 会向 Loqate 查询与输入内容匹配的真实地址，并将其与判定结果一并返回。

出现以下任一情况时会执行查询：

1. 地址未被接受（review 或 reject）；或
2. 地址已被接受，但得分低于策略的建议阈值（standard 为 0.85 — 见策略表）。

第二种情况可以捕捉那些差一点就匹配的地址。策略会接受置信度达到或超过最低值的所有地址，因此已接受不等于可信度高：在 standard 策略下，输入 marsh wall, E14 9TN 会匹配到一条街道，得分恰好为 0.55，因此会被接受——但缺少门牌号，而且有更合适的地址。使用 --suggest-below 可调整该阈值（--suggest-below 0 会关闭置信度检查，仅在 review/reject 时提供建议）。

{
  "address": {
    "verified_address": "Downing Street, London",
    "confidence": 0.5,
    "recommendation": "review",
    "suggestions": {
      "requested": true,
      "triggered": true,
      "reason": "accepted but confidence 0.55 is below the 0.85 floor",
      "floor": 0.85,
      "source": "loqate",
      "count": 2,
      "items": [
        {
          "id": "GB|RM|A|52509479",
          "type": "Address",
          "text": "10 Downing Street",
          "description": "London, SW1A 2AA",
          "address": "10 Downing Street, London, SW1A 2AA"
        },
        {
          "id": "GB|RM|A|52509480",
          "type": "Address",
          "text": "11 Downing Street",
          "description": "London, SW1A 2AB",
          "address": "11 Downing Street, London, SW1A 2AB"
        }
      ]
    }
  }
}

需要了解的事项：

• 默认关闭，因此除非你主动请求建议，否则现有输出不会改变。
• 不会查询置信度高且已接受的地址 — 仅在查询有帮助时才会产生额外延迟。仍会返回 suggestions 区块，其中包含 "triggered": false 和 reason，因此你可以区分“无需替代选项”和“从未请求建议”。
• floor 会报告所应用的阈值，因此即使不知道策略的配置，你也能看出为何执行了（或未执行）查询。
• 建议绝不会改变判定结果。 如果查询失败，原因会显示在 suggestions.error 中，验证结果保持不变。
• 仅适用于地址。 使用 verify --email / --phone 或 verify_contact 时，只有地址区块会附加建议。
• "expandable": true 的条目表示街道、邮政编码或包含多个地址的建筑，而非单个可投递地址。请在其中搜索具体的场所。
• 建议查询不会消耗 Loqate 验证额度，但你的账户必须拥有此功能的许可（见上方说明）。
• 建议功能需要标准 Loqate 密钥（--key / LOQATE_API_KEY）；仅有 --verify-key 只能用于地址验证。
• 不支持与 --batch 一起使用。 大型文件会扩展为数量无法预知的查询，因此系统会拒绝这种组合。请先验证文件，再对标记出的行逐一重新运行并添加 --suggest。

MCP verify_address / verify_contact 工具和 REST /v1/verify/address / /v1/verify/contact 端点均支持此功能，参数为 suggest: true，还可选用 suggest_limit（1–10，默认值为 5）和 suggest_below（0–1）。

闭环流程：提供选项、选择、重新验证

建议只是候选项，并非判定结果。 条目不包含置信度得分、匹配级别或 AVC — 它们只是参考数据推测地址可能是什么。不要未经确认就将其写入你的记录系统。请通过以下三个步骤完成闭环：

1. 使用 --suggest 进行验证。 suggestions.items 非空表示存在替代选项。
2. 将 items[].address 提供给能够作出决定的人 — 在结账或支持流程中交由客户选择，在自动化流程中交由 Agent 选择。此字段就是可直接展示的地址。
3. 通过 id 确认所选项（--suggestion-id）。该项的结果 — 包括其置信度、匹配级别和标准化字段 — 才是你要保留的内容。完整流程如下。

# 1. verify, asking for alternatives
lqt verify -a "marsh wall, E14 9TN" -c GB --suggest -o json > result.json

# 2. show the candidates
jq -r '.address.suggestions.items[] | .address' result.json
#   1 Marsh Wall, London, E14 9TN
#   2 Marsh Wall, London, E14 9TN

# 3. re-verify the chosen one — this is the decision of record
lqt verify -a "1 Marsh Wall, London, E14 9TN" -c GB -o json

通过 REST 实现的流程结构相同 — 先调用一次并使用 suggest，再使用所选项进行普通调用：

curl -s -X POST https://your-host/v1/verify/address \
  -H "Authorization: Bearer $LOQATE_API_KEY" -H 'Content-Type: application/json' \
  -d '{"address":"marsh wall, E14 9TN","country":"GB","suggest":true}'

curl -s -X POST https://your-host/v1/verify/address \
  -H "Authorization: Bearer $LOQATE_API_KEY" -H 'Content-Type: application/json' \
  -d '{"address":"1 Marsh Wall, London, E14 9TN","country":"GB"}'

完整流程，端到端

1. 使用 --suggest 验证 — 为未能干净匹配的地址获取候选项。
2. 提供 items[].address，交由决策者选择。
3. 使用 --suggestion-id 确认，并传入所选项的 id。该结果就是最终保留的结果。

# 1 + 2
lqt verify -a "marsh wall london" -c GB --suggest -o json > r.json
jq -r '.address.suggestions.items[] | "\(.id)\t\(.address)"' r.json

# 3 — confirm the chosen one by id, not by re-typing the text
lqt verify --suggestion-id "GB|RM|B|55782678" -o json

传入 id 而非文本，才能确保第 3 步准确：lqt 会获取该地址经过清理的组成部分（公司、子建筑物、门牌号、街道、城市、邮编、国家）并验证这些内容，因此不会重新解析。对于包含公司名称的建议，这一点很重要，例如 — London Lash, 56 Marsh Wall, London — 重新读取文本可能会把公司名误当作街道的一部分。

结果会记录其解析依据，因此你可以审计，而无需再次解析：

{
  "verified_address": "56 Marsh Wall, London, E14 9TP",
  "confidence": 0.95,
  "recommendation": "accept",
  "resolved_from": {
    "suggestion_id": "GB|RM|B|55782678",
    "address": "London Lash, Unit 7, Hampton Tower, 56 Marsh Wall, LONDON, E14 9TP"
  }
}

通过 REST 执行相同的两个步骤：

curl -s -X POST https://your-host/v1/verify/address \
  -H "Authorization: Bearer $LOQATE_API_KEY" -H 'Content-Type: application/json' \
  -d '{"address":"marsh wall london","country":"GB","suggest":true}'

curl -s -X POST https://your-host/v1/verify/address \
  -H "Authorization: Bearer $LOQATE_API_KEY" -H 'Content-Type: application/json' \
  -d '{"suggestion_id":"GB|RM|B|55782678"}'

须知：

• 第 3 步会消耗一个 Loqate 额度来解析 id（第 1 步的搜索不会）。只解析选定的那个地址，不要解析整个列表来进行比较。
• suggestion_id 会替代 address；同时发送两者会返回 400。
• --batch 和 --dry-run 均不可用（解析需要实时的计费调用）。
• 过期的 id 会返回 SUGGESTION_NOT_FOUND / 404。Id 会随时间变化 — 请重新搜索，而不要重试相同的 id。

只想获取地址，而非进行决策？ 单独解析即可：

lqt retrieve --id "GB|RM|B|55782678"           # components as JSON
lqt retrieve --id "GB|RM|B|55782678" -o table  # human-readable

通过 REST 使用 GET /v1/address/{id}，或使用 retrieve_address MCP 工具。这会返回参考数据，而非验证结果 — 不包含置信度或建议 — 因此不要将其视为已核验。

遵循以下四条规则，确保流程安全：

• 确认调用时省略 suggest。 如果所选地址仍未达到策略要求，你会得到一组新的建议，自动化流程可能会在这些建议之间反复循环。先进行一轮建议，然后进行普通验证。
• 让重新验证决定结果 — 而不是因为存在建议就直接认定。如果确认结果为 review 或 reject，记录仍需人工处理。你只是缩小了范围，并未解决问题。
• 不要原样重新验证 expandable 项。 它是街道、邮编或建筑物，因此验证结果最多只能到街道级别。用它来询问缺失的信息（“Marsh Wall 上的哪个门牌号？”），然后验证完整地址。
• 绝不存储 id。 它是由 Loqate 分配且会随时间变化的标识符。应以第 3 步返回的已验证地址作为键。

确认调用时保留原始请求中的国家信息 — 删除它可能会改变匹配结果。

建议排序由 Loqate 决定

lqt 按照 Loqate 提供的顺序返回建议 — 不会重新排序或筛选。Loqate 会匹配整个地址记录，包括组织名称，因此像 marsh wall london 这样的查询，会将名称中含有“London”的企业排在该街道上的普通住宅地址之前：

London Lash, 56 Marsh Wall, London, E14 9TP
London Metropolis Ltd, 77 Marsh Wall, London, E14 9SH

这是标准的地址自动补全行为，但这意味着建议质量取决于输入质量。如果你知道国家/地区，请通过 --country 传入，而不要将其留在地址文本中 — 这样会将该词从模糊匹配中移出，并作为筛选条件：

lqt verify -a "marsh wall london" --suggest      # "london" is matchable text
lqt verify -a "marsh wall" -c GB --suggest       # cleaner: country is a filter

parse

使用 Claude（Haiku）解析并标准化联系信息。提取地址组成部分、验证电子邮件语法，并根据 250 多种国家/地区特有的邮政格式规范化电话号码。不会调用 Loqate API，也不会消耗额度。

lqt parse [flags]

标志：

标志	短选项	描述
--address	-a	要解析的完整地址
--email	-e	要验证的电子邮件地址
--phone	-p	要规范化的电话号码
--country	-c	ISO 两字母国家/地区代码提示
--batch	-b	CSV/TSV/竖线分隔文件路径（或使用 - 表示标准输入）
--delimiter	-d	批处理分隔符：comma、tab、pipe（未指定时自动检测）
--output	-o	输出格式：json、jsonl、table
--jsonl		JSON Lines 输出
--no-color		禁用彩色输出
--anthropic-key		Anthropic API 密钥（覆盖环境变量）

示例：

# Parse a messy address into structured components
lqt parse -a "125 summer street boston ma 02110 us"

# Parse address + validate email + normalize phone
lqt parse -a "10 downing st london" -e "[email protected]" -p "02071234567"

# Batch parse from CSV
lqt parse --batch messy-data.csv --output json

policy

列出、检查并验证验证策略。

lqt policy list                  # List all built-in policies
lqt policy show <name>           # Show full JSON for a policy
lqt policy validate <file>       # Validate a custom policy JSON file

mcp

启动 MCP（Model Context Protocol）服务。将 LQT 作为工具提供给 AI Agent。

lqt mcp                    # Stdio transport (launched by clients)
lqt mcp --http :8080       # HTTP transport (deployed as a service)
lqt mcp --smoke-test       # Verify the server starts correctly and exit

标志：

标志	默认值	描述
--http		监听地址（例如 :8080、127.0.0.1:8080）
--rate-limit	10	每个 IP 每秒的最大请求数（0 表示禁用）
--rate-burst	20	速率限制器允许的最大突发请求数
--smoke-test		对 MCP 服务进行自检（检查工具和提示词是否已注册），然后退出
--disable-custom-endpoint		禁止在每个请求中指定自定义验证端点字段
--rest		同时在 /v1 提供 REST API（仅限 HTTP 模式）

---

REST API

对于不使用 MCP 的客户端，HTTP 服务还可以提供纯 REST API——使用 --rest 显式启用，并在同一端口挂载到 /v1。返回的数据与 CLI 和 MCP 相同。

lqt mcp --http :8080 --rest

**身份验证：**使用 Loqate API 密钥作为 bearer token——Authorization: Bearer <LOQATE_API_KEY>（或在请求正文中使用 key）。

方法	路径	描述
POST	/v1/verify/address	验证地址（支持 detect_country、suggest、suggestion_id）
POST	/v1/verify/email	验证电子邮件
POST	/v1/verify/phone	验证电话号码
POST	/v1/verify/contact	验证任意组合，并给出总体建议（支持 detect_country、suggest）
GET	/v1/address/{id}	将建议 ID 解析为清理后的地址（会消耗额度）
GET	/v1/policies	列出决策策略
GET	/v1/policies/{name}	显示单项策略
GET	/v1/openapi.json	OpenAPI 3.1 规范
GET	/v1/docs	交互式 API 参考

建议结果（accept / review / reject）始终以 HTTP 200 返回，决策包含在响应正文中。错误使用标准状态码：400 表示输入无效，401 表示密钥缺失或无效，429 表示请求过多，502 表示上游错误。

curl -s -X POST https://your-host/v1/verify/address \
  -H "Authorization: Bearer $LOQATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"address":"125 Summer St, Boston, MA 02110, US","policy":"standard"}'

# Ask for alternatives when the address does not clear the policy
curl -s -X POST https://your-host/v1/verify/address \
  -H "Authorization: Bearer $LOQATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"address":"10 downin st london","country":"GB","suggest":true,"suggest_limit":5}'

完整的请求/响应架构记录在 /v1/openapi.json 的 OpenAPI 规范中（可在 /v1/docs 浏览）。

---

解释结果

每次地址验证都会返回详细信息，解释评分依据，但不会改变评分：

字段	说明
matchscore	0-100，返回的地址与您提交的地址有多相似。此字段已单独提供，因此您无需从 avc 中解析。
coverage_level + coverage_level_label	该国家 Loqate 验证级别的上限，以数字和名称表示：5 delivery_point、4 premise、3 street、2 locality。标签使用与 match_level 相同的术语，因此两者相同时，表示地址匹配精度已达到该国家数据所允许的上限。
coverage_boost	因该国家的数据覆盖范围低于门牌级别而应用的级别调整值。这个数字解释了为什么在覆盖范围较低的国家，街道级匹配仍然可以获得高分。
changes	Loqate 修改了哪些内容，以文字说明。需主动选择启用——见下文。

要获取 changes，请让 Loqate 返回各字段的状态码：

lqt verify -a "125 Summer St, Boston, MA 02110, US" \
  --option ServerOptions.FieldStatus=true -o json

"changes": [
  { "field": "country_name",            "change": "added",       "value": "United States", "code": "5" },
  { "field": "postal_code",             "change": "reformatted", "value": "02110-1634",    "code": "2" },
  { "field": "postal_code_secondary",   "change": "added",       "value": "1634",          "code": "5" },
  { "field": "sub_administrative_area", "change": "added",       "value": "Suffolk",       "code": "5" }
]

该地址没有任何问题；有三项内容被添加（ZIP+4、县、国家名称），邮政编码也经过了格式整理。Loqate 已验证但未修改的字段不会列出，因此列表较短表示地址无误。

change 的值为 added、corrected、reformatted 或 unrecognised。code 是 Loqate 原始状态码，会予以保留，以避免分类造成信息损失——这些代码由 Loqate 定义，详见docs.loqate.com/report-codes/fieldstatus。

未提供 changes 表示您没有请求状态码。空数组表示您已请求，但没有任何内容发生变化。此选项还会在 fields 中为每个组成字段添加一个 <field>_status 键，因为该透传字段会返回 Loqate 发送的所有内容。

此详细信息会出现在每次地址验证结果中——包括单条、批量（每行）、MCP 和 REST——因为这四种方式都经过同一个结果构建器。

策略

策略用于控制接受、审核或拒绝哪些结果。每次验证都会应用一个策略——没有硬编码的阈值。

策略	地址置信度	匹配级别	邮件置信度	是否需要电话	建议阈值	用途
strict	0.90	premise	0.85	是	0.90	KYC、防欺诈、受监管场景
shipping	0.85	street	0.50	否	0.85	实物配送、电商
standard	0.55	street	0.45	否	0.85	通用验证（默认）
permissive	0.30	locality	0.30	否	0.70	潜在客户信息收集、销售漏斗前期

建议阈值不是接受阈值——它不会改变接受、审核或拒绝的结果。当置信度低于该值时，即使地址已被接受，--suggest 也会查找替代选项。参见地址建议。自定义策略可以设置自己的值，而 recommend_policy MCP 工具会根据您描述的用途提出策略建议。

自定义策略

创建一个 JSON 文件：

{
  "name": "my-custom-policy",
  "description": "Tuned for my use case",
  "address": {
    "min_confidence": 0.65,
    "min_match_level": "street",
    "reject_verification_status": ["U", "R"]
  },
  "email": {
    "min_confidence": 0.50,
    "allow_catch_all": true,
    "reject_disposable": true
  },
  "phone": {
    "min_confidence": 0.40,
    "required": false
  }
}

lqt policy validate my-policy.json    # Validate first
lqt verify -a "..." --policy-file my-policy.json

---

批量处理

批量端点（每次最多 100 条记录）

lqt batch 一次调用即可验证最多 100 条记录——与 verify_*_batch MCP 工具和 /v1/verify/*/batch REST 端点的功能相同。 每行输入一条记录，可从文件或标准输入读取：

lqt batch address --file addresses.txt --country GB
lqt batch email   --file emails.txt --policy strict
lqt batch phone   --file phones.txt --country GB -o table
lqt batch contact --file contacts.json
cat emails.txt | lqt batch email

contact 是按行输入一条记录这一规则的例外：联系人包含多个字段，因此它会读取 JSON 数组——其结构与 MCP 工具和 REST 端点接收的格式相同。每个联系人可以包含地址、邮件和电话中的任意组合，并根据已验证的字段给出总体建议。这三种类型会并行处理，因此完整批次的处理速度由邮件验证决定。

结果按提交顺序返回，每条结果都带有输入的 index，因此可以按索引对应回原始行，无需依赖顺序。一条错误记录只会导致该记录失败——它会携带 error，其余记录仍会正常验证——汇总信息会报告 count、succeeded 和 failed。 退出代码反映的是整个批次，而非任何单条记录：0 表示全部验证通过，1 表示部分失败，2 表示没有任何记录成功，3 表示请求未运行。

批次记录使用与单次验证相同的字段。 所有 38 个结构化输入——premise、thoroughfare、organization、sub_building、address2–address8 和 delivery_address 行，以及收件人字段（contact、function、department、forename、surname、middle_name、full_name、id）——都可由 verify_address_batch、verify_contact_batch 及其 REST 等效接口按记录接收，并在 OpenAPI 文档中统一列为 AddressComponents。收件人字段指明配送对象，而非配送地点；这些字段会原样传递给 Loqate，不影响判定。唯一未包含的是批量处理时没有意义的字段：建议字段，以及适用于整个批次的请求级设置（key、policy、options、detect_country）。lqt batch address 每行读取一个自由格式地址；若要从文件发送结构化列，请使用 lqt verify --batch。

有三点值得了解：

• 发送前会按国家/地区对地址分组，这是 Loqate 的建议。因此，上游调用次数等于批次中的不同国家/地区数量，而不是记录数。
• 电子邮件批量验证返回的详细信息少于单次验证：不包含 risk、is_complainer_or_fraud_risk 和 reason。接受／审核／拒绝建议以及一次性邮箱标记则完全相同。
• 上游没有电话批量验证端点，因此号码会在进程级限流下并发检查。以 100 条记录测得：地址约 3 秒，电话约 2.6 秒，电子邮件约 7 秒。电子邮件是三者中最慢的，因为它会探测邮件服务器；电话虽没有批量端点，但速度比预想的快。

不含国家/地区的记录。 未指定国家/地区的地址验证效果较差——同一个波士顿地址，不指定国家/地区时评分为 0.03，指定后为 0.95——因此，如果既未提供 --country 也未提供 --detect-country，lqt batch address 会发出警告。使用 --detect-country 时，会根据每条记录的地址文本猜测国家/地区，并在该记录的结果中标记这一猜测。检测会在分组前运行，因此，即使批次跨越多个国家/地区，发送的每个分组也会使用各自的默认值，而不是所有记录都使用一个错误的默认值。

批量处理不提供建议，原因与 --batch 不提供建议相同。 托管服务上的速率限制。 批量端点按记录计费，而非按请求计费：一个 100 条记录的批次会占用每位调用者预算中的 100 条，因为这也是上游的计费方式。默认速率为每秒 100 条记录，突发额度为 600，因此连续运行两个完整的联系人批次后，后续批次会受到节流。如果批次需要等待超过 --record-max-wait（2 秒），服务会以 429 拒绝请求并提供重试提示，而不是让连接保持打开。可使用 --record-rate、--record-burst 和 --record-max-wait 调整，或将 --record-rate 0 设为禁用。突发额度必须至少为 300，否则服务会拒绝启动：联系人按验证字段计费，因此一个完整的联系人批次会消耗 300 条记录的额度，更小的突发额度无法接受这样的批次。CLI 不受速率限制。

对于超过 100 条记录的文件，或带有命名列的分隔符文件，请使用 lqt verify --batch <file>，它会将任意大小的文件分成每块 100 条记录进行处理。

使用 verify --batch 处理大型文件

处理包含地址、电子邮件和电话列的文件。支持逗号、制表符和竖线分隔的输入。

verify --batch 可读取任意大小的文件，并通过与 lqt batch 相同的批处理端点发送文件内容——每次调用最多处理 100 条记录，按国家分组，并分块流式处理，因此内存占用不会随文件增大。以前每行都会发送一个请求进行验证；包含 10,000 行的文件需要进行 10,000 次顺序往返请求。

这会带来以下三点影响，这些影响都不会显示在结果中：

• 多行记录一起发送。 上游调用的成本是每个 100 条记录的分块中，每个不同国家调用一次，而不是每行调用一次。
• 一个分块就是一个事务。 一起发送的记录共享同一个 pca-source 会话 ID，和其他所有批处理入口的行为一致。逐行关联是每行单独发送一个请求时才有的特性，任何批处理端点都无法提供。
• 电子邮件返回的详情较少，与 lqt batch email 完全相同：由于批量电子邮件端点不会返回 risk、is_complainer_or_fraud_risk 和 reason，这些字段不会包含在结果中。接受／审核／拒绝建议的计算方式相同。

文件必须至少包含一列地址，或一列电子邮件或电话。单行出错只会导致该行失败；如果整个分块在上游处理失败，文件的其余部分仍会继续处理。

# CSV (auto-detected)
lqt verify --batch addresses.csv --policy shipping -o json > results.json

# Tab-delimited
lqt verify --batch addresses.tsv -o json

# Pipe-delimited
lqt verify --batch addresses.txt --delimiter pipe -o json

# From stdin
cat addresses.csv | lqt verify --batch - --policy standard

# With summary statistics
lqt verify --batch addresses.csv --summary

Windows（PowerShell）：

.\lqt.exe verify --batch addresses.csv --policy shipping -o json > results.json
Get-Content addresses.csv | .\lqt.exe verify --batch - --policy standard

分隔符

根据首行自动检测。使用 --delimiter 显式指定：

值	别名	说明
comma	csv	逗号分隔（默认）
tab	tsv	制表符分隔
pipe		竖线分隔

支持的列

可使用单个 address 列、结构化字段，或同时使用两者。所有列名均不区分大小写。Loqate International Batch Cleanse API 中的所有字段均受支持。

地址行：

字段	可接受的列名
地址（第 1 行）	address、address1、street、address_line_1
地址行 2-8	address2-address8、address_line_2-address_line_8
配送地址	deliveryaddress、delivery_address
配送地址行 1-8	deliveryaddress1-deliveryaddress8、delivery_address_1-delivery_address_8

地理信息：

字段	可接受的列名
城市	city、locality、town
州／省	state、admin_area、province、region、administrative_area
县	county、sub_admin_area、sub_administrative_area
邮政编码	postcode、postal_code、zip、zipcode
国家／地区	country、country_code

街道／建筑物／房屋：

字段	可接受的列名
街道名称	thoroughfare、street_name
建筑物	building、building_name
门牌号	premise、house_number、building_number
公寓／套房	sub_building、apartment、suite、unit、flat

机构／邮政：

字段	可接受的列名
机构	organization、organisation、company、company_name
邮政信箱	post_box、postbox、po_box、pobox

联系人／个人：

字段	可接受的列名
名	forename、first_name
姓	surname、last_name
全名	full_name、name

非地址字段：

字段	可接受的列名
电子邮件	email、email_address
电话	phone、telephone、phone_number、mobile

CSV 示例

address,email,phone,country
"125 Summer St, Boston, MA 02110",[email protected],+16175551234,US
"10 Downing St, London",[email protected],+442071234567,GB

---

MCP 集成

lqt mcp 命令可通过 Model Context Protocol 将 LQT 作为工具提供给 AI Agent。连接 MCP 服务还会提供内置的用法指南提示词，指导 AI 如何有效使用这些工具。

Claude Code / Cursor

添加到项目的 .mcp.json：

{
  "mcpServers": {
    "loqate": {
      "command": "lqt",
      "args": ["mcp"],
      "env": {
        "LOQATE_API_KEY": "your-key-here",
        "ANTHROPIC_API_KEY": "your-key-here"
      }
    }
  }
}

Claude Desktop

添加到 Claude Desktop 的 MCP 设置中：

{
  "mcpServers": {
    "lqt": {
      "command": "/usr/local/bin/lqt",
      "args": ["mcp"],
      "env": {
        "LOQATE_API_KEY": "your-key-here",
        "ANTHROPIC_API_KEY": "your-key-here"
      }
    }
  }
}

GBG 托管端点（推荐）

通过 MCP 使用 Loqate 的最快方式是使用 GBG 托管端点——无需安装，也无需基础设施。将任意 MCP 客户端指向：

https://reach.prod.fabric.gbgplatforms.com/mcp

Claude Code / Cursor / 任意 MCP 客户端——.mcp.json：

{
  "mcpServers": {
    "loqate": {
      "url": "https://reach.prod.fabric.gbgplatforms.com/mcp"
    }
  }
}

重启客户端，然后让它“验证 125 Summer St, Boston, MA 02110, US”。它会发现可用工具、调用这些工具，并解释结果。

使用 Loqate API 密钥进行身份验证——任选一种方式：

1. 每次调用时传入——在工具参数中传入 key（{"key": "YOUR-KEY", "address": "..."}）。
2. 整个连接范围内生效——在 HTTP 连接上设置 Authorization: Bearer <YOUR-LOQATE-KEY>。这会应用于每次工具调用。
3. 通过带外方式传入（仅限 Claude）——在组织／项目／用户指令中添加 <loqate_api_key>YOUR-KEY</loqate_api_key>；模型会自动将其作为 key 注入。

如果三种方式都未提供，服务端会返回 NO_API_KEY 错误。Bearer 标头仅用于提供标准 Loqate 密钥；自定义地址验证端点所用的 verify_key 需单独设置。

在终端中进行基本检查（无需客户端）：

# List tools (no auth required)
curl -s -X POST https://reach.prod.fabric.gbgplatforms.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Verify an address (Bearer auth)
curl -s -X POST https://reach.prod.fabric.gbgplatforms.com/mcp \
  -H 'Authorization: Bearer YOUR-LOQATE-KEY' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"verify_address","arguments":{"address":"125 Summer St, Boston, MA 02110, US"}}}'

托管部署出于安全考虑会禁用自定义验证端点。如果收到 CUSTOM_ENDPOINT_DISABLED 错误，请从工具参数中移除 verify_url 和 verify_key。

GBG 托管 REST 端点

更倾向于使用纯 REST？同一托管服务还提供 REST API，无需 MCP 客户端。使用 Loqate API 密钥作为 bearer 令牌进行身份验证。

# Verify an address
curl -s -X POST https://reach.prod.fabric.gbgplatforms.com/v1/verify/address \
  -H 'Authorization: Bearer YOUR-LOQATE-KEY' \
  -H 'Content-Type: application/json' \
  -d '{"address":"125 Summer St, Boston, MA 02110, US","policy":"standard"}'

# Browse the interactive API reference (no key required)
open https://reach.prod.fabric.gbgplatforms.com/v1/docs

OpenAPI 规范（/v1/openapi.json）和参考页面（/v1/docs）无需身份验证，因此即使尚未获取密钥，也可以探索完整 API。

远程 HTTP（可自托管）

如果你更愿意自行运行服务端，可以将 lqt mcp --http 部署为服务：

{
  "mcpServers": {
    "loqate": {
      "url": "https://lqt.your-company.com/mcp"
    }
  }
}

同样适用三级密钥解析顺序（请求体中的 key → Authorization: Bearer → 服务端环境变量 LOQATE_API_KEY）。

可用工具

stdio 模式下有 10 个工具，HTTP 模式下有 7 个工具（标记为仅限 stdio 模式的工具无法通过 HTTP 使用）。

工具	描述
verify_address	验证地址并提供置信度评分和建议（支持 detect_country、suggest、suggestion_id）
verify_email	验证电子邮件并提供风险等级和建议
verify_phone	验证电话号码并提供类型／运营商信息和建议
verify_contact	一并验证所有字段并给出总体建议（支持 detect_country、suggest、suggestion_id）
retrieve_address	根据建议 ID 获取清理后的地址（会消耗一个额度；不属于验证）
parse_address	通过 Claude 解析并规范化地址（仅限 stdio 模式）
list_policies	列出可用的决策策略
show_policy	显示特定策略的详细信息
set_policy	注册自定义策略（仅限 stdio 模式）
recommend_policy	根据使用场景获取推荐策略，包括其建议置信度下限（仅限 stdio 模式）

---

退出代码

适用于脚本和 CI/CD：

代码	含义
0	ACCEPT — 所有字段均通过验证
1	REVIEW — 建议人工审核
2	REJECT — 验证失败
3	ERROR — 缺少密钥、输入无效或 API 调用失败

macOS / Linux：

lqt verify -a "125 Summer St, Boston, MA 02110, US" --policy shipping -o json
case $? in
  0) echo "Ship it" ;;
  1) echo "Queue for review" ;;
  2) echo "Bad address" ;;
  3) echo "Something broke" ;;
esac

Windows（PowerShell）：

.\lqt.exe verify -a "125 Summer St, Boston, MA 02110, US" --policy shipping -o json
switch ($LASTEXITCODE) {
  0 { Write-Host "Ship it" }
  1 { Write-Host "Queue for review" }
  2 { Write-Host "Bad address" }
  3 { Write-Host "Something broke" }
}

---

API 密钥

Loqate API 密钥（用于 verify）

macOS / Linux：

# Environment variable
export LOQATE_API_KEY=your-key-here

# Key file (add to .gitignore)
echo "your-key-here" > .loqate-key

# Per-command flag
lqt verify -a "..." --key your-key-here

Windows（PowerShell）：

# Current session
$env:LOQATE_API_KEY="your-key-here"

# Persistent (survives restarts)
[System.Environment]::SetEnvironmentVariable("LOQATE_API_KEY", "your-key-here", "User")

# Per-command flag
.\lqt.exe verify -a "..." --key your-key-here

Anthropic API 密钥（用于 parse）

macOS / Linux：

export ANTHROPIC_API_KEY=your-key-here

Windows（PowerShell）：

$env:ANTHROPIC_API_KEY="your-key-here"

**解析顺序：**标志 > 环境变量 > 密钥文件

自定义验证端点（可选）

如果您需要通过其他端点进行地址验证（例如，本地部署或由合作伙伴托管的 Loqate 实例）：

macOS / Linux：

# Environment variables
export LOQATE_VERIFY_URL=https://custom-verify.example.com/v1/batch
export LOQATE_VERIFY_KEY=your-custom-key

# Or use flags (override env vars)
lqt verify -a "..." --verify-url https://custom-verify.example.com/v1/batch --verify-key your-custom-key

Windows（PowerShell）：

$env:LOQATE_VERIFY_URL="https://custom-verify.example.com/v1/batch"
$env:LOQATE_VERIFY_KEY="your-custom-key"

**解析顺序：**标志 > 环境变量 > 默认 Loqate 端点

设置 --verify-key 后，仅验证地址时无需使用标准 --key / LOQATE_API_KEY。如果您还要验证电子邮件（-e）或电话号码（-p），仍需为这些验证提供标准密钥。

这些标志仅影响地址验证。电子邮件和电话号码始终使用标准 Loqate 端点。

在 MCP 模式下，客户端可以在 verify_address 和 verify_contact 工具输入中按请求传入 verify_url 和 verify_key。

---

支持

• 错误报告和功能请求 — 提交问题
• 安全漏洞 — 请发送电子邮件至 [email protected]，不要公开提交问题
• 一般问题 — 发起讨论或提交问题

报告错误时，请提供：

• lqt 版本（lqt --version）
• 操作系统和架构（例如，macOS ARM64、Linux x86_64）
• 您运行的命令（请隐去任何 API 密钥）
• 预期行为与实际行为

---

许可证

专有 — 请参阅 LICENSE。使用需要有效的 Loqate 订阅。

---

由 GBG 构建。