高德地图API获取地铁城市列表实战指南

Clark Liew

1. 高德地图地铁城市列表获取方案解析

作为一名长期从事地图应用开发的工程师，我经常需要处理各类城市数据获取需求。最近在开发一个地铁线路展示项目时，遇到了获取全国开通地铁城市列表的需求。高德地图作为国内主流地图服务商，其API文档中确实没有直接给出完整示例，经过一番摸索后，我整理出这套稳定可靠的实现方案。

这个方案的核心价值在于：

直接调用高德官方JS API获取最新城市数据
绕过文档不完善的问题，提供完整可运行代码
包含错误处理和调试技巧，降低接入门槛

2. 环境准备与密钥配置

2.1 申请开发者密钥

在使用高德地图任何API前，都需要先申请密钥对。具体步骤：

访问高德开放平台(https://lbs.amap.com)
注册开发者账号并完成实名认证
进入"控制台"-"应用管理"创建新应用
为应用添加"Web端(JS API)"服务平台
获取生成的Key和安全密钥(securityJsCode)

重要提示：安全密钥是2021年后新增的安全机制，必须配置否则会报"INVALID_USER_DOMAIN"错误

2.2 域名白名单配置

在应用设置中必须添加可调用API的域名白名单：

开发环境可配置为localhost和127.0.0.1
生产环境需填写正式域名
支持通配符如*.yourdomain.com

3. 地铁城市列表获取实现

3.1 基础代码结构

以下是完整可运行的实现代码，关键部分已添加注释说明：

html复制<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>高德地铁城市列表获取</title>
    <!-- 引入高德地铁JS -->
    <script type="text/javascript">
        // 配置安全密钥
        window._AMapSecurityConfig = {
            securityJsCode: "你的安全密钥" // 替换为实际值
        };
    </script>
    <!-- 加载地铁JS API -->
    <script src="https://webapi.amap.com/subway?v=1.0&key=你的Key&callback=metroInit"></script>
</head>
<body>
    <script>
        // 地铁API加载完成回调
        window.metroInit = function(){
            // 创建地铁实例
            var subwayInstance = subway("container", {
                easy: 1 // 简易模式
            });
            
            // 获取城市列表
            subwayInstance.getCityList(function(cities){
                console.log("获取到的城市数据:", cities);
                processCityData(cities); // 处理数据
            });
        };
        
        // 数据处理函数
        function processCityData(data) {
            // 示例：提取开通地铁的城市名
            var cityNames = data.map(item => item.name);
            console.log("开通地铁的城市:", cityNames);
            
            // 可根据需要进一步处理数据
            // ...
        }
    </script>
</body>
</html>

3.2 核心参数说明

参数	类型	必填	说明
v	string	是	API版本号，固定1.0
key	string	是	开发者Key
callback	string	是	回调函数名
securityJsCode	string	是	安全密钥

3.3 返回数据结构解析

API返回的典型数据结构如下（以北京为例）：

json复制[
    {
        "adcode": "110000",
        "name": "北京市",
        "pinyin": "beijing",
        "lines": [
            {
                "id": "1000",
                "name": "1号线",
                "color": "#E5171B",
                "stations": ["苹果园", "古城", "..."]
            }
            // 其他线路...
        ]
    }
    // 其他城市...
]

关键字段说明：

adcode: 城市行政区划代码
name: 城市名称
pinyin: 城市拼音
lines: 地铁线路数组
- id: 线路ID
- name: 线路名称
- color: 线路代表色(RGB)
- stations: 站点列表

4. 常见问题与解决方案

4.1 API加载失败排查

问题现象：

控制台报错"INVALID_USER_KEY"
无任何数据返回

解决步骤：

检查Key是否正确且未过期
确认安全密钥配置正确
验证调用域名是否在白名单中
检查网络是否正常访问高德API域名

4.2 数据获取异常处理

典型场景：

回调函数未执行
返回数据不完整

解决方案：

javascript复制// 添加超时处理
var timeout = setTimeout(function(){
    console.error("获取数据超时");
}, 5000);

window.metroInit = function(){
    clearTimeout(timeout);
    // ...原有逻辑
};

4.3 跨域问题处理

如果需要在本地开发环境调试：

在HTML文件头部添加：

html复制<meta http-equiv="Content-Security-Policy" content="upgrade-insecure-requests">

或使用本地服务器启动(如http-server)

5. 高级应用与优化建议

5.1 数据缓存策略

频繁调用API可能导致限流，建议：

javascript复制// 使用localStorage缓存数据
function getCityListWithCache() {
    var cached = localStorage.getItem('amap_metro_cities');
    if(cached) {
        return Promise.resolve(JSON.parse(cached));
    }
    
    return new Promise(resolve => {
        subwayInstance.getCityList(function(data){
            localStorage.setItem('amap_metro_cities', JSON.stringify(data));
            resolve(data);
        });
    });
}

5.2 性能优化技巧

延迟加载：在页面主要内容加载完成后再请求地铁数据
按需加载：只获取需要的城市数据（需修改API调用方式）
数据压缩：只保留必要字段减少传输量

5.3 错误监控实现

建议添加错误监控代码：

javascript复制window.metroInit = function(){
    try {
        // ...原有逻辑
    } catch(e) {
        console.error("地铁数据获取异常:", e);
        // 可上报到监控系统
    }
};

6. 实际应用案例

6.1 城市选择器实现

基于获取的数据构建城市选择下拉框：

javascript复制function buildCitySelector(cities) {
    var select = document.createElement('select');
    cities.forEach(city => {
        var option = document.createElement('option');
        option.value = city.adcode;
        option.textContent = city.name;
        select.appendChild(option);
    });
    document.body.appendChild(select);
}

6.2 地铁线路可视化

结合高德地图JS API实现线路展示：

javascript复制// 需先加载AMap.Map
function showCityLines(cityAdcode) {
    subwayInstance.getCityLines(cityAdcode, function(lines){
        lines.forEach(line => {
            // 在地图上绘制线路
            new AMap.Polyline({
                path: line.path,
                strokeColor: line.color,
                strokeWeight: 5
            }).setMap(map);
        });
    });
}