POSTPublicshipping-address-parse

Shipping Address Parser

Intelligently extract Chinese shipping recipient details from unstructured text: name, phone number, ID number, zip code, province/city/district, and detailed address. Supports single and batch processing (up to 200 entries/request) with deduplication by phone number or name.

Documentation

接口简介

本接口基于自然语言处理技术，能够从非结构化的混合文本中精准提取中国快递收件关键信息。核心能力包括自动识别并分离姓名、手机号码、身份证号码（如有）、邮政编码以及标准的省/市/区/街道详细地址。

适用场景

电商订单清洗：自动规范化用户手动输入的模糊地址，减少发货错误率。
CRM 数据治理：批量整理历史客户资料，补全缺失的行政区划字段。
物流系统集成：在下单环节实时校验并结构化地址数据，提升打单效率。

请求与返回说明

请求方式：POST /v1/shipping-address-parse
输入要点：
addresses：字符串数组，支持单次提交最多 200 条地址文本。
dedup：可选去重策略，支持按 phone（手机号）或 name（姓名）进行重复项过滤。
返回结果：
返回标准化的 JSON 结构，包含解析后的 name、mobile、province、city、region、street 等字段。
提供 count（有效数量）、originalCount（原始数量）及 removed（去重移除数量）统计信息。

接入建议

批量处理：建议将待处理数据聚合后批量调用（≤200 条/次），以降低网络开销并提高吞吐量。
去重策略：若业务场景对唯一联系人敏感，请启用 dedup 参数，避免因同一用户多条地址记录导致的数据冗余。
异常处理：请检查返回中的 code 状态码，对于解析失败的字段（如无法识别的邮编），系统会返回 null，前端需做好空值兼容。

Integration Examples

Includes ready-to-use Shell, Python, Go, Java, and PHP examples for direct integration.

Request Example

{
  "addresses": [
    "张三 13800138000 广东省深圳市南山区科技园路 1 号 518000",
    "李四 13900139000 北京市朝阳区建国路 88 号"
  ],
  "dedup": "phone"
}

Response Example

{
  "code": "SUCCESS",
  "message": "success",
  "data": {
    "count": 2,
    "originalCount": 2,
    "removed": 0,
    "items": [
      {
        "name": "张三",
        "mobile": "13800138000",
        "idn": null,
        "postcode": "518000",
        "province": "广东省",
        "city": "深圳市",
        "region": "南山区",
        "street": "科技园路1号",
        "original": "张三 13800138000 广东省深圳市南山区科技园路 1 号 518000"
      },
      {
        "name": "李四",
        "mobile": "13900139000",
        "idn": null,
        "postcode": null,
        "province": "北京市",
        "city": "北京市",
        "region": "朝阳区",
        "street": "建国路88号",
        "original": "李四 13900139000 北京市朝阳区建国路 88 号"
      }
    ]
  }
}

Request Fields

The fields below are derived from example JSON for integration reference only.

Path	Type	Sample
addresses	array	"张三 13800138000 广东省深圳市南山区科技园路 1 号 518000"
addresses[]	string	张三 13800138000 广东省深圳市南山区科技园路 1 号 518000
dedup	string	phone

Response Fields

The fields below are derived from example JSON for integration reference only.

Path	Type	Sample
code	string	SUCCESS
message	string	success
data	object	{...}
data.count	number	2
data.originalCount	number	2
data.removed	number	0
data.items	array	{"name":"张三","mobile":"13800138000","idn":null,"postcode":"518000","province":"广东省","city":"深圳市","region":"南山区","street":"科技园路1号","original":"张三 13800138000 广东省深圳市南山区科技园路 1 号 518000"}

curl --request POST \ --url 'https://openapi.toolkk.com/v1/shipping-address-parse' \ --header 'Content-Type: application/json' \ --header 'X-API-Key: YOUR_API_KEY' \ --data '{\n "addresses": [\n "张三 13800138000 广东省深圳市南山区科技园路 1 号 518000",\n "李四 13900139000 北京市朝阳区建国路 88 号"\n ],\n "dedup": "phone"\n}'

import os import requests url = "https://openapi.toolkk.com/v1/shipping-address-parse" payload = { "addresses": [ "张三 13800138000 广东省深圳市南山区科技园路 1 号 518000", "李四 13900139000 北京市朝阳区建国路 88 号" ], "dedup": "phone" } headers = { "Content-Type": "application/json", "X-API-Key": os.getenv("TOOLKK_API_KEY", "YOUR_API_KEY"), } response = requests.request("POST", url, headers=headers, json=payload, timeout=30) response.raise_for_status() print(response.json())

package main import ( "bytes" "fmt" "io" "net/http" ) func main() { endpoint := "https://openapi.toolkk.com/v1/shipping-address-parse" payload := []byte("{\n \"addresses\": [\n \"张三 13800138000 广东省深圳市南山区科技园路 1 号 518000\",\n \"李四 13900139000 北京市朝阳区建国路 88 号\"\n ],\n \"dedup\": \"phone\"\n}") req, err := http.NewRequest("POST", endpoint, bytes.NewBuffer(payload)) if err != nil { panic(err) } req.Header.Set("Content-Type", "application/json") req.Header.Set("X-API-Key", "YOUR_API_KEY") resp, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer resp.Body.Close() body, err := io.ReadAll(resp.Body) if err != nil { panic(err) } fmt.Println(string(body)) }

import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; public class ToolkkExample { public static void main(String[] args) throws Exception { String payload = "{\n \"addresses\": [\n \"张三 13800138000 广东省深圳市南山区科技园路 1 号 518000\",\n \"李四 13900139000 北京市朝阳区建国路 88 号\"\n ],\n \"dedup\": \"phone\"\n}"; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://openapi.toolkk.com/v1/shipping-address-parse")) .method("POST", HttpRequest.BodyPublishers.ofString(payload)) .header("Content-Type", "application/json") .header("X-API-Key", "YOUR_API_KEY") .build(); HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body()); } }

<?php $endpoint = 'https://openapi.toolkk.com/v1/shipping-address-parse'; $payload = "{\n \"addresses\": [\n \"张三 13800138000 广东省深圳市南山区科技园路 1 号 518000\",\n \"李四 13900139000 北京市朝阳区建国路 88 号\"\n ],\n \"dedup\": \"phone\"\n}"; $ch = curl_init($endpoint); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'Content-Type: application/json', 'X-API-Key: YOUR_API_KEY', ], CURLOPT_POSTFIELDS => $payload, ]); $response = curl_exec($ch); if ($response === false) { throw new RuntimeException(curl_error($ch)); } curl_close($ch); echo $response;

Shipping Address Parser

Documentation

接口简介

适用场景

请求与返回说明

接入建议

Integration Examples

Request Example

Response Example

Request Fields

Response Fields

Shell Example

Python Example

Go Example

Java Example

PHP Example

Try it online