地理位置服务 API

基于 EdgeOne 边缘节点自动获取访客的地理位置信息，无需用户提供任何参数。响应遵循 JSON:API 规范。

📡 接口信息

• 接口路径: /geo
• 请求方法: GET
• 是否需要参数: 否
• 响应格式: JSON（application/vnd.api+json）

🚀 快速开始

基础调用

curl https://api.160621.xyz/v1/geo

JavaScript 调用

// 使用 fetch
fetch('https://api.160621.xyz/v1/geo')
  .then(response => response.json())
  .then(result => {
    if (result.data) {
      const geo = result.data.attributes.geo
      console.log('国家:', geo.countryName)
      console.log('城市:', geo.cityName)
      console.log('IP:', result.data.attributes.clientIp)
    } else {
      console.error('获取失败:', result.errors?.[0]?.detail)
    }
  })

// 使用 async/await
async function getLocation() {
  try {
    const response = await fetch('https://api.160621.xyz/v1/geo')
    const result = await response.json()

    if (!result.data) {
      throw new Error(result.errors?.[0]?.detail || '获取地理位置信息失败')
    }

    return result.data.attributes
  } catch (error) {
    console.error('获取地理位置失败:', error)
    throw error
  }
}

提示：该接口不使用 code / status 字段，请通过 HTTP 状态码与响应中是否包含 data / errors 判断结果。

📋 响应字段

字段	类型	说明	示例
jsonapi	object	JSON:API 版本信息	{ "version": "1.0" }
data	object	资源对象（type=geo、id=client）	{ type, id, attributes }
errors	array	错误对象数组，仅失败时出现	[{ status, code, title, detail }]

data.attributes 字段说明

字段名	类型	说明	示例
geo	object	地理位置信息	{ countryName, cityName, ... }
uuid	string	用户唯一标识	"示例唯一标识"
clientIp	string	客户端 IP 地址	"203.0.113.10"

geo 字段说明

字段名	类型	说明	示例
asn	number	自治域编号	64512
countryName	string	国家/地区名称	"示例国家"
countryCodeAlpha2	string	两位国家代码	"XX"
countryCodeAlpha3	string	三位国家代码	"XXX"
countryCodeNumeric	string	数字国家代码	"000"
regionName	string	省/州名称	"示例省/州"
regionCode	string	省/州代码	"XX-00"
cityName	string	城市名称	"示例城市"
latitude	number | string	纬度	0.0000
longitude	number | string	经度	0.0000
cisp	string	运营商	"示例运营商"

📝 响应示例

成功响应 200

{
  "jsonapi": { "version": "1.0" },
  "data": {
    "type": "geo",
    "id": "client",
    "attributes": {
      "geo": {
        "asn": 64512,
        "countryName": "示例国家",
        "countryCodeAlpha2": "XX",
        "countryCodeAlpha3": "XXX",
        "countryCodeNumeric": "000",
        "regionName": "示例省/州",
        "regionCode": "XX-00",
        "cityName": "示例城市",
        "latitude": 0.0,
        "longitude": 0.0,
        "cisp": "示例运营商"
      },
      "uuid": "示例唯一标识",
      "clientIp": "203.0.113.10"
    }
  }
}

错误响应 500

{
  "jsonapi": { "version": "1.0" },
  "errors": [
    {
      "status": "500",
      "code": "SERVER_ERROR",
      "title": "服务端错误",
      "detail": "获取地理位置信息失败"
    }
  ]
}

⚠️ 注意事项

1. 隐私保护

• 该接口基于网络请求的 IP 地址获取位置
• 无法获取精确的街道地址信息
• 建议在隐私政策中说明位置信息的使用

2. 准确性限制

• 位置信息基于 IP 地址数据库，可能存在偏差
• 使用代理或 VPN 可能导致位置信息不准确
• 某些网络环境下可能无法获取详细的位置信息

3. 缓存建议

// 位置信息缓存（1小时）
const locationCache = new Map()

async function getCachedLocation() {
  const cacheKey = 'user_location'
  const cached = locationCache.get(cacheKey)

  if (cached && Date.now() - cached.timestamp < 3600000) { // 1小时
    return cached.data
  }

  const result = await fetch('https://api.160621.xyz/v1/geo').then(res => res.json())
  const location = result.data?.attributes

  locationCache.set(cacheKey, {
    data: location,
    timestamp: Date.now()
  })

  return location
}