邮编查询

把邮编解析为地点（名称、行政区划、坐标）；未知邮编返回 found 为 false。法国一个邮编可能对应多个市镇。

接口	POST /v1/postal-code-lookups
所需权限	postal_code:lookup
MCP 工具	postal_code
计量单位	places

计量单位出现在 execution.usage.units 中，用于对账和计费。

请求字段

字段	类型	必填	说明
invocation_id	string	是	调用方（市场）生成的调用 ID：同一个 ID 在同一操作上只执行一次，用同一 ID 重试会被拒绝而不会重复计费。1–128 个字符，可用 A-Z a-z 0-9 . _ : -。
provider	string	是	处理本次请求的数据源，按下方数据源表的覆盖范围选择。 可选值：geo-api-gouv
country	string	是	ISO 3166-1 二位国家代码：postcodes-io 用 GB，geo-api-gouv 用 FR。
postal_code	string	是	邮编，2–10 个字符，可用 A-Z、0-9、空格或连字符，例如 SW1A 1AA、75001。

数据源

数据源	区域	说明	限制
geo-api-gouv	FR	法国政府地理 API，覆盖 FR	timeout_seconds: 30

示例

curl

curl -sS https://services.zgi.im/v1/postal-code-lookups \
  -H "Authorization: Bearer $ZGI_SERVICES_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"invocation_id": "docs-1791778521-postal_code", "provider": "geo-api-gouv", "country": "FR", "postal_code": "75001"}'

HTTP

POST /v1/postal-code-lookups HTTP/1.1
Host: services.zgi.im
Authorization: Bearer <token>
Content-Type: application/json

{
  "invocation_id": "docs-1791778521-postal_code",
  "provider": "geo-api-gouv",
  "country": "FR",
  "postal_code": "75001"
}

MCP

通过 MCP 调用时，工具参数与 HTTP 请求体完全相同。

request.json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "postal_code",
    "arguments": {
      "invocation_id": "docs-1791778521-postal_code",
      "provider": "geo-api-gouv",
      "country": "FR",
      "postal_code": "75001"
    }
  }
}

curl -sS https://services.zgi.im/v1/mcp \
  -H "Authorization: Bearer $ZGI_SERVICES_TOKEN" \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  -d @request.json

返回

以下为一次真实调用的返回，列表只保留前两项，长文本已截断。

{
  "code": 0,
  "message": "success",
  "data": {
    "execution": {
      "id": "exe_01a12e52b380780ab60ad66705fd849c",
      "invocation_id": "docs-1791778521-postal_code",
      "capability": "postal_code",
      "operation": "postal_code.lookup",
      "provider": "geo-api-gouv",
      "outcome": "succeeded",
      "error_category": null,
      "error_code": null,
      "usage": {
        "provider_requests": 1,
        "units": [
          {
            "name": "places",
            "value": 1,
            "source": "measured"
          }
        ]
      },
      "upstream_ref": null,
      "request_id": "req_5de7a4832ee978d041f03e5f",
      "started_at": "2026-10-12T04:15:34.272524429Z",
      "finished_at": "2026-10-12T04:15:34.952464762Z",
      "duration_ms": 679
    },
    "result": {
      "found": true,
      "places": [
        {
          "postal_code": "75001",
          "place_name": "Paris",
          "admin_area_1": "Île-de-France",
          "admin_area_2": "Paris",
          "latitude": 48.8589,
          "longitude": 2.347,
          "country": "FR"
        }
      ],
      "source": {
        "name": "API Géo (geo.api.gouv.fr): La Poste Base officielle des codes postaux, INSEE Code officiel géographique",
        "license": "Licence Ouverte / Open Licence 2.0",
        "url": "https://api.gouv.fr/les-api/api-geo"
      }
    }
  }
}