当前位置：首页 > news >正文

使用UniApi调用百度地图API的需要注意的地方

news 来源：原创 2025/5/18 5:29:45

前言

一、百度开放平台

1、功能简介

2、地点搜索服务

3、按行政区划检索API

二、Uniapi集成百度API

1、API集成流程

2、访问接口的定义

3、业务调用集成

三、可能遇到的问题

1、指定输出格式无效

2、返回数据的总数

四、总结

前言

在之前的系列博客中，关于地图在线API我们介绍了天地图、高德开放平台API，当然除了这两个平台还有其它的平台。有朋友发私信留言，希望可以在Uniapi中调用百度开放平台的API的方法和实践方法介绍一下，因为他在亲自动手实践的时候出现了一些状况，然后来交流想看一下是否是哪里的设置有问题。在此之前，对百度地图的API使用的也不多，而且想着都是开放平台，调用方式应该差不多。但是在亲自动手联调的时候，却发现了几个地方不符合预期。

本文是一篇实践型内容，主要讲解如何在Java中使用uniapi来集成百度地图的开放接口实现POI数据的获取，重点讲解在集成过程中的遇到的几个问题，围绕面向问题来寻找解决方案，叙述如何来解决这些问题，让大家在使用同样的方式进行集成时遇到问题有一些参考。为了让大家对百度地图开放平台API有更深入的了解，博文首先将依然对使用到的百度API接口进行简单的介绍，然后介绍在Uniapi来调用百度地图的API接口，最后针对问题来逐一讲解解决方案。示例将涵盖从API密钥的获取、HTTP请求的发送、数据的解析到最终结果的展示等完整流程。通过本文的学习，开发者将能够掌握Java与百度开放平台WebAPI集成的基本方法，并能够根据实际需求，灵活应用这些技术解决实际问题。通过本文的实践，开发者将能够更好地理解和使用百度开放平台的API，为未来的项目开发打下坚实的基础。

一、百度开放平台

本节介绍百度开放平台的功能和主要服务，包括地图、定位、导航等API的概述。其次介绍如何在百度平台中申请个人的账号，以及简要介绍对接方法。

1、功能简介

在之前的系列博客中，我们介绍了天地图的相关WebAPI和高德的开放平台API，基于这两个WebAPI我们可以做一些应用。高德地图和百度地图都是很优秀的地图类产品，这里我们来说说如何从百度平台获取数据。进入到开放平台的首页后可以看到以下界面，这里有很多介绍的文字，大家可以到官网看一下，不再赘述。

关于百度地图提供的服务接口有很多，这里有一个总的入口可以粗略的看一下：

与高德地图提供的接口类似，基本的导航服务、规划服务、地图服务都是应有尽有，大家可以尽情的发挥自己的聪明才智来进行功能使用和探索。

2、地点搜索服务

地点检索服务（又名Place API）是一类Web API接口服务；服务提供多种场景的地点（POI）检索功能，包括城市检索、圆形区域检索、多边形区域检索。开发者可通过接口获取地点（POI）基础或详细地理信息。注意：地点检索服务适用于【XX大厦】、【XX小区】等POI地点名称的检索;若需要检索结构化地址，如【北京市海淀区上地十街十号】，则推荐使用地理编码服务。

以地点搜索API为例，地点搜索包含以下几种地点规则，分别市行政区划区域检索，圆形区域检索，多边形检索，地点详情检索，地点输入提示，POI图片获取以及获取POI的营业状态。

3、按行政区划检索API

为了让大家对百度的开放平台API有更深入的了解，这里将把官网的按行政区划检索POI数据的接口进行重点讲解，希望对大家理解API有所帮助。开发者可通过该功能，检索某一行政区划内（目前最细到城市级别）的地点信息。

API的服务地址：

https://api.map.baidu.com/place/v2/search?query=ATM机&tag=银行&region=北京&output=json&ak=您的ak
//GET请求

请求参数

参数名称	参数含义	示例	字段类型	必选
query	检索关键字。行政区划区域检索不支持多关键字检索。如果需要按POI分类进行检索，请将分类通过query参数进行设置，如query=美食	天安门、美食	string(45)	是
region	检索行政区划区域（增加区域内数据召回权重，如需严格限制召回数据在区域内，请搭配使用city_limit参数），可输入行政区划名或对应cityCode	北京、131（北京的code）、全国，等	string(50)	是
ak	开发者的访问密钥，必填项。v2之前该属性为key。申请密钥		string(50)	是
tag	检索分类偏好，与query组合进行检索，多个分类以","分隔（POI分类），如果需要严格按分类检索，请通过query参数设置	美食	string(50)	否
city_limit	区域数据召回限制，为true时，仅召回region对应区域内数据。	true、false	string(50)	否
extensions_adcode	是否召回国标行政区划编码，true（召回）、false（不召回）	true、false	string(50)	否
output	输出格式为json或者xml	json或xml	string(50)	否
scope	检索结果详细程度。取值为1 或空，则返回基本信息；取值为2，返回检索POI详细信息	1、2	string(50)	否
center	传入poi坐标，辅助检索结果按照距离排序返回。注意：需要结合filter字段一起使用并结合coord_type字段说明该字段的坐标类型	38.76623,116.43213 lat<纬度>,lng<经度>	string(50)	否
filter	检索过滤条件。当scope取值为2时，可以设置filter进行排序。industry_type：行业类型，注意：设置该字段可提高检索速度和过滤精度，取值有： hotel（宾馆）；cater（餐饮）；life（生活娱乐） sort_name：排序字段，根据industry_type字段的值而定。 1、industry_type为hotel时，sort_name取值有： default（默认）；price（价格）；total_score（好评）；level（星级）；health_score（卫生）；distance（距离排序，需结合center字段一起使用） 2、industry_type为cater时，sort_name取值有： default（默认）；taste_rating（口味）；price（价格）；overall_rating（好评）；service_rating（服务）；distance（距离排序，需结合center字段一起使用） 3、industry_type为life时，sort_name取值有： default（默认）；price（价格）；overall_rating（好评）；comment_num（服务）；distance（距离排序，需结合center字段一起使用）sort_rule：排序规则：0（从高到低），1（从低到高）price_section：价格区间groupon：是否有团购：1（有），0（无）discount：是否有打折：1（有），0（无）	sort_name:distance\|sort_rule:1	string(50)	否
coord_type	传入的坐标类型，1（wgs84ll即GPS经纬度），2（gcj02ll即国测局经纬度坐标），3（bd09ll即百度经纬度坐标），4（bd09mc即百度米制坐标）注："ll为小写LL"坐标详细说明	1、2、3(默认)、4	int	否
ret_coordtype	返回的坐标类型，可选参数，添加后POI返回国测局经纬度坐标坐标详细说明	gcj02ll	string(50)	否
page_size	单次召回POI数量，默认为10条记录，最大返回20条。多关键字检索时，返回的记录数为关键字个数*page_size。	10	int	否
page_num	分页页码，默认为0,0代表第一页，1代表第二页，以此类推。常与page_size搭配使用，仅当返回结果为poi时可以翻页。	0、1、2	int	否
sn	开发者的权限签名。sn校验说明		string(50)	可选，若开发者所用AK的校验方式为SN校验时该参数必须。
timestamp	设置sn后该值必填。		string(50)	设置sn后该值必填。
photo_show	是否输出图片信息：true(输出) 、false(不输出)	true、false	bool	否
address_result	query传入结构化地址（如：上地十街10号），检索结果返回数据的类型。若不传入该字段，默认召回门址数据，仅当address_result=false时，召回相应的POI数据	false	string(50)	否
extenstions_town	当取值为true时，召回POI的乡镇街道信息注意：该功能为高级付费功能，您可提交工单咨询	false、true 默认值：false	string(50)	否
language	指定输入参数和召回参数的语言类型，可支持的语言类型为英文注意：该功能为高级付费功能，您可提交工单咨询	en	string(50)	否

返回参数

返回参数				类型	备注
status				Int	本次API访问状态，如果成功返回0，如果失败返回其他数字。（见服务状态码）
message				string	对API访问状态值的英文说明，如果成功返回ok，并返回结果字段，如果失败返回错误说明。
total				int	POI检索总数，开发者请求中设置了page_num字段才会出现total字段。出于数据保护目的，单次请求total最多为150。
result_type				string	region_type 行政区划类型;address_type 结构化地址类型;poi_type poi类型;city_type 城市类型
results					返回的结果
	name			string	poi名称
	location			object	poi经纬度坐标
		lat		float	纬度值
		lng		float	经度值
	address			string	poi地址信息
	province			string	所属省份
	city			string	所属城市
	area			string	所属区县
	town			string	所属乡镇街道信息注意：该功能为高级付费功能，您可提交工单咨询
	adcode			int	行政区划代码
	telephone			string	poi电话信息
	uid			string	poi的唯一标识，可用于详情检索
	status			string	POI的状态：空（代表正常营业）推算位置（代表开放/营业/办公状态可能有变化）暂停营业可能已关闭已关闭注意：该功能为高级付费功能，您可提交工单咨询
	street_id			string	街景图id
	detail			string	是否有详情页：1有，0没有
	detail_info			object	poi的扩展信息，仅当scope=2时，显示该字段，不同的poi类型，显示的detail_info字段不同。
		classified_poi_tag		string	POI展示分类（细致分类）
		distance		int32	距离中心点的距离，圆形区域检索时返回
		type		string	所属分类，如hotel、cater。
		tag		string	标签
		label		string	标签细分解释，比如停车场标签（地上停车场/地下停车场），知名景区标签（几A级景区），酒店标签（什么类型酒店）等
		navi_location		object	POI对应的导航引导点坐标。大型面状POI的导航引导点，一般为各类出入口，方便结合导航、路线规划等服务使用
			lng	float	导航引导点经度
			lat	float	导航引导点纬度
		alias		array	poi别名
		detail_url		string	poi的详情页
		children			poi子点数据，若某poi无子点，该字段为空
			uid	string	poi子点的唯一标示，可用于详情检索
			name	string	poi子点名称
			show_name	string	poi子点简要名称
			tag	string	poi子点类别
			location	object	poi子点坐标 {"lat":39.911318,"lng":116.402284}, // lat poi子点纬度 , lng poi子点经度
			address	string	poi子点地址
		price		string	poi商户的价格
		shop_hours		string	营业时间
		overall_rating		string	总体评分
		taste_rating		string	口味评分
		service_rating		string	服务评分
		environment_rating		string	环境评分
		facility_rating		string	星级（设备）评分
		hygiene_rating		string	卫生评分
		technology_rating		string	技术评分
		image_num		string	图片数
		groupon_num		int	团购数
		discount_num		int	优惠数
		comment_num		string	评论数
		favorite_num		string	收藏数
		checkin_num		string	签到数
		brand		string	poi对应的品牌（如加油站中的『中石油』、『中石化』）
		content_tag		string	poi标签信息
		photos		array	poi图片的下载链接。注意：该功能为高级付费功能，您可提交工单咨询。

二、Uniapi集成百度API

本节详细介绍如何在Java中使用Uniapi来集成百度api实现相关的检索服务。主要从以下三个部分进行介绍，第一是介绍API的集成流程；第二是介绍如何在Uniapi中定义接口；第三是介绍如何在业务中进行集成。

1、API集成流程

在官网中已经详细的说明了如何进行API的注册和集成，按照以下的步骤进行集成即可。

与所有的开放平台一样，要想在外面调用这些接口来进行token的申请，在下面的应用中可以创建访问token。

2、访问接口的定义

这里介绍如何在Uniapi中创建访问api，用来跟开放平台进行交互，uniapi的操作比较简单，下面是示例代码：

package com.yelang.project.thridinterface;
import com.burukeyou.uniapi.http.annotation.HttpApi;
import com.burukeyou.uniapi.http.annotation.param.QueryPar;
import com.burukeyou.uniapi.http.annotation.request.GetHttpInterface;
import com.burukeyou.uniapi.http.core.response.HttpResponse;
@HttpApi(url = "https://api.map.baidu.com/place/v2")
public interface BaiduGeoSearchService {@GetHttpInterface("/search?")public HttpResponse<String> getSearch(@QueryPar("query") String query,@QueryPar("region") String region,@QueryPar("output") String output,@QueryPar("ak") String ak,@QueryPar("page_size") int pageSize,@QueryPar("page_num") int pageNum,@QueryPar("scope") String scope);
}

请注意，这里的参数跟之前的请求参数有一定的差异，因为我们按照需要传入相应的请求参数即可，不需要传入所有的参数。在上面的例子中，创建了两个一个访问接口。第一个方法是根据关键字和行政区划来调用检索一些感兴趣的空间地理信息。

3、业务调用集成

接下来讲解如何在Java当中调用Uniapi定义的接口，根据我们传入的参数来查询目标POI。比如我们需要查询湖南省长沙市的医院（query：医院）的数据，每页数据返回的大小为20条数据。集成的访问代码如下：

package com.yelang.project.unihttp;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.junit4.SpringRunner;
import com.burukeyou.uniapi.http.core.response.HttpResponse;
import com.yelang.project.thridinterface.BaiduGeoSearchService;
@SpringBootTest
@RunWith(SpringRunner.class)
public class BaiduGeoUnihttpCase {private static final String BAIDU_CLIENT_AK = "百度AK";@Autowiredprivate BaiduGeoSearchService bdsearchService;@Testpublic void testSearch() {String query = "医院";String region = "长沙市";String output = "json";HttpResponse<String> result = bdsearchService.getSearch(query, region, output, BAIDU_CLIENT_AK,20,0,"2");System.out.println("第一页的数据如下：");System.out.println(result.getBodyResult());}
}

完成以上的定义之后，我们就可以来调用相关的接口实现关键字的指定行政区划检索，执行结果如如下图所示：

细心的朋友一定发了上面红框中的问题。在代码中我们指定了响应数据的格式为json，但后台返回前端的却不是，那么问题出在哪里呢？下节将进行讲解。

三、可能遇到的问题

在实际开发过程中，开发者可能会遇到一些常见问题，如API调用频率限制、数据解析错误、网络请求超时等。这里我们讲解两个很容易碰到的问题，第一个就是上面提到过的指定输出格式后，输出依然是Xml格式的问题，另外就是如何获取数据总数，从而进行分页获取数据的问题。

1、指定输出格式无效

请注意，在前面的代码中我们已经正确的设置了请求接口中的值output，String output = "json";表示输出响应数据格式为json，而不要是xml。如果不是用uniapi的朋友，大家可以去看一下官方提供的实例，也是可以直接运行跑的。官方实例如下：

请注意在官方提供的示例里，需要访问的接口search后是跟了一个问号的。如果您使用的不是uniapi那么应该是没有问题的。如果使用了uniapi后，一定不要有这个问号，问否输出的值就一直是xml，这个问题曾经让我很迷惑，以为是哪里的值没传过去。经过事件，在定义时一定不要在search后加？。将问号去掉以后再来看最后的输出，如下所示：

是不是惊奇的发现output参数生效了，是我们需要的json了，那么将output修改成xml来看看有没有作用？可以直观的看到，这里的响应输出已经改为xml了，说明output参数可以进行精确的控制。

2、返回数据的总数

在上面的数据中，我们要查询整个长沙市的医院，省会城市的医院数量肯定是超过20条，因为我们设置了默认的参数是20。在返回的响应报文中，包含了数据的总数是130，如下：

"status":0,
"message":"ok",
"total":130,
"result_type":"poi_type",

如果你的接口返回的数据中没有包含total字段，请先检查在请求接口中是否传入了page_num即当前第几页的参数。没有这个参数，则接口中不会返回total。POI检索总数，开发者请求中设置了page_num字段才会出现total字段。

四、总结

以上就是本文的主要内容，本文是一篇实践型内容，主要讲解如何在Java中使用uniapi来集成百度地图的开放接口实现POI数据的获取，重点讲解在集成过程中的遇到的几个问题，围绕面向问题来寻找解决方案，叙述如何来解决这些问题，让大家在使用同样的方式进行集成时遇到问题有一些参考。为了让大家对百度地图开放平台API有更深入的了解，博文首先将依然对使用到的百度API接口进行简单的介绍，然后介绍在Uniapi来调用百度地图的API接口，最后针对问题来逐一讲解解决方案。通过文本，大家不仅掌握了百度地图API接口的相关功能、如何集成百度地图以及使用UniApi的实践过程，希望对大家有所帮助。行文仓促，定有不足之处，欢迎各位朋友在评论区批评指正，不胜感激。