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

API Introduction

This API, based on natural language processing technology, can accurately extract key Chinese express delivery recipient information from unstructured mixed text. Core capabilities include automatically identifying and separating name, mobile number, ID card number (if any), postal code, and standard province/city/district/street detailed address.

Use Cases

E-commerce Order Cleaning: Automatically standardize vague addresses manually entered by users, reducing shipping error rates.
CRM Data Governance: Batch organize historical customer data and complete missing administrative division fields.
Logistics System Integration: Real-time validation and structuring of address data during the order placement process to improve labeling efficiency.

Request and Response Description

Request Method: POST /v1/shipping-address-parse
Input Highlights:
addresses: String array, supports submitting up to 200 address texts per request.
dedup: Optional deduplication strategy, supports filtering duplicate items by phone (mobile number) or name.
Return Results:
Returns a standardized JSON structure, including parsed name, mobile, province, city, region, street, and other fields.
Provides statistical information for count (valid quantity), originalCount (original quantity), and (deduplicated quantity).

Integration Suggestions

Batch Processing: It is recommended to aggregate data and call in batches (≤200 entries/time) to reduce network overhead and improve throughput.
Deduplication Strategy: If the business scenario is sensitive to unique contacts, please enable the dedup parameter to avoid data redundancy caused by multiple address records for the same user.
Error Handling: Please check the code status in the return. For fields that fail to parse (e.g., unrecognized postal code), the system will return null. The frontend should handle null values gracefully.

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

API Introduction

Use Cases

Request and Response Description

Integration Suggestions

Integration Examples

Request Example

Response Example

Request Fields

Response Fields

Shell Example

Python Example

Go Example

Java Example

PHP Example

Try it online