適用場(chǎng)景中文地址解析接口的核心能力是傳入一段包含姓名、手機(jī)號(hào)、地址、郵編的混合字符串返回拆分后的結(jié)構(gòu)化字段。在電商訂單處理、快遞面單打印、CRM 客戶資料清洗、辦公地址入庫等場(chǎng)景中人工拆分地址耗時(shí)且容易出錯(cuò)用接口做自動(dòng)化預(yù)處理可以顯著提升效率。典型的輸入形態(tài)包括張三 13812345678 上海市浦東新區(qū)張江鎮(zhèn)科苑路88號(hào) 201203北京市海淀區(qū)中關(guān)村大街1號(hào) 李四 13900001111新疆烏魯木齊市天山區(qū)解放路100號(hào)接口采用純本地正則算法無上游依賴響應(yīng)在毫秒級(jí)。需要說明的是這里的“無上游依賴”指的是服務(wù)端解析過程中不依賴第三方地址庫具體響應(yīng)延遲請(qǐng)以實(shí)際環(huán)境為準(zhǔn)。接口能力邊界在接入前需要明確這個(gè)接口能做什么、不能做什么支持 34 個(gè)省級(jí)行政區(qū)及其簡稱識(shí)別例如“北京”歸一化為“北京市”“新疆”歸一化為“新疆維吾爾自治區(qū)”。支持姓名、手機(jī)、郵編的混合輸入提取但手機(jī)號(hào)和郵編會(huì)做脫敏處理例如響應(yīng)中的phone為138****1234。地址長度限制為 500 字符超出后建議截?cái)嗷蜃銮爸眯ｒ?yàn)。返回字段固定省份、城市、區(qū)縣、街道、詳細(xì)地址、姓名、手機(jī)號(hào)、郵編、原始文本。QPS 限制為 20/s未登錄匿名調(diào)用會(huì)受到更嚴(yán)格的限流具體閾值以文檔為準(zhǔn)。如果業(yè)務(wù)中需要處理非常規(guī)地址如“xx路xx號(hào)xx棟xx室”和“xx村xx組”混合建議先用樣本數(shù)據(jù)做充分測(cè)試確認(rèn)解析結(jié)果符合預(yù)期。請(qǐng)求參數(shù)與鑒權(quán)請(qǐng)求方法與地址請(qǐng)求方法POST請(qǐng)求地址https://v1.apizero.cn/api/address-parse請(qǐng)求頭Content-Type: application/jsonHeader 參數(shù)參數(shù)名是否必須類型說明Authorization否stringBearer sk_live_xxx可選未登錄匿名調(diào)用受更嚴(yán)格限流X-API-Key視文檔而定string部分調(diào)用方式使用該頭部傳遞密鑰請(qǐng)以文檔頁說明為準(zhǔn)素材中的 curl 示例使用了X-API-Key作為鑒權(quán)頭同時(shí)接口文檔也支持Authorization: Bearer sk_live_xxx的方式。建議在代碼中固定一種鑒權(quán)方式將密鑰放到環(huán)境變量中避免硬編碼。請(qǐng)求體字段請(qǐng)求體是一個(gè) JSON 對(duì)象只有一個(gè)必填字段address。字段類型是否必須說明addressstring是中文地址字符串支持姓名/手機(jī)/郵編混合輸入長度 ≤ 500請(qǐng)求體示例{ address: 張三 13812345678 上海市浦東新區(qū)張江鎮(zhèn)科苑路88號(hào) 201203 }如果傳入空字符串或非 string 類型接口會(huì)返回錯(cuò)誤。建議客戶端在發(fā)起請(qǐng)求前先做類型和長度檢查避免無效請(qǐng)求消耗 QPS。使用 curl 接入以下是一個(gè)可直接運(yùn)行的 curl 示例請(qǐng)將$APIZERO_API_KEY替換為你的密鑰curl -sS \ -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d {address: 張三 13812345678 上海市浦東新區(qū)張江鎮(zhèn)科苑路88號(hào) 201203} \ https://v1.apizero.cn/api/address-parse如果你使用Authorization頭可以這樣寫curl -sS \ -X POST \ -H Authorization: Bearer sk_live_xxx \ -H Content-Type: application/json \ -d {address: 新疆烏魯木齊市天山區(qū)解放路100號(hào)} \ https://v1.apizero.cn/api/address-parse注意上面示例中的sk_live_xxx是占位符你需要替換成自己賬號(hào)下的真實(shí)密鑰。生產(chǎn)環(huán)境推薦使用環(huán)境變量export APIZERO_API_KEYsk_live_your_key然后通過$APIZERO_API_KEY引用。響應(yīng)字段解讀成功響應(yīng)的Content-Type為application/json外層結(jié)構(gòu)固定為code、msg、data、request_id。{ code: 0, data: { city: 上海市, detail: 科苑路88號(hào), district: 浦東新區(qū), name: 張三, original: 張三 138****1234 上海市浦東新區(qū)張江鎮(zhèn)科苑路88號(hào) 201203, phone: 138****1234, province: 上海市, street: 張江鎮(zhèn), zipcode: 201203 }, msg: 成功, request_id: kx8n9q2a1b3c4d5e6f7g }data 字段明細(xì)字段類型說明provincestring省份已做歸一化如“上海市”citystring城市如“上海市”districtstring區(qū)縣如“浦東新區(qū)”streetstring街道/鄉(xiāng)鎮(zhèn)如“張江鎮(zhèn)”detailstring剩余詳細(xì)地址如“科苑路88號(hào)”namestring識(shí)別出的姓名phonestring脫敏后的手機(jī)號(hào)zipcodestring郵編originalstring原始字符串手機(jī)號(hào)已脫敏注意original字段中的手機(jī)號(hào)被中間四位替換為****這是接口的脫敏處理。如果你需要原始手機(jī)號(hào)接口不返回請(qǐng)勿將明文手機(jī)號(hào)寫入日志。street字段在輸入沒有明確鄉(xiāng)鎮(zhèn)/街道時(shí)會(huì)返回空字符串或缺失需要根據(jù)實(shí)際響應(yīng)處理。常見錯(cuò)誤排查這里列出幾類常見問題實(shí)際錯(cuò)誤碼與錯(cuò)誤信息請(qǐng)以接口返回為準(zhǔn)。1. 鑒權(quán)失敗現(xiàn)象返回code非 0或 HTTP 狀態(tài)碼為 401/403。排查檢查X-API-Key或Authorization是否正確密鑰是否過期是否在請(qǐng)求頭中正確攜帶。2. 請(qǐng)求體格式錯(cuò)誤現(xiàn)象接口無法解析 JSON返回格式錯(cuò)誤。排查確保Content-Type為application/json請(qǐng)求體是合法的 JSON 對(duì)象字段名address必須存在字符串用雙引號(hào)。3. 地址長度超限現(xiàn)象address長度超過 500 字符。排查在客戶端預(yù)處理超過 500 字符的地址可以先截?cái)嗷虿鸱忠部梢栽跇I(yè)務(wù)層設(shè)置更保守的長度上限比如 200 字符。4. 解析不到姓名或手機(jī)號(hào)現(xiàn)象返回的name或phone為空。排查確認(rèn)輸入的字符串中確實(shí)包含姓名和手機(jī)號(hào)手機(jī)號(hào)必須是 11 位數(shù)字如果隱私要求可以用x或*占位但接口可能無法提取。5. QPS 限流現(xiàn)象短時(shí)間內(nèi)大量請(qǐng)求被拒絕。排查控制調(diào)用頻率不要超過 20/s如果需要更高并發(fā)考慮使用Authorization鑒權(quán)方式若有更高權(quán)益以文檔為準(zhǔn)。工程化注意事項(xiàng)超時(shí)與重試接口是網(wǎng)絡(luò)請(qǐng)求必須設(shè)置合理的超時(shí)時(shí)間。建議連接超時(shí)3 秒讀取超時(shí)5 秒重試策略對(duì)超時(shí)和 5xx 錯(cuò)誤做重試最多重試 2 次并使用指數(shù)退避如 200ms、400ms。日志脫敏original字段包含脫敏后的手機(jī)號(hào)但address請(qǐng)求參數(shù)中的手機(jī)號(hào)是明文。建議請(qǐng)求日志不打印完整address只打印長度或截?cái)嗪蟮那?20 個(gè)字符。響應(yīng)日志中直接使用接口返回的original字段不要拼接請(qǐng)求參數(shù)。數(shù)據(jù)校驗(yàn)與兜底接口返回的province、city等字段不一定完全符合你們系統(tǒng)的字典。建議在入庫前做一次映射校驗(yàn)例如# 示例將接口返回的省份名映射到業(yè)務(wù)字典 province_map { 上海市: 上海, 新疆維吾爾自治區(qū): 新疆, } standard_province province_map.get(data.get(province), data.get(province))如果detail為空可以用streetdetail的邏輯拼接完整地址但要避免重復(fù)拼接。批量處理限制接口一次只能解析一個(gè)地址沒有批量接口。若需要批量清洗建議在本地做并發(fā)控制用線程池或異步隊(duì)列限制并發(fā)數(shù)避免觸發(fā)限流。測(cè)測(cè)試?yán)O(shè)計(jì)建議準(zhǔn)備以下測(cè)試樣本標(biāo)準(zhǔn)帶姓名手機(jī)號(hào)郵編的地址。只有地址沒有手機(jī)號(hào)。省級(jí)簡稱輸入如“北京”“新疆”。地址中夾雜英文或特殊符號(hào)。地址長度接近 500 字符。用這些樣本跑一遍確認(rèn)解析結(jié)果是否符合預(yù)期。如果個(gè)別地址解析錯(cuò)誤可以考慮在前置流程中用正則先清洗一次再調(diào)用接口。參考文檔接口文檔頁https://apizero.cn/aidocs/address-parse原始 Markdown 文檔https://apizero.cn/aidocs/address-parse/raw.md