簡介這份工具包基于高德地圖API實現(xiàn)批量地理位置距離計算主要面向物流行業(yè)與需要處理大量地址數(shù)據(jù)的Java開發(fā)者。功能覆蓋CSV批量導(dǎo)入導(dǎo)出、距離矩陣計算、多線程并發(fā)處理與結(jié)果可視化展示可有效縮短成百上千個坐標點的處理時間輔助配送路線優(yōu)化與網(wǎng)點覆蓋分析。壓縮包共16個文件、約695KB內(nèi)含4個XML配置、3個Java源碼、3個Class編譯文件、2個Iml工程文件以及docx、txt、md、jar等其中docx與txt提供詳細使用說明README幫助快速理解項目結(jié)構(gòu)。已有178人學(xué)習下載適合具備一定Java基礎(chǔ)的用戶。通過閱讀源碼與文檔可以掌握高德地圖API的地理編碼和距離計算調(diào)用方式學(xué)習多線程任務(wù)拆分、CSV數(shù)據(jù)讀寫及結(jié)果可視化的具體實現(xiàn)為物流調(diào)度等真實場景提供可直接復(fù)用的參考方案。1. 物流場景的批量距離計算為什么高德API能把這個月的工作壓成幾分鐘物流調(diào)度的日常里最磨人的往往不是路線規(guī)劃本身而是先把幾十個網(wǎng)點兩兩之間的距離算出來。一個同城配送項目里50個網(wǎng)點需要算2450對距離人工在高德地圖網(wǎng)頁上一個個點至少半天500個網(wǎng)點就是12萬多對基本不可能手動完成。而這個基于高德地圖API批量地理位置距離計算的高效工具輸入CSV、調(diào)用距離矩陣接口、多線程并發(fā)處理幾分鐘就能把距離矩陣跑完再疊加可視化展示輔助決策。它服務(wù)三類人物流調(diào)度要算網(wǎng)點覆蓋半徑運費結(jié)算要核對里程數(shù)據(jù)分析要拿距離矩陣做聚類分群。不需要GIS背景Python能跑就行。下面按從選型到落地的順序把每一步的參數(shù)、代碼和坑都講清楚。2. 高德API選型與配額設(shè)計距離矩陣API為什么是批量算距的主力2.1 高德API家族里怎么選地理編碼、路徑規(guī)劃與距離矩陣的邊界高德Web服務(wù)API里和距離計算相關(guān)的有三個很多人上來就搞混。第一個是路徑規(guī)劃API它只接受一個起點和一個終點返回一條具體路線的駕車/騎行/步行方案帶紅綠燈等待、收費預(yù)估等信息。它的優(yōu)點是精度高缺點是單次只能算一對批量場景下要循環(huán)調(diào)幾千次既慢又費配額。第二個是地理編碼API它把「北京市朝陽區(qū)望京東路4號」這樣的文字地址轉(zhuǎn)成經(jīng)緯度坐標本身不計算距離但批量地址輸入的第一步就是它。第三個才是主角——距離矩陣API它接受多個起點和多個終點一次請求返回一個二維距離數(shù)組正好對應(yīng)「批量地理位置距離計算」這個標題。選型結(jié)論很直接只要目標是算多對多距離就選距離矩陣API不要用路徑規(guī)劃API硬拼。距離矩陣API底層走的也是高德路網(wǎng)數(shù)據(jù)返回的駕車距離和路徑規(guī)劃是同源的只是它把一堆起點終點打包成矩陣計算結(jié)果返回。如果你拿到的經(jīng)緯度本身就是網(wǎng)點的精確坐標連地理編碼都不用調(diào)直接喂給距離矩陣API就行。只有CSV里存的是文字地址時才需要先走一次地理編碼。2.2 Key申請與配額個人開發(fā)者和企業(yè)認證的差距在哪里高德開放平臺的Key分類型做這種服務(wù)端批量計算必須在控制臺創(chuàng)建一個「Web服務(wù)」類型的Key不能用Web端JS API的Key兩者權(quán)限域完全不同。創(chuàng)建后要把對應(yīng)服務(wù)打開一般默認會開通全部Web服務(wù)API但如果你看到某個接口報錯說服務(wù)未開通第一件事就是回控制臺確認這個Key的「API權(quán)限」勾選了距離測量相關(guān)服務(wù)。配額這塊是高德所有場景里最容易被低估的。個人開發(fā)者Key的日配額通常不大而且不同賬號、不同認證等級差別明顯企業(yè)認證或付費后配額會提升。這個數(shù)字不要憑記憶拍腦袋直接看控制臺「配額管理」頁。另外高德提供一個配額查詢接口每跑一批任務(wù)前查一次余量比等請求失敗再排查要省事得多curl https://restapi.amap.com/v3/account/status?key你的Web服務(wù)Key返回值里能看到當日的配額總額、已用量和剩余量。我一般會在腳本啟動時先調(diào)這個接口做一次「配額體檢」如果剩余量低于本次任務(wù)預(yù)估的請求數(shù)就直接中止免得跑到一半彈一堆配額超限錯誤。2.3 距離矩陣API的請求參數(shù)與返回結(jié)構(gòu)一次調(diào)用能拿到多少對距離距離矩陣API的正式端點是/v3/distance核心參數(shù)如下表參數(shù)含義示例與說明keyWeb服務(wù)Key控制臺獲取注意類型別選錯origins起點坐標列表多個坐標用豎線 destinations終點坐標列表格式同上單次最多100個type距離類型0是直線距離1是駕車路徑距離物流默認用1單次請求最多100個起點乘以100個終點也就是一次能拿回1萬對距離。這個「100×100」的上限是整個工具設(shè)計的錨點如果網(wǎng)點數(shù)是500要拆成5×5共25次請求如果網(wǎng)點數(shù)是2000就要拆成20×20共400次請求。返回結(jié)果是results數(shù)組每一項里帶origin_index、dest_index、distance和duration其中distance單位是米。origin_index和dest_index是0起編號正好和origins、destinations列表里的位置一一對應(yīng)解析時不要自己重新排序。3. 從CSV到可計算的矩陣地址清洗、坐標緩存與請求拆分3.1 CSV輸入格式設(shè)計location_id、坐標與地址列怎么排CSV的字段規(guī)劃直接決定后面腳本寫起來順不順手。我建議最小字段是五列l(wèi)ocation_id、location_name、address、lng、lat。location_id是內(nèi)部主鍵不要用中文名做關(guān)聯(lián)鍵同一個網(wǎng)點在Excel里可能出現(xiàn)「朝陽分倉」和「朝陽分倉庫」兩種寫法但ID是穩(wěn)定的。address填文字地址lng和lat是經(jīng)緯度。一個常見的坑是如果你的數(shù)據(jù)源是其他系統(tǒng)導(dǎo)出的坐標列可能缺失或混著坐標字符串所以代碼里要做空值判斷。下面這段代碼負責讀取CSV并構(gòu)建坐標列表它的輸入是原始CSV輸出是一個標準坐標數(shù)組和一個緩存字典import csv import os def load_locations(csv_path): locations [] with open(csv_path, r, encodingutf-8-sig) as f: reader csv.DictReader(f) for row in reader: loc_id row[location_id].strip() name row[location_name].strip() address row[address].strip() lng row.get(lng, ).strip() lat row.get(lat, ).strip() if lng and lat: try: coord (float(lng), float(lat)) except ValueError: coord None else: coord None locations.append({ id: loc_id, name: name, address: address, coord: coord }) return locations這個函數(shù)有兩個細節(jié)值得注意。第一encodingutf-8-sig是為了兼容Excel導(dǎo)出的帶BOM的CSV不寫這個參數(shù)第一列的列名很可能變成\ufefflocation_id后續(xù)所有按列名的取值都會靜默失敗。第二坐標列在CSV里可能是空字符串、None或非法數(shù)值這里統(tǒng)一捕獲ValueError并把coord置為None后面再走地理編碼補全比在循環(huán)外部做一堆if not coord判斷要干凈。3.2 地址清洗與坐標緩存同樣的地址不調(diào)第二次API批量地址輸入的第二道工序是地址清洗和地理編碼。清洗的常見規(guī)則包括去首尾空格、把全角空格和常見干擾字符歸一化、給短地址補城市前綴。例如「上地十街10號」這種缺省城市的地址如果不補前綴高德地理編碼返回的坐標可能落在全國任意一個同名地點這是批量地址輸入最典型的翻車點。地理編碼接口的city參數(shù)就是干這個的要么傳網(wǎng)點所在城市要么先通過地址庫補齊城市再調(diào)用。接下來是坐標緩存策略。地理編碼按次計費一套50個地址的CSV可能只有兩三個地址沒有坐標需要補但如果這套CSV每周跑一次每次都重復(fù)調(diào)地理編碼就太浪費了。緩存只需要一個字典加一個JSON文件import json import requests GEOCODE_URL https://restapi.amap.com/v3/geocode/geo def geocode_address(address, city, key): params {address: address, city: city, key: key} resp requests.get(GEOCODE_URL, paramsparams, timeout5) data resp.json() if data[status] 1 and data[geocodes]: location data[geocodes][0][location] lng, lat location.split(,) return float(lng), float(lat) return None def load_cache(cache_pathgeo_cache.json): if os.path.exists(cache_path): with open(cache_path, r, encodingutf-8) as f: return json.load(f) return {} def save_cache(cache, cache_pathgeo_cache.json): with open(cache_path, w, encodingutf-8) as f: json.dump(cache, f, ensure_asciiFalse, indent2)使用方式是把city | address作為緩存的key命中就直接讀坐標沒命中才調(diào)API并把結(jié)果寫回緩存。注意緩存文件不要和CSV放在同一個目錄避免Excel誤打開JSON文件導(dǎo)致編碼損壞。一個更穩(wěn)妥的做法是SQLite但JSON在幾十萬量級以下完全夠用物流網(wǎng)點很少有超過這個規(guī)模的。3.3 把大矩陣拆成100×100的請求塊組合邏輯與去重拿到所有網(wǎng)點的坐標列表后就面臨矩陣拆分問題。前面提到距離矩陣API單次最多100個起點、100個終點因此任意規(guī)模的矩陣都要按100切片做笛卡爾組合。假設(shè)網(wǎng)點數(shù)n250切片數(shù)是ceil(250/100)3分別命名為A0、A1、A2那請求組合就是A0×A0、A0×A1、A0×A2以此類推共9個請求返回9萬對距離而實際需要的距離對是250×2506.25萬說明這里存在多余的請求——因為A0×A1和A1×A0在對稱矩陣里是重復(fù)的。有沒有辦法省掉一半請求當然有。如果用戶只是要兩兩距離做聚類或覆蓋分析只需要上三角矩陣也就是只發(fā)i j的切片組合。但如果你做的是運費結(jié)算起點和終點有方向性例如從倉庫A到客戶B和從客戶B到倉庫A可能因為單行線、限行產(chǎn)生不同距離那就要保留完整矩陣。我在工具里加了一個symmetric開關(guān)默認開生成請求時只保留i j的組合能省將近一半的API調(diào)用量。下面是拆請求的代碼def build_distance_requests(coords, chunk_size100, symmetricTrue): chunks [coords[i:ichunk_size] for i in range(0, len(coords), chunk_size)] requests [] for ci, origin_chunk in enumerate(chunks): start ci if symmetric else 0 for cj, dest_chunk in enumerate(chunks[start:], startstart): requests.append({ origins: origin_chunk, destinations: dest_chunk, origin_offset: ci * chunk_size, dest_offset: cj * chunk_size, }) return requests拆出來的每個請求里都帶origin_offset和dest_offset作用是后續(xù)把返回的距離填入大矩陣時能把小塊坐標映射回全局坐標索引。這個偏移量如果不記錄解析響應(yīng)時會對不上號尤其是切片大小不是整除數(shù)的時候最后一個塊長度不足100偏移量容易算錯。4. 多線程并發(fā)調(diào)用線程池骨架、限流退避與參數(shù)取舍4.1 串行調(diào)用到底慢在哪先算一筆賬再決定并發(fā)距離矩陣API單次請求最多返回1萬對距離聽著很高效但服務(wù)端計算量并不小尤其是type1駕車距離要在路網(wǎng)上做大量路徑搜索。一個實際經(jīng)驗值單次100×100的請求響應(yīng)時間通常在1到3秒之間網(wǎng)絡(luò)波動時能到5秒以上。假設(shè)網(wǎng)點數(shù)2000按完整矩陣計算需要400次請求串行循環(huán)跑完大約需要400乘以2秒等于800秒也就是13分鐘以上如果其中夾雜幾次超時重試半小時很正常。多線程的價值就是把這400次請求分散到多個并發(fā)連接上。常見的做法是用ThreadPoolExecutor控制并發(fā)數(shù)而不是無腦開線程。高德對單個Key有QPS限制并發(fā)數(shù)不是越大越好。我一般建議先設(shè)8個線程跑小樣本觀察失敗率和響應(yīng)時間再往上調(diào)高德控制臺配額頁會明確寫出當前Key的QPS上限理論上線程數(shù)可以等于QPS上限但我習慣留20%余量比如QPS限制10就開到8。4.2 基于ThreadPoolExecutor的并發(fā)代碼最小可跑骨架下面的骨架是這類工具的核心循環(huán)它接收上一步生成的請求列表并發(fā)調(diào)用距離矩陣API并把結(jié)果合并到大矩陣中from concurrent.futures import ThreadPoolExecutor, as_completed import requests import time DISTANCE_URL https://restapi.amap.com/v3/distance def fetch_distance(origin_chunk, dest_chunk, key, type1): origins |.join(f{lng:.6f},{lat:.6f} for lng, lat in origin_chunk) destinations |.join(f{lng:.6f},{lat:.6f} for lng, lat in dest_chunk) params {key: key, origins: origins, destinations: destinations, type: type} resp requests.get(DISTANCE_URL, paramsparams, timeout15) data resp.json() if data[status] ! 1: raise RuntimeError(fAPI error: {data[infocode]} {data[info]}) return data[results] def run_concurrent(req_list, key, max_workers8): matrix {} with ThreadPoolExecutor(max_workersmax_workers) as pool: future_map {} for req in req_list: fut pool.submit( fetch_distance, req[origins], req[destinations], key ) future_map[fut] req for fut in as_completed(future_map): req future_map[fut] results fut.result() for item in results: o_idx req[origin_offset] item[origin_index] d_idx req[dest_offset] item[dest_index] if o_idx d_idx: matrix[(o_idx, d_idx)] 0.0 else: matrix[(o_idx, d_idx)] item[distance] return matrix代碼邏輯分三步先把坐標切片格式化成高德要求的lng,lat|lng,lat字符串然后提交到線程池最后解析結(jié)果時用origin_offset和dest_offset把塊內(nèi)編號還原成全局編號。注意as_completed返回的future順序和提交順序無關(guān)一定要通過future_map找回對應(yīng)的請求信息否則偏移量會串位。參數(shù)上timeout15是給網(wǎng)絡(luò)請求留的余量1萬對距離的響應(yīng)超過15秒就放棄重試坐標格式化成6位小數(shù)這是高德坐標精度的下限格式化成{lng:.6f}能避免浮點數(shù)過長或科學(xué)計數(shù)法污染URL。4.3 限流與重試三個參數(shù)把失敗率壓下去多線程并發(fā)后的第一個異常往往是限流?，F(xiàn)象是任務(wù)開始后前幾十個請求正常突然出現(xiàn)大量status ! 1的響應(yīng)伴隨infocode為10044或10019等配額相關(guān)錯誤。高德的限流是按秒計算的當你開的線程數(shù)超過Key的QPS上限超出的請求會被直接拒絕。解決思路有三個參數(shù)可以調(diào)max_workers、重試間隔、重試上限。def fetch_distance_with_retry(origin_chunk, dest_chunk, key, retries3): for attempt in range(retries): try: return fetch_distance(origin_chunk, dest_chunk, key) except RuntimeError as e: if 10044 in str(e) or 10019 in str(e): wait 2 ** attempt time.sleep(wait) continue raise raise RuntimeError(quota exceeded after retries)重試間隔用指數(shù)退避第一次失敗等2秒第二次等4秒第三次等8秒。這個策略的合理性在于限流通常是短時的等待幾秒鐘后配額窗口會釋放。注意不要把retries設(shè)成10以上指數(shù)增長到16秒、32秒會讓整個任務(wù)卡在尾部反而喪失并發(fā)優(yōu)勢。實測經(jīng)驗是并發(fā)8線程、重試3次在限流邊緣能把失敗率壓到0.1%左右。5. 避坑現(xiàn)場五個讓批量距離計算翻車的細節(jié)5.1 返回10001 INVALID_USER_KEYkey本身對服務(wù)沒開現(xiàn)象請求返回infocode10001提示INVALID_USER_KEY但Key是剛從控制臺復(fù)制的復(fù)制過程沒有多余空格。原因大概率不是Key錯了而是這個Key沒有開通「Web服務(wù)API」對應(yīng)的服務(wù)或者你復(fù)制的是「Web端(JS API)」的Key兩種Key不通用。解決去控制臺檢查Key類型確認是Web服務(wù)然后在「API權(quán)限」里確認距離測量/路徑規(guī)劃服務(wù)對該Key可見重新生成一次Key再試。這個小問題在團隊協(xié)作時特別常見A同學(xué)拿B同學(xué)臨時給的Key調(diào)試但B的Key沒開服務(wù)權(quán)限。5.2 type0的直線距離和物流里程差太遠現(xiàn)象兩個實際駕車里程約18公里的網(wǎng)點type0返回9.5公里差了近一半。原因type0算的是球面直線距離只考慮經(jīng)緯度差完全不理會路網(wǎng)、河流、山體。物流運費結(jié)算或配送時效評估必須用type1只有做網(wǎng)點覆蓋半徑的初篩時type0才有參考價值。這個參數(shù)一旦寫錯整張距離矩陣全部作廢而且因為數(shù)字是“合理”的不容易被發(fā)現(xiàn)。我的習慣是把type定義成常量DISTANCE_TYPE 1并在CSV導(dǎo)出文件名里標注type1杜絕誤用。5.3 并發(fā)一上去就成片失敗QPS配額與退避策略現(xiàn)象max_workers20時前10個請求正常第11個開始連續(xù)失敗錯誤集中在10044和10019。原因單Key的QPS上限被瞬間打滿多線程完全踩在限流閾值上。解決不要盲目加線程。先去控制臺看QPS上限把max_workers設(shè)為上限的80%代碼里必須帶指數(shù)退避重試。這里有一個深層坑即使QPS上限是10ThreadPoolExecutor的線程數(shù)是10也不能保證10個請求不會同時落在一個秒級窗口內(nèi)因為線程調(diào)度有延遲。所以并發(fā)數(shù)要留余量跑小樣本觀察失敗率再放大是唯一靠譜的做法。5.4 CSV坐標在Excel里變成科學(xué)計數(shù)法現(xiàn)象CSV文件里lng116.481028用Excel打開后顯示成1.16481E08再保存一次CSV坐標精度徹底丟失后續(xù)計算全部偏到另一個城市。原因Excel把純數(shù)字列自動識別為科學(xué)計數(shù)法并且保存時截斷精度。解決第一CSV里不要存純坐標列改成lng列前加前綴例如lng_str列存116.481028并帶上不可見的字符前綴這會影響后續(xù)解析更干凈的辦法是導(dǎo)出xlsx格式用openpyxl把坐標列的單元格格式設(shè)為文本from openpyxl import Workbook wb Workbook() ws wb.active ws.append([location_id, lng, lat]) ws[B1].number_format ws[C1].number_format 坐標都是經(jīng)緯度字符串用文本格式寫進xlsxExcel打開后不會變形。坐標的精度保留6位小數(shù)就夠6位對應(yīng)約0.1米的精度超過這個位數(shù)對物流距離沒有意義反而增加字符串長度。5.5 矩陣對角線自帶幾公里誤差現(xiàn)象用build_distance_requests生成對稱矩陣后location_id相同的點自己到自己返回的距離不是0而是350米甚至更遠。原因地理編碼對同一地址兩次調(diào)用的坐標可能有毫秒級抖動或者地址匹配到路網(wǎng)不同位置距離矩陣API對同一點做路徑搜索也會因為起點吸附位置不同產(chǎn)生非零距離。解決不管API返回什么解析結(jié)果時一律把o_idx d_idx的距離強制置為0.0。代碼里我在run_concurrent中已做了這個處理這是距離矩陣場景的通用約定。6. 結(jié)果驗證與增量更新把工具調(diào)到生產(chǎn)可用的最后一步6.1 先拿三對已知距離當基準并發(fā)跑通后不要直接信整張矩陣。從網(wǎng)點列表里挑三個已知短、中、長距離的地對例如5公里以內(nèi)的同城對、30公里的城郊對、100公里的跨城對拿手機導(dǎo)航App的推薦路線里程做對照。注意距離矩陣API是靜態(tài)路網(wǎng)計算不走實時路況和導(dǎo)航顯示的里程通常有5%到10%的偏差這可以接受但如果偏差超過20%基本就是type設(shè)錯了或者坐標源有問題。這個基準對照應(yīng)該寫成一個獨立函數(shù)每次修改代碼后先跑這個小樣本再跑全量比事后翻矩陣更省時間?；鶞誓_本的核心很簡單把三對已知坐標單獨喂給fetch_distance打印結(jié)果和導(dǎo)航里程做對比。成本就是三次API調(diào)用但換來的是對整批計算可信度的確認。6.2 SQLite緩存讓第二次跑幾乎零成本物流網(wǎng)點的坐標一般每周甚至每月才變一次距離矩陣更是長期穩(wěn)定。第二次跑相同CSV時如果重新調(diào)API純屬浪費配額。常見做法是在本地SQLite里建兩張表places存地址和坐標distances存距離結(jié)果CREATE TABLE places ( loc_id TEXT PRIMARY KEY, loc_name TEXT, address TEXT, lng REAL, lat REAL, updated_at TEXT ); CREATE TABLE distances ( origin_id TEXT, dest_id TEXT, distance_m REAL, duration_s REAL, PRIMARY KEY (origin_id, dest_id) );每次跑任務(wù)前先查詢CSV里的location_id在places里的坐標是否和之前一致坐標沒變的網(wǎng)點對直接復(fù)用distances里的距離只有新增或坐標變化的地址才進API計算。實際操作中一次增量更新通常只需要補幾個新網(wǎng)點的距離API調(diào)用量從幾百次降到幾十次。我自己的習慣是第一版跑通后不要急著擴并發(fā)而是把樣本縮到20個網(wǎng)點把每一步的返回碼都打印出來看一眼確認沒有配額告警再放大規(guī)模。這套流程執(zhí)行過兩三次后面基本不會再踩限流的坑。希望幫到你。本文還有配套的精品資源點擊獲取