地名解析API
镜像地球基于OpenStreetMap的Nominatim服务，提供免费的地名解析API，支持经纬度反查地名和地名查经纬度功能。
经纬度查地名 (Reverse Geocoding)
将经纬度坐标转换为地址信息。
请求URL
https://api.mirror-earth.com/nominatim/reverse请求参数
| 参数 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
lat | number | 是 | 纬度坐标 | 32.0584 |
lon | number | 是 | 经度坐标 | 118.7965 |
format | string | 否 | 响应格式，默认json | jsonv2 |
addressdetails | number | 否 | 是否返回详细地址信息，1为是，0为否 | 1 |
accept-language | string | 否 | 返回地址的语言，如zh-CN | zh-CN |
请求示例
https://api.mirror-earth.com/nominatim/reverse?lat=32.0584&lon=118.7965&format=jsonv2&addressdetails=1&accept-language=zh-CN响应示例
{
"place_id": 123456789,
"licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
"osm_type": "way",
"osm_id": 12345678,
"lat": "32.0584",
"lon": "118.7965",
"display_name": "中山路, 鼓楼区, 南京市, 江苏省, 中国",
"address": {
"road": "中山路",
"suburb": "鼓楼区",
"city": "南京市",
"state": "江苏省",
"country": "中国",
"postcode": "210000"
},
"boundingbox": [
"32.0583",
"32.0585",
"118.7964",
"118.7966"
]
}响应字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
place_id | number | 地点唯一标识符 |
licence | string | 数据许可证信息 |
osm_type | string | OpenStreetMap对象类型(node/way/relation) |
osm_id | number | OpenStreetMap对象ID |
lat | string | 纬度 |
lon | string | 经度 |
display_name | string | 完整地址显示名称 |
address | object | 详细地址信息对象 |
boundingbox | array | 边界框坐标[南,北,西,东] |
地名查经纬度 (Forward Geocoding)
将地址名称转换为经纬度坐标。
请求URL
https://api.mirror-earth.com/nominatim/search请求参数
| 参数 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
q | string | 是 | 查询的地址名称 | 北京天安门 |
format | string | 否 | 响应格式，默认json | json |
addressdetails | number | 否 | 是否返回详细地址信息，1为是，0为否 | 1 |
limit | number | 否 | 返回结果数量限制，默认10 | 5 |
accept-language | string | 否 | 返回地址的语言 | zh-CN |
countrycodes | string | 否 | 限制搜索的国家代码，逗号分隔 | cn,us |
viewbox | string | 否 | 搜索范围边界框，格式：西,南,东,北 | 116.0,39.0,117.0,40.0 |
bounded | number | 否 | 是否限制在viewbox内搜索，1为是 | 1 |
请求示例
https://api.mirror-earth.com/nominatim/search?q=北京&format=json&addressdetails=1&limit=3&accept-language=zh-CN响应示例
[
{
"place_id": 123456789,
"licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
"osm_type": "way",
"osm_id": 12345678,
"boundingbox": [
"39.9034",
"39.9036",
"116.3974",
"116.3976"
],
"lat": "39.9035",
"lon": "116.3975",
"display_name": "天安门广场, 东城区, 北京市, 中国",
"class": "amenity",
"type": "attraction",
"importance": 0.9,
"address": {
"amenity": "天安门广场",
"suburb": "东城区",
"city": "北京市",
"country": "中国",
"postcode": "100006"
}
}
]响应字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
place_id | number | 地点唯一标识符 |
licence | string | 数据许可证信息 |
osm_type | string | OpenStreetMap对象类型 |
osm_id | number | OpenStreetMap对象ID |
boundingbox | array | 边界框坐标[南,北,西,东] |
lat | string | 纬度 |
lon | string | 经度 |
display_name | string | 完整地址显示名称 |
class | string | 地点分类 |
type | string | 地点类型 |
importance | number | 重要性评分(0-1) |
address | object | 详细地址信息对象 |
使用限制
- 请求频率: 建议每秒不超过1个请求
- 数据来源: 基于OpenStreetMap数据，遵循ODbL许可证
- 服务状态: 免费服务，无服务级别保证
- 语言支持: 支持多语言地址查询和返回
错误处理
当请求出现错误时，API会返回相应的HTTP状态码：
400 Bad Request: 请求参数错误429 Too Many Requests: 请求频率过高500 Internal Server Error: 服务器内部错误
错误响应示例：
{
"error": "Unable to geocode",
"message": "Invalid coordinates provided"
}