您当前的位置Web服务API>Geocoding API

Geocoding API v2.0

Geocoding API V1.0 访问入口自2014年9月1日起,我们将废弃Geocoding API V1.0。届时Geocoding API V1.0将无法正常使用。

1.什么是Geocoding?

Geocoding API 是一类简单的HTTP接口,用于提供从地址到经纬度坐标或者从经纬度坐标到地址的转换服务,用户可以使用C# 、C++、Java等开发语言发送HTTP请求且接收JSON、XML的返回数据。

2.功能介绍

Geocoding API包括地址解析和逆地址解析功能。

  • 地理编码:即地址解析,由详细到街道的结构化地址得到百度经纬度信息,且支持名胜古迹、标志性建筑名称直接解析返回百度经纬度。例如:“北京市海淀区中关村南大街27号”地址解析的结果是“lng:116.31985,lat:39.959836”,“百度大厦”地址解析的结果是“lng:116.30815,lat:40.056885”
  • 逆地理编码,即逆地址解析,由百度经纬度信息得到结构化地址信息。例如:“lat:31.325152,lng:120.558957”逆地址解析的结果是“江苏省苏州市虎丘区塔园路318号”。

3.如何使用

百度地图Geocoding API是一套免费对外开放的API,无使用次数限制。使用方法:

第一步:申请ak(即获取密钥),若无百度账号则首先需要注册百度账号

第二步,拼写发送http请求的url,注意需使用第一步申请的ak。

第三步,接收http请求返回的数据(支持json和xml格式)。

Hello, World

以下是一个关于地理编码的简单示例。发送一个地址是“百度大厦”的请求,返回该地址对应的地理坐标。发送请求的url如下:

http://api.map.baidu.com/geocoder/v2/?address=百度大厦&output=json&ak=E4805d16520de693a3fe707cdc962045&callback=showLocation

结果说明:点击上述请求url,返回地址“百度大厦”解析的json格式的数据。

4.服务地址

百度地图Geocoding API服务地址:

http://api.map.baidu.com/geocoder/v2/

组成说明:

  • 域名:http://api.map.baidu.com
  • 服务名:geocoder
  • 服务版本号:较之前版本,v2版本新增参数。
  • 5.通用接口参数

    参数是否必须默认值格式举例含义
    output xml json或xml 输出格式为json或者xml
    ak E4805d16520de693a3fe707cdc962045 用户申请注册的key,自v2开始参数修改为“ak”,之前版本参数为“key”
    sn    若用户所用ak的校验方式为sn校验时该参数必须。 (sn生成算法
    callback callback=showLocation(JavaScript函数名) 将json格式的返回值通过callback函数返回以实现jsonp功能

    6.地理编码服务

    地理编码专属请求参数:

    参数是否必须默认值格式举例含义
    address 北京市海淀区上地十街10号 根据指定地址进行坐标的反定向解析
    city “北京市” “广州市” 地址所在的城市名

    对于address字段可能会出现中文或其它一些特殊字符(如:空格),对于类似的字符要进行编码处理,编码成 UTF-8 字符的二字符十六进制值,凡是不在下表中的字符都要进行编码。

    字符集合字符
    URL非保留字 a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9 - _ . ~
    URL保留字 ! * ' ( ) ; : @ & = + $ , / ? % # [ ]

    附注:

    (1) javascript中一般采用encodeURIComponent函数对特殊字符进行编码。

    (2) Java中可以使用函数URLEncoder.encode对特殊字符进行编码。

    (3) C#中可以使用函数HttpUtility.UrlEncode对特殊字符进行编码。

    (4) php中可以使用函数urlencode对特殊字符进行编码。

    地理编码示例

    以下是关于地理编码参数使用方法的示例。发送请求显示结果的JavaScript代码此处查看

    地理编码示例

    参数 说明
    address: 该参数是地理编码的必填项,可以输入三种样式的值,分别是:
    • 标准的地址信息,如北京市海淀区上地十街十号;
    • 名胜古迹、标志性建筑物,如天安门,百度大厦;
    • 支持 “*路与*路交叉口”描述方式,如北一环路和阜阳路的交叉路口
    注意:后两种方式并不总是有返回结果,只有当地址库中存在该地址描述时才有返回。
    City: 该参数是可选项,用于指定上述地址所在的城市,当多个城市都有上述地址时,该参数起到过滤作用。

    (结果显示如下)

    地理编码返回结果字段

    名称 类型 说明
    status Int 返回结果状态值, 成功返回0,其他值请查看附录
    location object 经纬度坐标
    lat float 纬度值
    lng float 经度值
    precise Int 位置的附加信息,是否精确查找。1为精确查找,0为不精确。
    confidence Int 可信度
    level string 地址类型

    json格式的返回值

    //带回调函数的返回格式  
    showLocation&&showLocation( 
    {
        status: 0,
        result: 
        {
            location: 
            {
                lng: 116.30814954222,
                lat: 40.056885091681
            },
            precise: 1,
            confidence: 80,
            level: "商务大厦"
        }
    }
    )
    
    //不带回调函数的返回值
    {
        status: 0,
        result: 
        {
            location: 
            {
                lng: 116.30814954222,
                lat: 40.056885091681
            },
        precise: 1,
        confidence: 80,
        level: "商务大厦"
        }
    }

    xml格式的返回值

    <GeocoderSearchResponse>
        <status>0</status>
        <result>
            <location>
                <lat>40.056885091681</lat>
                <lng>116.30814954222</lng>
            </location>
            <precise>1</precise>
            <confidence>80</confidence>    
            <level>商务大厦</level>
        </result>
    </GeocoderSearchResponse>

    特别说明:

    若解析status字段为OK,但结果内容为空,原因分析及可尝试方法:

    • 地址库里无此数据,本次结果为空
    • 加入city字段重新解析
    • 将过于详细或简单的地址更改至省市区县街道重新解析

    7.逆地理编码

    逆地理编码专属请求参数:

    参数是否必须默认值格式举例含义
    coordtype bd09ll bd09ll 百度经纬度坐标 坐标的类型,目前支持的坐标类型包括:bd09ll(百度经纬度坐标)、gcj02ll(国测局经纬度坐标)、wgs84ll( GPS经纬度)
    location 38.76623,116.43213
    lat<纬度>,lng<经度>
    根据经纬度坐标获取地址
    pois 0 0 是否显示指定位置周边的poi,0为不显示,1为显示。当值为1时,显示周边100米内的poi。

    以下是关于逆地理编码参数使用方法的示例。发送请求显示结果的JavaScript代码此处查看

    逆地理编码示例

    参数
    Latitude:
    Longitude:
    pois(是否显示周边100米内poi):

    (结果显示如下)

    状态字段:

    名称 类型 说明
    status constant 返回结果状态值, 成功返回0,其他值请查看附录
    location lat 纬度坐标
    lng 经度坐标
    formatted_address 结构化地址信息
    business 所在商圈信息,如 "人民大学,中关村,苏州街"
    addressComponent city 城市名
    district 区县名
    province 省名
    street 街道名
    street_number 街道门牌号
    pois(周边poi数组) addr 地址信息
    cp 数据来源
    distance 离坐标点距离
    name poi名称
    poiType poi类型,如’ 办公大厦,商务大厦’
    point poi坐标{x,y}
    tel 电话
    uid poi唯一标识
    zip 邮编

    json示例:

    http://api.map.baidu.com/geocoder/v2/?ak=E4805d16520de693a3fe707cdc962045&callback=renderReverse&location=39.983424,116.322987&output=json&pois=1

    xml示例:

    http://api.map.baidu.com/geocoder/v2/?ak=E4805d16520de693a3fe707cdc962045&callback=renderReverse&location=39.983424,116.322987&output=xml&pois=1

    特别说明:

    1.因为Geocoding和反Geocoding使用的门址数据以及算法都不是一样的,所以会出现不能一一对应的现象。

    2.逆地址解析location参数传入的参数格式是(纬度lat,经度lng)。

    8.返回码状态表

    返回码定义
    0正常
    1服务器内部错误
    2请求参数非法
    3权限校验失败
    4配额校验失败
    5ak不存在或者非法
    101服务禁用
    102不通过白名单或者安全码不对
    2xx无权限
    3xx配额错误

    9.升级说明

    • v2版本较之v1版本,功能更新详见更新日志。若需查看v1文档,请点击目录 “Geocoding APIv1.0”。
    • 若v1版本升级至v2版本,地理/逆地理编码的请求url,参数:新增版本号“v2”,修改“key”为“ak”。v2不兼容v1版本的key,若需升级,请重新获取密钥