搜狗地图服务接口 API 参考

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

参考目录

简介

    自驾Api是一种使用 HTTP 请求计算两个在同一个城市位置间的汽车行驶路线服务。起终点是以标准经纬度或者搜狗经纬度指定的,可以限制是否避开高速公路,还可以以距离短或者以时间短为标准计算行驶路线。

自驾请求

自驾请求的http网址:

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

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

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

请求参数

参数是否必填说明
origin 必填 起点位置的经纬度坐标值(可以是原始的经纬度坐标,也可以是搜狗坐标)。经度和纬度用逗号隔开。
destination 必填 终点位置的经纬度坐标值(可以是原始的经纬度坐标,也可以是搜狗坐标)。经度和纬度用逗号隔开。
tactic 可选 默认为1,自驾的限制策略,目前支持3种:
0: 距离短;
1: 时间短 默认策略;
2: 不走高速;
clientid 可选 clientid参数,表示客户id,用户可以通过申请获得clientid,clientid与客户的域名绑定,并根据用户权限不同绑定了访问次数的限制。如果没有clientid,则请求次数限制在每天2000次。如果访问次数超过这个限制,都需要申请clientid,以便提供更稳定的服务。
contenttype 可选 contenttype参数,用来定义返回内容的编码格式。当无此参数时默认为GBK。
cb 可选 返回结果需要回调的函数名。主要是为浏览器js调用设计。在返回结果格式是xml的时候,此参数失效。缺省值为空。

服务响应

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

JSON输出

以下东长安街到鼓楼西大街的自驾的HTTP请求实例:

//api.go2map.com/engine/api/navigation/json?origin=12956763,4824793&destination=13006516,4892623&tactic=0

JSON结果显示如下所示:

{"response":{
    "End":{
        "caption":"鼓楼西大街",
        "y":4892623,
        "x":13006516,
        "city":"北京"
    },
    "Waypoints":{
        "Waypoint":[
            {
                "id":1,
                "caption":"东长安街",
                "y":4824674,
                "x":12956766
            },
            {
                "id":2,
                "caption":"鼓楼西大街",
                "y":4892623,
                "x":13006516
            }
        ]
    },
    "Start":{
        "caption":"东长安街",
        "y":4824793,
        "x":12956763,
        "city":"北京"
    },
    "time-ms":8684398,
    "tactic":"0",
    "type":"final",
    "cost":71667,
    "mode":"",
    "distance":71667,
    "time":"2小时25分钟",
    "price":207,
    "Steps":{
        "Step":[
            {
                "id":1,
                "Steps":{
                    "Step":[
                        {
                            "id":1,
                            "Desc":"从起点出发,朝西方向沿[东长安街,5]行驶155米,进入西长安街"
                        },
                        {
                            "id":2,
                            "Desc":"沿[西长安街,5]行驶339米,过[天安门西站B东北口,4,12956168,4824674]
                                    约50米后右转进入南长街"
                        }
                    ],
                    "count":2
                },
                "Desc":"从起点出发,沿[东长安街,5]一直向前行驶494米,过[天安门西站B东北口,
                        4,12956168,4824674]约50米后右转进入南长街"
            },
            ...
        ]
    },
    "featuretype":"coord",
    "Routes":{
        "Route":{
            "id":1,
            "time":144739,
            "distance":71667,
            "Segments":{
                "Segment":[
                    {
                        "id":1,
                        "Way":{
                            "level":3,
                            "name":"东长安街、西长安街"
                        },
                        "distance":494,
                        "Segments":{
                            "count":2,
                            "Segment":[
                                {
                                    "id":1,
                                    "Way":{
                                        "level":3,
                                        "name":"东长安街"
                                    },
                                    "distance":155,
                                    "Feature":{
                                        "id":2,
                                        "Bounds":{
                                            "maxx":12956766,
                                            "maxy":4824674,
                                            "minx":12956563,
                                            "miny":4824668
                                        },
                                        "caption":"",
                                        "Points":{
                                            "index":"0"
                                        },
                                        "type":"L"
                                    }
                                },
                                {
                                    "id":2,
                                    "Way":{
                                        "level":3,
                                        "name":"西长安街"
                                    },
                                    "distance":339,
                                    "Feature":{
                                        "id":3,
                                        "Bounds":{
                                            "maxx":12956563,
                                            "maxy":4824668,
                                            "minx":12956121,
                                            "miny":4824652
                                        },
                                        "caption":"",
                                        "Points":{
                                            "index":1
                                        },
                                        "type":"L"
                                    }
                                }
                            ]
                        },
                        "Feature":{
                            "id":1,
                            "Bounds":{
                                "maxx":1.2956766E7,
                                "maxy":4824674,
                                "minx":1.2956121E7,
                                "miny":4824652
                            },
                            "caption":"",
                            "Points":{
                                "precision":"0",
                                "count":3,
                                "levels":"@@@",
                                "type":"C",
                                "txt":"{dyuWceneHtKJrZ^"
                            },
                            "type":"L"
                        }
                    },
                    ...
                ]
            }
        }
    }
},"status":"ok"}
                

XML输出

以下东长安街到鼓楼西大街的自驾的HTTP请求实例:

//api.go2map.com/engine/api/navigation/xml?origin=12956763,4824793&destination=13006516,4892623&tactic=0

XML结果显示如下所示:

<xml>
    <response>
        <End>
            <caption>鼓楼西大街</caption>
            <y>4892623</y>
            <x>13006516</x>
            <city>北京</city>
        </End>
        <Waypoints>
            <Waypoint>
                <id>1</id>
                <caption>东长安街</caption>
                <y>4824674</y>
                <x>12956766</x>
            </Waypoint>
            <Waypoint>
                <id>2</id>
                <caption>鼓楼西大街</caption>
                <y>4892623</y>
                <x>13006516</x>
            </Waypoint>
        </Waypoints>
        <Start>
            <caption>东长安街</caption>
            <y>4824793</y>
            <x>12956763</x>
            <city>北京</city>
        </Start>
        <time-ms>8684398</time-ms>
        <tactic>0</tactic>
        <type>final</type>
        <cost>71667</cost>
        <mode/>
        <distance>71667</distance>
        <time>2小时25分钟</time>
        <price>207.0</price>
        <Steps>
            <Step>
                <id>1</id>
                <Steps>
                    <Step>
                        <id>1</id>
                        <Desc>从起点出发,朝西方向沿[东长安街,5]行驶155米,进入西长安街</Desc>
                    </Step>
                    <Step>
                        <id>2</id>
                        <Desc>沿[西长安街,5]行驶339米,过[天安门西站B东北口,4,12956168,4824674]
                                约50米后右转进入南长街</Desc>
                    </Step>
                    <count>2</count>
                </Steps>
                <Desc>从起点出发,沿[东长安街,5]一直向前行驶494米,过[天安门西站B东北口,
                    4,12956168,4824674]约50米后右转进入南长街</Desc>
            </Step>
            ...
        </Steps>
        <featuretype>coord</featuretype>
        <Routes>
            <Route>
                <id>1</id>
                <time>144739</time>
                <distance>71667</distance>
                <Segments>
                    <Segment>
                        <id>1</id>
                        <Way>
                            <level>3</level>
                            <name>东长安街、西长安街</name>
                        </Way>
                        <distance>494</distance>
                        <Segments>
                            <count>2</count>
                            <Segment>
                                <id>1</id>
                                <Way>
                                    <level>3</level>
                                    <name>东长安街</name>
                                </Way>
                                <distance>155</distance>
                                <Feature>
                                    <id>2</id>
                                    <Bounds>
                                        <maxx>12956766</maxx>
                                        <maxy>4824674</maxy>
                                        <minx>12956563</minx>
                                        <miny>4824668</miny>
                                    </Bounds>
                                    <caption/>
                                    <Points>
                                        <index>0</index>
                                    </Points>
                                    <type>L</type>
                                </Feature>
                            </Segment>
                            <Segment>
                                <id>2</id>
                                <Way>
                                    <level>3</level>
                                    <name>西长安街</name>
                                </Way>
                                <distance>339</distance>
                                <Feature>
                                    <id>3</id>
                                    <Bounds>
                                        <maxx>12956563</maxx>
                                        <maxy>4824668</maxy>
                                        <minx>12956121</minx>
                                        <miny>4824652</miny>
                                    </Bounds>
                                    <caption/>
                                    <Points>
                                        <index>1</index>
                                    </Points>
                                    <type>L</type>
                                </Feature>
                            </Segment>
                        </Segments>
                        <Feature>
                            <id>1</id>
                            <Bounds>
                                <maxx>1.2956766E7</maxx>
                                <maxy>4824674.0</maxy>
                                <minx>1.2956121E7</minx>
                                <miny>4824652.0</miny>
                            </Bounds>
                            <caption/>
                            <Points>
                                <precision>0</precision>
                                <count>3</count>
                                <levels>@@@</levels>
                                <type>C</type>
                                <txt>{dyuWceneHtKJrZ^</txt>
                            </Points>
                            <type>L</type>
                        </Feature>
                    </Segment>
                     ...
                </Segments>
            </Route>
        </Routes>
    </response>
    <status>ok</status>
</xml>
                

结果说明

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

status元素

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

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

response元素

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

属性名说明
Start 起点信息对象,包括x,y,caption,city。x,y是起点的经纬度(搜狗坐标)坐标,caption起点的名称,city是起点所在城市。
End 终点信息对象,包括x,y,caption,city。x,y是终点的经纬度(搜狗坐标)坐标,caption起点的名称,city是起点所在城市。
distance 整个路线的距离,单位米。
time 总用时,单位是中文的例如:31分钟。
Waypoints 包含起终点在内的途经点信息,如果没有途经点,则只返回起终点,内容包括,序号id(按照线路经过先后顺序排序起点为1,依次增加) ,名称caption,x 坐标 y坐标(搜狗坐标)。
Price 打车票价,只有在存在当前城市打车价格数据且距离小于200公里时,才返回该字段。
Steps Steps是对线路的文字描述,其中为Step数组,每个Step元素代表一段具体路段的描述。Step的详细描述请参见Step元素说明。
Routes Routes是对线路的地图(坐标序列)描述,子节点为Route节点,route含义为路段,rote的详细信息请参见Route元素说明。
error 当status为error时需要解析此节点。error节点包括id和msg两个元素。错误情况:
id=301 msg=”抱歉,请求参数错误!”;
id= 302 msg=“未知的错误!";

Step元素

对于某些较长路段, Step元素下,仍可能包含Steps数组,是对这一路段的更详细的描述,目的让用户能更准确的找到目的地。

属性名说明
id 路段序号,由1自增。
desc Desc中的中括号中包含着途经点或者道路,或者收费站信息。
自驾路线文字描述中的TAG中的类型值含义(第二个元素为tag分类):
1 出口,2 立交桥,3 方向 ,4 地标 ,5 道路 ,6 收费站
如道路信息,只包含道路名称及类型:
如:沿[学院路,5]直行
如果是出口或方向的类型:
[哈尔滨出口,1,13955214,5440202,
http://misc.go2map.com/garmin/0c8f1699278c4d4bab651d0f9e629ef5_1.jpg]
途径地标信息:需要加入地标的坐标,
如:经[月坛南桥,2,12952223,4825571]左转
当表示收费信息时 ,id为6,代表收费站:
如果收费大于0,收费站tag内容包含如下信息:
信息包含[名称,类型id,x坐标(搜狗坐标),y坐标(搜狗坐标), 计费金额,计费里程,计费起始站名称,计费及时站x坐标,计费其实在y坐标]
如果收费等于0,表示刚刚进入收费路段,只领卡不缴费,此时信息只包含收费站入口信息: [名称,类型id,x坐标(搜狗坐标),y坐标(搜狗坐标),计费金额(此时为0)]

Route元素

属性名说明
id 由1开始对所有的路段由起点路段开始,自增的方式为所有的路段进行的编号。
distance 此路段距离,单位为米。
time 此路段所需要时间,单位为分钟。
Segments 该路段的坐标描述,坐标描述会分为多个Segment, Segment元素中包含 id :所有route中的segement的id依次排序,以1为起始id;这里的id与step元素的id是一一对应的。 Way:包含道路级别level和名称name。 Feature:该段路的坐标描述,其中的Points中的txt为具体坐标序列。 坐标串中的坐标用逗号隔开,如:x,y,x,y...。 Points元素还包含一个level属性,level属性是每个坐标点对应的显示级别。。 与Step元素类似,Segment元素也有可能有子一级的Segments,如果某id的Step存在子Steps,则相对应id的Segment也存在子Segments。