搜狗地图服务接口 API 参考

包含了所有开发中用到的服务接口实例以及使用方法。
使用前请您认真阅读《搜狗地图API使用条款》,如果您已开始使用,表示您已确认并同意该条款中的所有内容。
为了给您提供稳定的服务,请申请clientid,申请流程请参照用户clientid申请

参考目录

简介

    公交换乘方案 Api是一种使用 HTTP 请求计算起终点在同一个城市的公交乘坐方案服务。起终点是以标准经纬度或者搜狗经纬度指定的,可以限制是否避开地铁。返回的换乘方案可能是一个或多个以供用户选择。对返回的多个方案可以指定按时间、换乘次数、步行距离的方式排序。

方案请求

方案请求的http网址:

//api.go2map.com/engine/api/bustransfer/output?parameters

其中,output 可能是以下任何一个值:

  • json(建议)表示以 JavaScript 对象表示法 (JSON) 的形式输出
  • xml 表示以 XML 的形式输出

请求参数

参数是否必填说明
origin 必填 起点位置的经纬度坐标值(可以是原始的经纬度坐标,也可以是搜狗坐标)。经度和纬度用逗号隔开。
destination 必填 终点位置的经纬度坐标值(可以是原始的经纬度坐标,也可以是搜狗坐标)。经度和纬度用逗号隔开。
avoid 可选 指示计算路线时应避开的交通工具。目前只支持两个值: 0:正常模式,什么都不避开,默认值。 1:避开地铁。
tactic 可选 设置返回结果集的排序方式,目前支持: 8:时间排序,默认值。(按时间从少到多排序) 2:按换乘次数由少到多。 (按换乘次数从少到多排序) 4:按步行距离排序。(按步行距离从少到多排序)
maxresultcount 可选 返回结果最大数量。
maxdist 可选 最大步行距离,缺省值为1000。
clientid 可选 clientid参数,表示客户id,用户可以通过申请获得clientid,clientid与客户的域名绑定,并根据用户权限不同绑定了访问次数的限制。如果没有clientid,则请求次数限制在每天2000次。如果访问次数超过这个限制,都需要申请clientid,以便提供更稳定的服务。
contenttype 可选 contenttype参数,用来定义返回内容的编码格式。当无此参数时默认为GBK。
cb 可选 返回结果需要回调的函数名。主要是为浏览器js调用设计。在返回结果格式是xml的时候,此参数失效。缺省值为空。

服务响应

由请求路径中 output 指定服务的返回格式。

JSON输出

以下是西单到搜狐网络大厦的换乘方案的HTTP请求实例:

//api.go2map.com/engine/api/bus/json?destination=12949481,4837101&origin=12954554,4824616 &avoid=1&tactic=8&maxresultcount=10

JSON结果显示如下所示:

{
    "response":{
        "queryflag":"NORMAL",
        "routing":{
            "endtype":"COORD",
            "ex":"12949481",
            "maxdist":"1000",
            "count":"8",
            "ey":"4837101",
            "tactic":"8",
            "swlimit":"0",
            "endstopuid":"",
            "city":"北京",
            "existsw":"1",
            "startstopuid":"",
            "starttype":"COORD",
            "enduid":"",
            "st":"起点位置",
            "sy":"4824616",
            "et": "启迪科技大厦",
            "group":
            [
                {
                    "id":"",
                    "time":"63",
                    "subtime":"0",
                    "nooftrans":"3",
                    "walkdist":"950",
                    "line":[
                        {"dets":"7,127,128","linenames":"地铁1号线"},
                        {"dets":"68,1175,1178","linenames":"地铁2号线(内)"},
                        {"dets":"1,23,26","linenames":"地铁13号线"},
                        {"dets":"930,24515,24516","linenames":"375"}
                    ],
                    "fare":"0.0",
                    "toenddist":"367",
                    "dist":"13"},
                ...
            ],"sx":"12954554",
            "startuid":""
        },
        "type":"FINAL",
        "mapservice":"QueryBusTransfer",
        "city":"北京"
    },
    "status":"ok"
}
                

XML输出

以下是西单到搜狐网络大厦的换乘方案的HTTP请求实例:

//api.go2map.com/engine/api/bus/xml?destination=12949481,4837101&origin=12954554,4824616 &avoid=1&tactic=8&maxresultcount=10

XML结果显示如下所示:

<xml>
    <response>
        <queryflag>NORMAL</queryflag>
        <routing>
            <endtype>COORD</endtype>
            <ex>12949481</ex>
            <maxdist/>
            <count>7</count>
            <ey>4837101</ey>
            <tactic>8</tactic>
            <swlimit>1</swlimit>
            <endstopuid/>
            <city>北京</city>
            <existsw>1</existsw>
            <startstopuid/>
            <starttype>COORD</starttype>
            <enduid/>
            <st>起点位置</st>
            <sy>4824616</sy>
            <et>启迪科技大厦</et>
            <group>
                <id/>
                <time>82</time>
                <subtime>0</subtime>
                <nooftrans>0</nooftrans>
                <walkdist>1100</walkdist>
                <line>
                    <dets>1742,48695,48711</dets>
                    <linenames>690</linenames>
                </line>
                <fare>0.0</fare>
                <toenddist>383</toenddist>
                <dist>13</dist>
            </group>
           ...
            <sx>12954554</sx>
            <startuid/>
        </routing>
        <type>FINAL</type>
        <mapservice>QueryBusTransfer</mapservice>
        <city>北京</city>
    </response>
    <status>ok</status>
</xml>
                

结果说明

返回结果包括response、status两个元素。

status元素

服务返回的状态码,会返回以下两个值:

  • ok表示服务正常,请求无误。
  • error 表示返回结果有误,可以通过解析response中的error节点,得到详细的错误信息。

response元素

response包括两中情况,输入参数无误,查询结果正常的情况,查询有误的情况。分别对应status的ok和error状态。

属性名说明
routing 换乘方案的具体信息,详情信息请参见rooting节点说明。
city 当前查询换乘方案所在的城市。
error 当status为error时需要解析此节点。error节点包括id和msg两个元素。错误情况:
id= 201 msg=“抱歉, 在起点附近无法找到上车车站,请尝试增加步行距离!“
id= 202 msg=“抱歉, 在终点附近无法找到上车车站,请尝试增加步行距离!“
id= 203 msg=“抱歉, 在起终点之间无法找到可行线路!“;
id= 204 msg=“抱歉,没有在您所指定的最大步行距离内找到合适的路线,请尝试增加步行距离!“
id= 205 msg=“抱歉, 所在城市不支持公交换乘!“;
id= 206 msg=“抱歉,您查询的起终点距离过近,步行即可!“
id= 209 msg=“抱歉,服务器链接失败,请稍候查询!“
id= 210 msg=“抱歉,起终点不在同一个城市,无法查询公交换乘策略!“
id= 212 msg=”抱歉,您选择的最大步行距离内无法找到您所选的必乘线路车站,请扩大步行距离或更换必乘线路!”
id= 213 msg=”抱歉,请求参数错误!“

routing元素

属性名说明
sx 起点的搜狗坐标的经度。
sy 起点的搜狗坐标纬度。
ex 终点的搜狗坐标的经度。
ey 终点的搜狗坐标纬度。
st 起点名称。
et 终点名称。
group 对应的换乘方案。Json中对应的是方案的数组。XML则是对应的单个的方案信息。具体的方案信息请参见group节点说明。
count 返回的方案数量数量

group元素

属性名说明
time 方案所用的时间,单位分钟。
subtime 因聚类因素需要减掉的时间,需要在二次请求时传给服务器端。
nooftrans 方案换乘次数。
walkdist 方案需要步行的距离。
line 方案换乘信息包括两个元素:
dets:dets标签表示第二次请求需要返回给服务器的串,以冒号(:)为一个分隔,依次为:[线路ID,上车站ID,下车站ID:线路ID,上车站ID,下车站ID]。
linename:linenames为可乘坐的线路名,如果有多条线路可以选择时,用冒号来分隔多个路线。例如:linenames="345路:731路:地铁13号线:331路"。
toenddist 终点车站距离目的地的步行距离。 单位米。

方案信息简介

    方案详细信息 Api是公交换乘方案的后续接口。公交换乘方案在考虑响应时间、资源合理应用的前提下,只返回了换乘方案的简要信息。由此服务接口返回公交方案的详细信息。

方案信息请求

具体方案请求的http网址:

//api.go2map.com/engine/api/busdetail/output?parameters

其中,output 可能是以下任何一个值:

  • json(建议)表示以 JavaScript 对象表示法 (JSON) 的形式输出
  • xml 表示以 XML 的形式输出

请求参数

参数是否必填说明
dets 必填 线路段的方案对应线路的上下车站信息。如果需要换乘,则用冒号隔开多个dets值。
subtime 必填 交换乘方案中返回的subtime,因聚类车站需要减掉的时间。
city 必填 查询的公交换乘方案所在的城市。
startxy 必填 起点经纬度(搜狗坐标),经纬度用逗号隔开。
endxy 必填 终点经纬度(搜狗坐标),经纬度用逗号隔开。
startname 可选 起点的名称。
endname 可选 终点的名称。
clientid 可选 clientid参数,表示客户id,用户可以通过申请获得clientid,clientid与客户的域名绑定,并根据用户权限不同绑定了访问次数的限制。如果没有clientid,则请求次数限制在每天2000次。如果访问次数超过这个限制,都需要申请clientid,以便提供更稳定的服务。
contenttype 可选 contenttype参数,用来定义返回内容的编码格式。当无此参数时默认为GBK。
cb 可选 返回结果需要回调的函数名。主要是为浏览器js调用设计。在返回结果格式是xml的时候,此参数失效。缺省值为空。

服务响应

由请求路径中 output 指定服务的返回格式。

JSON输出

以下是西单到搜狐网络大厦的换乘方案的HTTP请求实例:

//api.go2map.com/engine/api/busdetail/json?dets=513,15088,15093:1,23,26&groupid=0&startxy=12954554,4824616&endxy=12949481,4837101&subtime=0&city=北京&startname=西单-公交车站&endname=搜狐网络大厦

JSON结果显示如下所示:

{
    "response":{
        "walkdet":[],
        "start":{
                   "walkdist":"0",
                   "name":"西单-公交车站",
                   "y":"4824616",
                   "x":"12954554"
        },
        "fare":"3.0",
        "groupid":"0",
        "transferinfo":
        [
            {
                "subwayoutxy":"",
                "linetype":"2",
                "upname":"西单",
                "lineid":"7",
                "walkdist":"140",
                "downfid":"128",
                "passstopnum":"1",
                "subwayin":"C",
                "endstopseq":"11",
                "linename" :"地铁1号线(四惠东-苹果园)",
                "uniqueid":"1000028978646",
                "time":"7",
                "downname" :"复兴门",
                "startstopseq":"10",
                "linefid":"7",
                "upfid": "127",
                "upx":"12954438",
                "subwayout":"",
                "upy" :"4824602",
                "points":{
                    "levels": "@Q@",
                    "type":"C",
                    "txt":"kstuWs`neHryAGfo@G"
                } ,
                "downy":"4824610",
                "subwayinxy" :"12954544.000000,4824669.000000",
                "downx":"12952216",
                "dist":"1.7"
            },
             ...
        ],
        "end":{
            "walkdist":"280",
            "name":"搜狐网络大厦",
            "y":"4837101",
            "x":"12949481"
        }
    },
    "status":"ok"
}

XML输出

XML输出HTTP请求实例:

//api.go2map.com/engine/api/busdetail/xml?dets=513,15088,15093:1,23,26&groupid=0&startxy=12954554,4824616&endxy=12949481,4837101&subtime=0&city=北京&startname=西单-公交车站&endname=搜狐网络大厦

XML结果显示如下所示:

<xml>
    <response>
        <start>
            <walkdist>0</walkdist>
            <name>西单-公交车站</name>
            <y>4824616</y>
            <x>12954554</x>
        </start>
        <fare>3.0</fare>
        <groupid>0</groupid>
        <mapservice>BusQueryDetails</mapservice>
        <transferinfo>
            <subwayoutxy/>
            <linetype>2</linetype>
            <upname>西单</upname>
            <lineid>7</lineid>
            <walkdist>140</walkdist>
            <downfid>128</downfid>
            <passstopnum>1</passstopnum>
            <subwayin>C</subwayin>
            <endstopseq>11</endstopseq>
            <linename>地铁1号线(四惠东-苹果园)</linename>
            <uniqueid>1000028978646</uniqueid>
            <time>7</time>
            <downname>复兴门</downname>
            <startstopseq>10</startstopseq>
            <linefid>7</linefid>
            <upfid>127</upfid>
            <upx>12954438</upx>
            <subwayout/>
            <upy>4824602</upy>
            <points>
                <levels>@Q@</levels>
                <type>C</type>
                <txt>kstuWs`neHryAGfo@G</txt>
            </points>
            <downy>4824610</downy>
            <subwayinxy>12954544.000000,4824669.000000</subwayinxy>
            <downx>12952216</downx>
            <dist>1.7</dist>
        </transferinfo>
        ...
        <end>
            <walkdist>280</walkdist>
            <name>搜狐网络大厦</name>
            <y>4837101</y>
            <x>12949481</x>
        </end>
    </response>
    <status>ok</status>
</xml>
                

结果说明

返回结果包括response、status两个元素。

status元素

服务返回的状态码,会返回以下两个值:

  • ok 表示服务正常,请求无误。
  • error 表示返回结果有误,可以通过解析response中的error节点,得到详细的错误信息。

response元素

    response包括两中情况,输入参数无误,查询结果正常的情况,查询有误的情况。分别对应status的ok和error状态。当status为error时respone中只有error元素。当status为ok时response中没有error元素。下表是respones中所有节点信息的说明。

属性名说明
start 起点信息对象。包括属性:name,x,y。x,y代表起点经纬度(搜狗坐标)。name代表起点的名称。
end 终点信息对象。包括属性:walkdist,name,x,y。walkdist代表下车站到终点的距离。x,y代表起点经纬度(搜狗坐标)。name代表起点的名称。
fare 此方案总的票价花费。
transferinfo 换乘路段的详细信息,包括路段的线坐标,乘坐线路类型,线路名称,上下车站,本段距离,花费时间等信息。详细信息请参见transferinfo元素。
error 当status为error时需要解析此节点。error节点包括id和msg两个元素。错误情况:
id= 209 msg=“抱歉,服务器链接失败,请稍候查询!“
id= 213 msg=“抱歉,请求参数错误!“

transferinfo元素

属性名说明
linetype 线路类型 : 1代表公交; 2代表地铁
upname 上车站的站名称。
downname 下车站的站名称。
walkdist 出发点(起点或者前一次乘座线路的下车站)到本次乘坐线路的上车站的距离。
upx 上车站的经度坐标(搜狗坐标)。
upy 上车站的纬度坐标(搜狗坐标)。
downx 下车站的经度坐标(搜狗坐标)。
downy 下车站的纬度坐标(搜狗坐标)。
passstopnum 本次乘坐线路途经的站点数。
time 乘坐本次线路耗时。
points 坐标信息,具体的坐标信息存放在txt属性中。 坐标串中的坐标用逗号隔开,如:x,y,x,y... 。 Points元素还包含一个level属性,level属性是每个坐标点对应的显示级别。