@tni/amap

高德地图 Web 服务 API 封装，提供 IP 定位、地理编码、逆地理编码能力。

安装

vp add @tni/amap

使用

创建客户端

import { createAmapClient } from "@tni/amap";

const amap = createAmapClient({
  key: "your-amap-web-service-key",
  timeout: 10_000, // 可选
});

IP 定位

根据 IP 获取地理位置。支持 v3（仅国内）和 v5（国内+国外，需商务申请）。

// v3 基础版：不传 ip 时取请求 IP（服务端调用时有效）
const loc = await amap.getIpLocation();
// { province: "北京市", city: "北京市", adcode: "110000", rectangle: "..." }

// 指定 IP
const loc2 = await amap.getIpLocation({ ip: "114.247.50.2" });

// v5 高级版：支持国外 IP，ip 必传
const loc3 = await amap.getIpLocation({ ip: "8.8.8.8", type: "4" }, "v5");
// { country, province, city, district, adcode, location, isp, ip }

地理编码（地址 → 经纬度）

const { locations, geocodes } = await amap.geocode("北京市朝阳区阜通东大街6号");
// locations: [{ lng: 116.48, lat: 39.99 }, ...]
// geocodes: 完整地理编码信息

// 指定城市提高精度
const { locations: locs } = await amap.geocode("阜通东大街6号", { city: "北京" });

逆地理编码（经纬度 → 地址）

const regeocode = await amap.regeocode(116.310003, 39.991957);
// regeocode.formatted_address
// regeocode.addressComponent: { country, province, city, district, ... }

// 返回附近 POI、道路等（extensions: "all"）
const full = await amap.regeocode(116.31, 39.99, {
  extensions: "all",
  radius: 1000,
});
// full.pois, full.roads, full.roadinters, full.aois

错误处理

请求失败时抛出 AmapError：

import { createAmapClient, AmapError } from "@tni/amap";

try {
  await amap.geocode("invalid");
} catch (e) {
  if (e instanceof AmapError) {
    console.error(e.info, e.infocode);
  }
  throw e;
}

API 参考

| 方法 | 说明 | | ---------------------------------- | ---------------------------- | | getIpLocation(params?, version?) | IP 定位，version 默认为 "v3" | | geocode(address, options?) | 地理编码 | | regeocode(lng, lat, options?) | 逆地理编码 |

类型导出

• IpLocationV3Result / IpLocationV5Result：IP 定位结果
• GeocodeParams / RegeocodeParams：请求参数
• Location：{ lng, lat } 坐标
• parseLocation(str)：解析 "lng,lat" 字符串为 Location

相关文档

• 高德 Web 服务 API 总览
• IP 定位
• 地理/逆地理编码