搜狗地图服务接口 API 参考

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

参考目录

简介

    地图搜索接口支持如下类型的查询方式:城市内查询某关键字或分类 某视野内查询某关键字或分类,某坐标周边查询关键字或分类,某poi周边查询关键字或分类,周边查询支持按照距离中心点远近排序。 某视野所在的城市内查询关键字或分类,全国范围内查询某个关键字或者分类。

地图搜索请求串

地图搜索请求的http网址:

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

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

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

请求参数

参数是否必填说明
what 必填 what参数表示要查询的内容。
what取值可以是关键字,或分类id ,或uid,dataid。用一个参数标记类型。
    关键字:what=keyword:五道口:
    分类id:what=classid:97 或 what=classid:C_31 普通数字代表小类id,前缀为C_的代表大类id。
    uid或者dataid: what=id:100002342 或者 what=id:1_D2323_323
     Uid与dataid都用id做标识,由服务端判断属于那种id。当类型为id时,其他参数无效,只返回该id对应的一条数据。
range 必填 range参数表示查询范围, range分多种类型:
名称类型: 如“全国”,省名称,城市名称。例如range=city:全国 range=city:北京市
bound类型: bound值加一个状态分别代表视野内,拉框内,视野所在城市。
例如:range=bound:x,y,x,y:BoundFlag
x,y可以是sogou坐标,或者是经纬度,radius单位为米。
BoundFlag==0 代表视野所在的城市内搜索,
BoundFlag==1代表拉框内搜索
BoundFlag==2代表视野内搜索
坐标加半径: range=center:x,y:radius:limit
x,y可以是sogou坐标,或者是经纬度,radius单位为米,limit代表是否严格限制半径,0代表不限制,1代表限制。
id加半径: range=id:10093200566:radius:limit
id可以是uid或者dataid,radius单位为米,limit代表是否严格限制半径,0代表不限制,1代表限制。
pageinfo 选填 pageinfo参数代表翻页信息
翻页参数:参数名:
pageinfo=1,10 1代表第一页,10代表每页显示结果个数。目前支持最大每页显示100个结果,最多请求1000条。
classfilter 选填 查询keyword时,可以限定分类。分类支持大类小类,可支持多个分类,用以实现在某些分类下查询某关键字的功能,目前只支持id周边查找类型。多个分类用逗号隔开,小类传代表小类id的数字,大类在id前加C_ 如C_22 例如:classfilter=97 classfilter=C_33。 【查看所有分类id
classsort 选填 分类排序参数 classsort 参数控制哪些分类的参数靠前排列 参数格式: classsort=58:10 表示给分类id为58(代表大学)的数据排序权重加10(可以这么简单理解) classsort=50:30,58:20,97:10 classsort=C_12:20,C_3:10
locationsort 选填 locationsort位置排序。 默认值0; locationsort=0(1,2) 排序参数含义: 0---综合排序; 1—matchrank 排序 ; 2 ? 距离中心点距离排序(由小到大) 通常情况下传0 ,进行综合排序。 在查找周边时,如果用户选择了按照中心点距离远近排序,则传2 如果无此参数,普通查询默认为0,周边查询时默认为2
from 选填 参数 ,表示来自哪个应用,无此参数默认来自map搜索。 from=search 表示来自地图搜索 from=bus 表示来自公交换乘 from=nav 表示来自自驾 以后有其他应用,或者合作伙伴需要特殊逻辑,可以再此基础上增加。
clientid 选填 clientid参数,表示客户id,用户可以通过申请获得clientid,clientid与客户的域名绑定,并根据用户权限不同绑定了访问次数的限制。如果没有clientid,则请求次数限制在每天2000次。如果访问次数超过这个限制,都需要申请clientid,以便提供更稳定的服务。
contenttype 选填 contenttype参数,用来定义返回内容的编码格式。当无此参数时默认为GBK。
cb 可选 返回结果需要回调的函数名。主要是为浏览器js调用设计。在返回结果格式是xml的时候,此参数失效。缺省值为空。

服务响应

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

JSON输出

某城市中查询某关键字的实例:

//api.go2map.com/engine/api/search/json?what=keyword:天安门&range=city:北京

JSON结果显示如下所示:

{"response":
{"data":
{"curpage":1,"pagecount":20,"curresult":10,
"feature":[
{"bounds":{"maxx":"1.2956763E7","maxy":"4824793.0","minx":"1.2956763E7","miny":"4824793.0"},
"id":"1000059914330",
"detail":{"phone":"010-63095718","category":"旅游景点","county":"东城区",
"address":"北京市东城区东长安街","subcategory":"知名景点","poidesc":"5星",
"city":"北京市","provience":"北京市"},
"level":15,"alias":"天安门城楼",
"Style":{"id":"S01"},
"cpid":"1","caption":"天安门","points":{"levels":"","type":"C","txt":"udyuWqlneH"},
"type":"S","dataid":"D1000053330282"},

其他feature对象。。。。。。。。。。。。
]

},"status":"ok"}
                

XML输出

某城市中查询某关键字的实例:

//api.go2map.com/engine/api/search/xml?what=keyword:天安门&range=city:北京

XML结果显示如下所示:

<xml>
<response>
<data>
<curpage>1</curpage><pagecount>20</pagecount><curresult>10</curresult>
<resultcount>199</resultcount>
<feature>
<bounds><maxx>1.2956763E7</maxx><maxy>4824793.0</maxy><minx>1.2956763E7</minx>
<miny>4824793.0</miny></bounds><id>1000059914330
</id><detail><phone>010-63095718</phone><category>旅游景点</category>
<county>东城区</county><address>北京市东城区东长安街</address><subcategory>知名景点</subcategory>
<poidesc>5星</poidesc><city>北京市</city><provience>北京市</provience></detail>
<level>15</level><alias>天安门城楼</alias><Style><id>S01</id></Style><cpid>1</cpid>
<caption>天安门</caption><points><levels/><type>C</type><txt>udyuWqlneH</txt></points>
<type>S</type><dataid>D1000053330282</dataid>
</feature>
</data>
<parameters><range>city:北京</range><what>keyword:天安门</what>
<IPLOC>CN1100</IPLOC></parameters>
</response>
<status>ok</status>
</xml>
                

结果说明

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

status元素

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

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

response元素

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

属性名说明
parameters 含义:当前的查询参数。 返回当前提交的所有参数及参数值。 parameters:{ “range”:””,what:””,page:”1,10”…. }
data 含义:主查询结果节点
data节点下,feature数组代表查询结果。
data:{ "curpage":2,"pagecount":378,"curresult":10,"resultcount":3775, “feature[…]”}
结果个数及翻页信息
curpege: 当前是第几页,pagecount:总页数,curresult:当前页包含的结果数,resultcount:总结果数。
feature节点的结构详解 feature 为每个地点对象。也必须保证它的id唯一。
属性:
id 对象的UID。
caption 为对象的名称,也就是在地图上看到的标注文字。
type 为对象类型。取值 S | L | R ,其中 S 表示点,L表示线,R表示面。
layerid 对象所在层的id。
cpid 数据提供者的编号。
dataid数据的编号。
attach归属地。
clustering 代表数据聚类属性 0 :普通数据,1聚类车站,2:公交线路地铁线路,3:聚类道路。
points为对象的节点坐标序列,先采用压缩格式,levels,表示压缩与级别的关系,txt:压缩后的坐标序列,type=C代表压缩格式
bounds 为对象的边界。
属性:
minx,miny,maxx,maxy 表示坐下角和右上角的坐标。
点对象的minx=maxx , miny=maxy
style 用于指定样式。
属性:
id 样式编号。
可以给样式id指定预定义的样式,也可以自定义样式。
点样式图片的编号由S和两位数字组成 ,如:S01 ,S02, S03...
线样式图片的编号由L和两位数字组成 ,如:L01 ,L02, L03...
面样式图片的编号由R和两位数字组成 ,如:R01 ,R02, R03...
自定义时,样式id="custom",style 节点下是样式的实体。
label 用于设置标注的状态。
属性:
on 表示是否要显示标注。true 显示 false 不显示
style 表示标注的样式,是一个css的classname。
detail为详细信息。
属性:
href 网址
phone 电话
address 地址
tag 标签
如果查询词在分词后,在名称 地址,电话中没有全命中,只在标签中(包含别名和大小类)有命中,才返回标签
注释节点 介绍
(为了能随意添加HTML内容而不会与XML冲突)
category 大类
subcategory 小类
poidesc :简介内容,只有需要飘红时才显示此属性。
属性名说明
centerxy, centerpoint 含义:周边搜索的中心点信息
a.当查询xy坐标周边的结果时:
centerxy:{x: 12931375.33,y: 4816433}
b.当中心点为某个poi时,返回中心点对象的feature对象,存在centerpoint属性里:
centerpoint:{feature:{…} }
属性名说明
error 含义:报错信息及提示
当status为error时,取error里的内容,用于客户端提示出错的原因
属性:msg错误信息
msg可以为“,”分隔的关键字,具体取值根据id不同有不同定义;
属性:id 错误信息匹配id msg:报错信息
id:101,msg:查询城市,所查询的关键字
id:102,msg:该坐标范围内,所查询的关键字
id:103,msg:当前视野所在的城市内,所查询的关键字
id:104,msg:当前中心点,所查询的关键字
id:105,msg:当前中心点,所查询的关键字
id:106,msg:全国范围内,所查询的关键字
id:108,msg:查询城市,分类编号id对应的分类
id:109,msg:该坐标范围内,id对应的分类
id:110,msg:当前视野所在的城市内,分类编号id对应的分类
id:111,msg:当前中心点,分类编号id对应的分类
id:112,msg:当前中心点,分类编号id对应的分类
id:113,msg:全国范围内,分类编号id对应的分类
id:115,msg:全国范围内,符合相关id的点
id:123,msg:服务端报错。直接返回报错信息。
以上是查询时查不到结果所报的错误,(严格的说不是错误,只是没查到结果,id即错误编号,msg即错误描述,
格式为 msg:a,b
其中逗号前的a代表查询范围,逗号后的b代表所查的对象。
客户端提示时 可以组合成句子:
如“在a没有找到b”

123 是系统错误,可能由于程序或提交错误参数原因导致的错误,
这时msg中没有逗号,只要显示整句提示就可以,如果不希望用户看到报错原因,也可以在id=123时,给一个统一的描述。
例如:
error":{"id":100,"msg":"北京,深发展大厦 "} 客户端显示为:在北京没有查到与深发展大厦相关的结果