簡介中國及34個省市地圖JSON文件是一套可直接用于前端地理可視化的數(shù)據(jù)包面向使用D3.js、ECharts繪制全國或省級地圖的開發(fā)者和數(shù)據(jù)分析人員。文件以省市拼音命名覆蓋全國34個省級行政區(qū)讀者無需自行拼接或抓取地理邊界數(shù)據(jù)省去坐標邊界整理環(huán)節(jié)可快速實現(xiàn)各級地圖的加載與交互配置。整個壓縮包共35個JSON文件容量約466KB單文件體積小、結(jié)構(gòu)規(guī)整適合按需提取單個省份或整體引入項目。該資源目前已有3640人學習下載常用于大數(shù)據(jù)可視化大屏、疫情/人口分布圖、區(qū)域業(yè)務(wù)看板等場景。包內(nèi)JSON均按國內(nèi)常用地理坐標系組織屬性字段便于映射到ECharts的map對象也能在D3中配合投影使用同時提供china.json與各省文件方便做下鉆聯(lián)動效果是地圖類前端項目的輕量級基礎(chǔ)工具。 做數(shù)據(jù)可視化這幾年我下載次數(shù)最多的素材大概率就是中國及34個省市的地圖JSON文件了。無論是給客戶做ECharts大屏還是用Python做行政區(qū)劃數(shù)據(jù)分析第一步永遠卡在同一個問題上地圖數(shù)據(jù)從哪來、拿到的JSON能不能直接用。尤其是每次接到“全國地圖下鉆到省、市、區(qū)”的需求時最怕的就是邊界數(shù)據(jù)不完整、坐標對不上、名稱匹配失敗。今天這篇就把我攢下來的這套地圖JSON文件的獲取、解析和落地經(jīng)驗一次性說清楚。全文會從文件結(jié)構(gòu)講到下載渠道再講到ECharts注冊與坐標轉(zhuǎn)換最后附上我踩過的幾個典型坑。希望對正在折騰地圖可視化的朋友有點用不管你是純前端、用Python處理數(shù)據(jù)還是偶爾做后端接口應(yīng)該都能找到自己能直接抄走的東西。1. 地圖JSON到底是個什么東西地圖JSON從本質(zhì)上說就是用一個JSON文件把一塊區(qū)域的邊界、中心點、層級關(guān)系全部描述出來。日常開發(fā)里最常見的格式是GeoJSON它有自己固定的數(shù)據(jù)結(jié)構(gòu)最外層通常是一個FeatureCollection對象里面裝著一個個Feature要素每個要素又分成properties和geometry兩部分。Properties里放的是屬性信息比如行政區(qū)編碼、名稱、中心點坐標geometry里放的才是這條邊界的真正遠近點坐標數(shù)組。很多人第一次打開地圖JSON文件最大的感受是“頭暈”。因為省一級邊界的坐標數(shù)組動輒幾千上萬個點層層嵌套的結(jié)構(gòu)讓人根本看不清哪里是開頭哪里是結(jié)尾。其實你只需要記住一點就好地圖JSON最核心的信息就是邊界點的坐標集合其他的字段都是給業(yè)務(wù)邏輯用的輔助信息。1.1 一張地圖JSON的內(nèi)部結(jié)構(gòu)以DataV.GeoAtlas這套最常見的省級數(shù)據(jù)為例一個省份的JSON文件打開后大概長這樣{ type: FeatureCollection, features: [ { type: Feature, properties: { adcode: 110000, name: 北京市, center: [116.405285, 39.904989], centroid: [116.41995, 40.04404], childrenNum: 16, level: province, parent: { adcode: 100000 }, acroutes: [100000] }, geometry: { type: MultiPolygon, coordinates: [...] } } ] }我來拆開說一下里面幾個關(guān)鍵字段。adcode是行政區(qū)劃代碼相當于每個行政區(qū)的身份證號全國是100000北京市是110000后面下鉆到區(qū)縣就接著用六位編碼往上疊加。name是區(qū)域名稱center和centroid都是中心點但含義不同center是官方公布的地理中心centroid是邊界多邊形計算出來的幾何質(zhì)心如果做標注點位建議用centroid視覺上更居中。childrenNum表示下一級行政區(qū)數(shù)量parent表示上一級acroutes表示完整的父級鏈路數(shù)組從全國一直映射到當前層級。geometry里的coordinates是重頭戲它存放的是區(qū)域邊界的點坐標。如果區(qū)域是完整的連續(xù)地塊一般是MultiPolygon類型里面會有多個多邊形每個多邊形再由多個環(huán)組成環(huán)由一個個經(jīng)緯度坐標點組成。經(jīng)緯度順序通常是[經(jīng)度, 緯度]也就是[lon, lat]這一點千萬別搞反很多新手直接把反了的坐標丟進地圖畫出來的形狀會歪到天上去。1.2 34個省市文件的數(shù)據(jù)關(guān)系34個省市的地圖JSON在數(shù)據(jù)組織上有一個很有意思的特征它們并不是一堆完全孤立散落的文件而是有明確父子關(guān)系的。全國地圖文件里只包含34個省級行政區(qū)的外層邊界不包含市的邊界每個省級文件里則包含它下面所有地級市的邊界再往下每個市級文件里包含區(qū)縣邊界。這種層級在DataV的數(shù)據(jù)命名里體現(xiàn)得很清楚adcode為100000的全國文件內(nèi)部的features數(shù)組就是34個省級區(qū)域每個元素里都有adcode和name字段方便你按名稱或編碼去匹配數(shù)據(jù)。所以在實際使用中全國總圖和省圖的關(guān)系就像母圖和子圖。你要做成“點擊省份下鉆到市級”根本不需要一次性加載所有文件只需要先加載全國文件點擊某個省后動態(tài)加載對應(yīng)的省級文件再把地圖實例重新注冊一遍就行。這種按需加載的方式能明顯減少首屏加載體積尤其是當你只需要展示幾個省份的時候完全沒必要拖著一個幾十兆的全國完整邊界文件。2. 免費下載中國及省市地圖JSON的三大渠道地圖JSON文件看起來稀松平常但要找到一份邊界準確、坐標系正常、帶層級關(guān)系的靠譜文件并不容易。我這些年用下來真正穩(wěn)定省心的渠道就三個下面按推薦程度排序講清楚。2.1 DataV.GeoAtlas最省事的官方渠道第一個要推薦的肯定是阿里云DataV出的GeoAtlas地理數(shù)據(jù)小工具地址在datav.aliyun.com的學校/地圖選擇器板塊。進去之后你可以直接點擊中國地圖上的任意省份也可以搜索行政區(qū)名稱頁面會實時展示該區(qū)域的地圖預(yù)覽同時提供一個JSON文件下載鏈接。我實際使用下來發(fā)現(xiàn)它還有一個非常好用的規(guī)律就是下載地址可以直接拼接。全國地圖的JSON接口是這個格式https://geo.datav.aliyun.com/areas_v3/bound/100000_full.json后面加不加_full區(qū)別很大。帶_full表示返回的是包含下一級全部子區(qū)域的完整文件比如100000_full.json返回的就是34個省級邊界加全部地級市邊界文件更大但信息更全不帶_full則只返回當前層級的邊界。實際做項目時全國大屏用100000_full.json單獨做某個省下鉆時再用對應(yīng)省份的adcode加_full。這套數(shù)據(jù)里默認用的是GCJ-02加密坐標在國內(nèi)地圖組件上直接渲染是沒問題的后面章節(jié)我會細說坐標系的坑。用DataV的另一個好處是文件里已經(jīng)把名稱、adcode、中心點這些屬性都整理好了基本不需要再做二次清洗拿過來直接registerMap就能用。我做過十多個ECharts大屏項目地形邊界部門從來沒因為這個渠道掉過鏈子。2.2 高德地圖行政區(qū)劃接口接實時數(shù)據(jù)的方案第二個渠道是高德地圖的行政區(qū)域查詢接口。如果項目的數(shù)據(jù)本身就跑在高德上或者你希望每次請求都拿到最新的邊界數(shù)據(jù)那用高德接口會更合適。需要在高德開放平臺申請一個Web服務(wù)Key然后請求下面這個地址https://restapi.amap.com/v3/config/district?keywords北京市subdistrict2key你的Keysubdistrict參數(shù)控制返回下級層級的深度0表示只返回當前區(qū)域2表示返回省、市、區(qū)三級。接口返回的是JSON但高德的邊界數(shù)據(jù)藏在districtList下的polyline字段里是一段用分號和逗號分隔的經(jīng)緯度字符串并不是標準的GeoJSON。你需要自己解析成坐標數(shù)組再組裝成FeatureCollection。而且高德返回的是GCJ-02加密坐標如果項目底圖用的是WGS-84的OpenStreetMap之類的地圖解析完之后還得再做一次坐標糾偏工作量就會上來。所以這個渠道更適合后端有一定處理能力的團隊前端拿到的應(yīng)該是后端組裝好的GeoJSON而不是直接把高德原始返回丟給前端解析。如果你只是快速做個靜態(tài)展示沒必要選這條路。2.3 其他開源GeoJSON資源與質(zhì)量對比除了上面兩個主力渠道還有幾個開源項目也能找到中國地圖邊界數(shù)據(jù)。OpenStreetMap上可以通過Overpass API拉取國界和省界但它導(dǎo)出的是WGS-84坐標且中國區(qū)域在OSM上的邊界完整性要看貢獻者的維護情況某些省市邊界會比較粗糙導(dǎo)出后還需要大量清理。Github上有不少個人維護的China GeoJSON倉庫質(zhì)量參差不齊有些甚至是用早期數(shù)據(jù)轉(zhuǎn)的省界和市界會出現(xiàn)重疊、空洞等問題用之前務(wù)必打開檢查。我整理了一張對比表方便你按項目情況選擇渠道坐標系統(tǒng)數(shù)據(jù)完整性實時性適合場景DataV.GeoAtlasGCJ-02高層級完整低頻更新ECharts等國內(nèi)地圖可視化高德APIGCJ-02高但需自行組裝GeoJSON實時后端處理、動態(tài)數(shù)據(jù)系統(tǒng)OSM / Github倉庫WGS-84為主參差不齊不定需自行清洗不建議生產(chǎn)環(huán)境我個人的建議是默認優(yōu)先用DataV能省掉九成麻煩。只有當項目對坐標系統(tǒng)有特定要求或者需要用WGS-84做跨平臺地圖分析時再轉(zhuǎn)向OSM渠道并做好坐標轉(zhuǎn)換。3. ECharts地圖可視化從JSON文件到可交互大屏拿到地圖JSON之后下一步基本就是把它渲染出來。國內(nèi)做地圖大屏最常用的就是ECharts它對GeoJSON的原生支持做得非常好只需要兩三個步驟就能把省級地圖掛到頁面上。3.1 JSON文件加載和注冊在ECharts里使用自定義地圖數(shù)據(jù)核心是registerMap方法。如果你用的是Vite或Webpack這類打包工具可以這樣寫import * as echarts from echarts; import chinaJson from ./assets/china.json; echarts.registerMap(china, chinaJson); const chart echarts.init(document.getElementById(map-container)); chart.setOption({ series: [ { type: map, map: china, roam: true, data: [ { name: 北京市, value: 100 }, { name: 廣東省, value: 88 } ] } ] });registerMap的第一個參數(shù)是你給這份地圖起的注冊名想叫什么都可以但保持一致就行。第二個參數(shù)就是剛才講過的GeoJSON對象可以直接import也可以先用fetch請求回來再傳入。這里有個容易踩的坑就是打包工具對json模塊的解析方式可能不一樣比較穩(wěn)妥的方式是先通過fetch把JSON文本取回來再用JSON.parse轉(zhuǎn)成對象這樣在Node環(huán)境、瀏覽器環(huán)境里都不容易出岔子。如果是做省份下鉆點擊事件里需要重新注冊地圖再setOption。偽代碼大概是這樣的chart.on(click, (params) { const adcode params.data.adcode || mapAdcodeMap[params.name]; fetch(https://geo.datav.aliyun.com/areas_v3/bound/${adcode}_full.json) .then(res res.json()) .then(json { echarts.registerMap(province, json); chart.setOption({ series: [{ type: map, map: province }] }); }); });這樣整體體驗就順了點省份地圖無縫下鉆到市級用返回按鈕或屏幕左上角一個路徑導(dǎo)航再做上鉆交互手感基本可以對齊很多商業(yè)大屏模板了。3.2 數(shù)據(jù)名稱匹配與樣式適配做地圖可視化最頭大的問題之一是名稱匹配。ECharts的map數(shù)據(jù)是根據(jù)name字段去匹配GeoJSON里features的properties.name的如果后端返回的名稱是“北京”而地圖JSON里的名稱是“北京市”那么這件數(shù)據(jù)就不會落到地圖上對應(yīng)區(qū)域會變成空白。處理辦法是在后端或前端做一層名稱歸一化我一般會維護一個映射字典把所有常見縮寫和全稱統(tǒng)一成標準名稱function normalizeName(name) { const map { 北京: 北京市, 上海: 上海市, 廣東: 廣東省, 內(nèi)蒙古: 內(nèi)蒙古自治區(qū), 新疆: 新疆維吾爾自治區(qū), 西藏: 西藏自治區(qū) }; return map[name] || name; }規(guī)格化之后再傳給series.data里的name字段匹配率能達到接近百分之百。名稱匹配上之后剩下的就可以自由發(fā)揮了比如給區(qū)域加漸變顏色、給tooltip加單位后綴、根據(jù)value大小做視覺映射這些都可以用ECharts的visualMap組件實現(xiàn)。我通常會把省份名稱作為第一列可視化維度因為地圖天然就有地理空間感比柱狀圖帶入感強太多。4. 坐標系、數(shù)據(jù)清洗與文件轉(zhuǎn)換的深坑地圖JSON用久了之后你會發(fā)現(xiàn)真正的坑往往不在渲染而在數(shù)據(jù)和坐標。這一節(jié)說幾個我反復(fù)踩、也反復(fù)幫別人排查過的問題。4.1 坐標系三兄弟WGS-84、GCJ-02、BD-09國內(nèi)做地圖繞不開的坐標系就是WGS-84、GCJ-02和BD-09。WGS-84是GPS全球定位系統(tǒng)用的國際標準坐標谷歌地球、OpenStreetMap這類平臺用的大多是這個GCJ-02是中國國內(nèi)使用的一種加密坐標也叫火星坐標高德、騰訊地圖以及阿里DataV的GeoJSON用的都是它BD-09則是百度地圖在GCJ-02基礎(chǔ)上再做一層偏移的坐標只用于百度體系。很多困惑都可以歸結(jié)為一個點不同來源的坐標不能直接混合使用。比如你從高德接口拿到的邊界是GCJ-02但從Github上下載的地圖JSON可能是WGS-84兩者相差大概幾百米在大比例尺的區(qū)縣級地圖上非常明顯邊界會整體偏出底圖輪廓。處理的辦法就是在數(shù)據(jù)層面做坐標轉(zhuǎn)換。網(wǎng)上有很多現(xiàn)成的坐標轉(zhuǎn)換庫Node端可以用coordtransformPython端可以用幾種開源實現(xiàn)核心就是把WGS-84和GCJ-02之間的偏移量算出來再修正回去。我自己的習慣是如果項目所有底圖和邊界數(shù)據(jù)都來自國內(nèi)渠道那統(tǒng)一用GCJ-02如果涉及海外地圖或OpenStreetMap底圖那就統(tǒng)一轉(zhuǎn)成WGS-84。最忌諱的是一個項目里混用兩套坐標那排查起來真的會讓人崩潰。4.2 壓縮、格式轉(zhuǎn)換與Python處理地圖JSON文件通常幾兆到十幾兆不等如果項目對首屏性能要求高建議做壓縮和簡化。最常用的工具是mapshaper一條命令就能把GeoJSON轉(zhuǎn)換成簡化后的版本npx mapshaper china.json -simplify 10% -o china_simplified.json-simplify 10%表示保留大約10%的點文件體積能減小到原來的十分之一左右。需要注意比例太小會讓省界變得非常粗糙出現(xiàn)明顯的折線和鋸齒一般做省級大屏用20%到30%比較穩(wěn)妥做全國總覽用10%也能接受。如果你習慣用Python處理數(shù)據(jù)也可以用geopandas來讀取和轉(zhuǎn)換GeoJSONimport geopandas as gpd gdf gpd.read_file(china.json) gdf gdf.to_crs(EPSG:4326) gdf.to_file(china_4326.json, driverGeoJSON)geopandas最大的好處是可以方便地對屬性字段做過濾和清洗。比如你只需要華東地區(qū)的幾個省市直接對name字段做條件篩選后導(dǎo)出就行比手工維護文件要省事得多。另外部分老文件是TopoJSON格式它把邊界做成了拓撲編碼體積更小但結(jié)構(gòu)更復(fù)雜ECharts不直接支持需要先用topojson-client或mapshaper轉(zhuǎn)成GeoJSON后再用。4.3 省市名稱不一致問題與兜底方案名稱不一致這個問題我單獨拿出來說是因為它在實際項目中出現(xiàn)的頻率實在太高。數(shù)據(jù)源可能返回“廣東省”也可能返回“廣東”甚至可能返回“廣東省-廣州市”這種帶路徑的格式。如果只是展示全國大屏名稱不匹配最多讓某個省市空白但如果是做下鉆交互名稱對不上會導(dǎo)致點擊事件拿不到adcode整個下鉆鏈路直接斷掉。除了維護映射字典我還會在數(shù)據(jù)接入層做一個兜底邏輯先用name精確匹配匹配不到就改用adcode匹配再匹配不到就嘗試去掉“省、市、區(qū)、自治區(qū)、特別行政區(qū)”等后綴后進行模糊匹配。三層匹配下來基本能覆蓋百分之九十九的場景。如果你手頭數(shù)據(jù)源比較多還可以把映射表存成一份獨立JSON文件前端和后端共用方便后續(xù)增量維護。5. 常見問題速查與排查思路最后整理幾個我實際操作中大概率會遇到的問題按“現(xiàn)象、原因、解決”的方式寫出來收藏一下下次排查能少走很多彎路。5.1 地圖白屏或完全不顯示的五個檢查項地圖白屏是最常見的問題大部分時候都不是代碼寫錯了而是數(shù)據(jù)本身有問題。我從易到難排一下檢查順序。第一確認JSON文件內(nèi)容是否為合法JSON很多編輯器會默認給文件加BOM頭用JSON.parse解析時會直接報錯第二確認數(shù)據(jù)里是否包含features字段如果下載的是不帶FeatureCollection結(jié)構(gòu)的普通JSONECharts沒法識別第三確認registerMap的第二個參數(shù)是對象而不是字符串一種低級錯誤是直接傳了文件名第四確認地圖容器有實際高度ECharts初始化時容器高度為0會導(dǎo)致圖表不渲染第五確認坐標系與底圖是否匹配如果底圖是高德而邊界是WGS-84地圖雖然能渲染但邊界會整體偏移看起來就像顯示了一塊錯誤區(qū)域。5.2 常見報錯信息解讀報錯信息常見原因解決思路Unexpected token in JSON文件不是純JSON混入了HTML或注釋檢查下載鏈接是否正確去掉BOMCannot read properties of undefinedGeoJSON結(jié)構(gòu)不完整features為空換數(shù)據(jù)源或重新導(dǎo)出series.map.map can not be foundregisterMap未執(zhí)行或注冊名不一致核對map參數(shù)名確認執(zhí)行順序Invalid GeoJSON坐標范圍異?；蛞蚋呔S數(shù)組層級錯誤無效用geopandas重新校驗并精簡結(jié)構(gòu)5.3 地圖邊界偏移問題如何處理如果你的地圖渲染出來邊界和底圖明顯錯位十有八九是坐標系不一致。用高德底圖配GCJ-02數(shù)據(jù)最穩(wěn)用OSM底圖配WGS-84最穩(wěn)。如果非要把GCJ-02的數(shù)據(jù)放到WGS-84底圖上就得自己寫偏移修正函數(shù)。網(wǎng)上有很多現(xiàn)成代碼核心思想是先計算GCJ-02相對WGS-84的偏移量再把每個坐標點減去這個偏移。修改完之后建議在一個已知坐標點做驗證比如某個城市的市政府位置渲染出來要能正好落在正確位置。我個人在實際操作中的體會是地圖JSON這層數(shù)據(jù)選對來源解決了八成問題剩下兩成時間基本都花在名稱和層級的匹配邏輯上。DataV的文件雖然好用但也要在項目里做一層數(shù)據(jù)緩存不要每次刷新頁面都從遠程拉全量的幾百兆內(nèi)容部署時盡量把這些JSON文件放到自己的靜態(tài)目錄下既保證訪問速度也避免依賴外部接口的穩(wěn)定性。最后再分享一個小技巧在下鉆交互里我會額外緩存用戶點擊過的省份JSON返回上鉆時直接從內(nèi)存或localStorage里讀而不是再fetch一次。這樣反復(fù)切換省市時體驗會順滑很多整個地圖感覺才會真正“活”起來。本文還有配套的精品資源點擊獲取