快速入门

本节介绍如何快速使用DuMap Java SDK接入DuMap服务。

创建DuMapClient

DuMapClient是与DuMap服务交互的客户端,DuMap Java SDK的基本功能都是通过DuMapClient完成的。

使用AK/SK创建DuMapClient

通过AK/SK方式访问DuMap服务,用户可以参考下面代码完成初始化客户端的操作。

String ACCESS_KEY_ID = "<your-access-key-id>";                   // 用户的Access Key ID
String SECRET_ACCESS_KEY = "<your-secret-access-key>";           // 用户的Secret Access Key

// 初始化配置
BceClientConfiguration config = new BceClientConfiguration()
    .withCredentials(new DefaultBceCredentials(ACCESS_KEY_ID, SECRET_ACCESS_KEY));

// 初始化一个DuMapClient
DuMapClient client = new DuMapClient(config);

在代码中,变量ACCESS_KEY_ID与SECRET_ACCESS_KEY是系统分配给用户的,均为字符串,用于用户访问位置服务的签名认证。其中ACCESS_KEY_ID对应控制台中的“Access Key ID”, SECRET_ACCESS_KEY对应控制台的“Access Key Secret”。

设置网络参数

用户可以通过BceClientConfiguration对基本网络参数进行设置。

// 初始化配置
BceClientConfiguration config = new BceClientConfiguration();

// 设置网络协议
config.setProtocol(Protocol.HTTPS);

// 设置允许打开的最大连接数
config.setMaxConnections(10);

// 设置建立连接的超时时间
config.setConnectionTimeoutInMillis(5000);

参数说明

通过BceClientConfiguration可以配置的参数如下表所示:

参数 说明
connectionTimeoutInMillis 建立连接的超时时间(单位:毫秒)
localAddress 本地地址
maxConnections 允许打开的最大HTTP连接数
protocol 连接协议类型
proxyDomain 访问NTLM验证的代理服务器的Windows域名
proxyHost 代理服务器主机地址
proxyPassword 代理服务器验证的密码
proxyPort 代理服务器端口
proxyPreemptiveAuthenticationEnabled 是否设置用户代理认证
proxyUsername 代理服务器验证的用户名
proxyWorkstation NTLM代理服务器的Windows工作站名称
retryPolicy 连接重试策略
socketBufferSizeInBytes Socket缓冲区大小
socketTimeoutInMillis 通过打开的连接传输数据的超时时间(单位:毫秒)
userAgent 用户代理,指HTTP的User-Agent头

地点检索

行政区划区域检索

行政区划区域检索示例代码如下:

PlaceSearchByRegionParam param = PlaceSearchByRegionParam.builder()
            .query("ATM机")                 // 检索关键字
            .tag("银行")                    // 检索分类偏好
            .region("北京")                 // 检索行政区划区域
            .output("json")                // 输出格式为json字符串或者xml字符串 
            .build();
String response = client.placeQuery("<your-app-id>", param); // "<your-app-id>"为用户的appId,即前端应用列表中的应用id

上面代码通过PlaceSearchByRegionParam构建行政区划区域检索的参数,更多请求参数及返回参数说明请参考地点检索服务接口文档

圆形区域检索

圆形区域检索示例代码如下:

PlaceSearchByLocationParam param = PlaceSearchByLocationParam.builder()
            .query("银行")                 // 检索关键字
            .location("39.915,116.404")  // 圆形区域检索中心点
            .radius("2000")               // 圆形区域检索半径
            .output("json")               // 输出格式为json字符串或者xml字符串 
            .build();
String response = client.placeQuery("<your-app-id>", param); // "<your-app-id>"为用户的appId,即前端应用列表中的应用id

上面代码通过PlaceSearchByLocationParam构建圆形区域检索的参数,更多请求参数及返回参数说明请参考地点检索服务接口文档

矩形区域检索

矩形区域检索示例代码如下:

PlaceSearchByBoundsParam placeSearchByBoundsParam = PlaceSearchByBoundsParam.builder()
            .query("美食")                                      // 检索关键字
            .bounds("38.76623,116.43213,39.54321,116.46773")   // 检索矩形区域
            .retCoordtype("gcj02ll")                           // 添加后POI返回国测局经纬度坐标
            .output("json")                                    // 输出格式为json字符串或者xml字符串
            .build();
String response = client.placeQuery("<your-app-id>", placeSearchByBoundsParam); // "<your-app-id>"为用户的appId,即前端应用列表中的应用id

上面代码通过PlaceSearchByBoundsParam构建矩形区域检索的参数,更多请求参数及返回参数说明请参考地点检索服务接口文档

地点详情检索

地点详情检索示例代码如下:

PlaceDetailParam param = PlaceDetailParam.builder()
            .uid("08db2caeab1dc6dcfb2213da")          // 检索poi的uid
            .scope(2)                                 // 检索结果详细程度
            .output("json")                           // 输出格式为json字符串或者xml字符串
            .build();
String response = client.placeDetail("<your-app-id>", param); // "<your-app-id>"为用户的appId,即前端应用列表中的应用id

上面代码通过PlaceDetailParam构建地点详情检索的参数,更多请求参数及返回参数说明请参考地点检索服务接口文档

正/逆地理编码

地理编码

地理编码示例代码如下:

GeocoderParam param = GeocoderParam.builder()
            .address("北京市海淀区上地十街10号")         // 待解析的地址
            .output("json")                          // 输出格式为json字符串或者xml字符串
            .build();
String response = client.geocoder("<your-app-id>", param); // "<your-app-id>"为用户的appId,即前端应用列表中的应用id

上面代码通过GeocoderParam构建地理编码的参数,更多请求参数及返回参数说明请参考正/逆地理编码服务接口文档

全球逆地理编码

全球逆地理编码示例代码如下:

ReverseGeocoderParam param = ReverseGeocoderParam.builder()
            .location("35.658651,139.745415")       // 根据经纬度坐标获取地址
            .output("json")                         // 输出格式为json字符串或者xml字符串
            .build();
String response = client.reverseGeocoder("<your-app-id>", param); // "<your-app-id>"为用户的appId,即前端应用列表中的应用id

上面代码通过ReverseGeocoderParam构建逆地理编码的参数,更多请求参数及返回参数说明请参考正/逆地理编码服务接口文档

坐标转换

坐标转换示例代码如下:

GeoconvParam param = GeoconvParam.builder()
            .coords("114.21892734521,29.575429778924")       // 需要转换的源坐标
            .from(1)                                         // 源坐标类型
            .to(5)                                           // 目标坐标类型
            .build();
String response = client.geoconv("<your-app-id>", param); // "<your-app-id>"为用户的appId,即前端应用列表中的应用id

上面代码通过GeoconvParam构建坐标转换的参数,更多请求参数及返回参数说明请参考坐标转换服务接口文档

路线规划

公交路线规划

公交路线规划示例代码如下:

DirectionTransitParam param = DirectionTransitParam.builder()
            .origin("40.056878,116.30815")             // 起点坐标
            .destination("31.222965,121.505821")       // 终点坐标
            .output("json")                            // 输出格式为json字符串或者xml字符串
            .pageIndex(1)                              // 返回第几页
            .pageSize(1)                               // 返回每页几条路线
            .build();
String response = client.direction("<your-app-id>", param); // "<your-app-id>"为用户的appId,即前端应用列表中的应用id

上面代码通过DirectionTransitParam构建公交路线规划的参数,更多请求参数及返回参数说明请参考路线规划服务接口文档

驾车路线规划

驾车路线规划示例代码如下:

DirectionDrivingParam param = DirectionDrivingParam.builder()
            .origin("40.056878,116.30815")              // 起点坐标
            .destination("31.222965,121.505821")        // 终点坐标
            .output("json")                             // 输出格式为json字符串或者xml字符串
            .build();
String response = client.direction("<your-app-id>", param); // "<your-app-id>"为用户的appId,即前端应用列表中的应用id

上面代码通过DirectionDrivingParam构建驾车路线规划的参数,更多请求参数及返回参数说明请参考路线规划服务接口文档

骑行路线规划

骑行路线规划示例代码如下:

DirectionRidingParam param = DirectionRidingParam.builder()
            .origin("40.056878,116.30815")              // 起点坐标
            .destination("31.222965,121.505821")        // 终点坐标
            .output("json")                             // 输出格式为json字符串或者xml字符串
            .build();
String response = client.direction("<your-app-id>", param); // "<your-app-id>"为用户的appId,即前端应用列表中的应用id

上面代码通过DirectionRidingParam构建骑行路线规划的参数,更多请求参数及返回参数说明请参考路线规划服务接口文档

普通IP定位

普通IP定位示例代码如下:

IPLocationParam param = IPLocationParam.builder()
            .ip("xxx.xxx.xxx.xxx")                     // 需要定位的IP
            .build();
String response = client.locate("<your-app-id>", param); // "<your-app-id>"为用户的appId,即前端应用列表中的应用id

上面的代码通过IPLocationParam构建普通IP定位的参数,更多请求参数及返回参数说明请参考普通IP定位服务接口文档

智能硬件定位

智能硬件定位示例代码如下:

// queryParamList为请求定位的智能硬件列表,每次请求可定位1-3个智能硬件
List<map<string, object>&gt; queryParamList = new ArrayList<map<string, object>&gt;();
// 每个智能硬件定位的请求信息
Map<string, object> bodyElem0 = new HashMap<string, object>();
bodyElem0.put("accesstype", 0);                       // 移动端接入网络方式
bodyElem0.put("output", "JSON");                      // 返回结果类型,目前仅支持JSON(大写)
bodyElem0.put("need_rgc", "N");                       // 是否返回地址信息,默认不返回
queryParamList.add(bodyElem0);
HardwareLocationRequest request = HardwareLocationRequest.builder()
            .body(queryParamList)                     // 请求定位的智能硬件的详细信息
            .src("")                                  // 定位请求来源,厂商标识
            .prod("")                                 // 产品线
            .ver("1.0")                               // 请求服务版本号,1.0
            .trace(false)                             // 是否开启trace,若为true,则将定位记录到鹰眼(暂不开通)
            .build()
String response = client.locate("<your-app-id>", request); // "<your-app-id>" 为用户的appId,即前端应用列表中的应用id

上面的代码通过HardwareLocationRequest构建智能硬件定位的参数,更多请求参数及返回参数说明请参考智能硬件定位服务接口文档

返回结果

DuMapClient接口的返回结果通过请求参数中的output字段进行指定,返回Json字符串或者Xml字符串,默认返回Json字符串。用户获得DuMapClient接口的返回结果后,需要对结果进行解析来获取具体字段的信息。

Json 解析

Json 字符串解析示例代码如下:

// 构造地理编码请求参数
GeocoderParam param = GeocoderParam.builder()
            .address("北京市海淀区上地十街10号")
            .output("json")
            .build();

// 调用地理编码接口
String response = client.geocoder("<your-app-id>", param);

// 将返回的Json字符串解析为HashMap
HashMap map = JsonUtils.fromJsonString(response, HashMap.class);

// 获取返回结果中的status字段
int status = map.get("status");

Xml 解析

Xml 字符串解析示例代码如下:

// 构造地理编码请求参数
GeocoderParam param = GeocoderParam.builder()
            .address("北京市海淀区上地十街10号")
            .output("json")
            .build();

// 调用地理编码接口
String response = client.geocoder("<your-app-id>", param);

// 将返回的Xml字符串解析为Map
Map map = parseXml2Map(response);

// 获取返回结果中的status字段
Object status = map.get("status");

// 将Xml字符串解析为Map
private Map<string,object> parseXml2Map(String xmlStr){
    Map<string,object> map = new HashMap<string,object>();
    Document document;
    try {
        document = DocumentHelper.parseText(xmlStr);
        Element root = document.getRootElement();
        List children = root.elements();
        if(children != null &amp;&amp; children.size() &gt; 0) {
            for(int i = 0; i &lt; children.size(); i++) {
                Element child = (Element)children.get(i);
                map.put(child.getName(), parseElement(child));
            }
        }
    } catch (DocumentException e) {
        e.printStackTrace();
    }
    return map;
}

private Object parseElement(Element root) {
    Map<string,object> map = new HashMap<string,object>();
    List children = root.elements();
    if(children != null &amp;&amp; children.size() &gt; 0) {
        for(int i = 0; i &lt; children.size(); i++) {
            Element child = (Element)children.get(i);
            map.put(child.getName(), parseElement(child));
        }
    } else {
        return root.getTextTrim();
    }
    return map;
}

上面Xml解析代码在使用时需要添加下面依赖

<dependency>
    <groupid>dom4j</groupid>
    <artifactid>dom4j</artifactid>
    <version>1.6.1</version>
</dependency>