位置服务

简介

位置服务SDK提供位置查询服务，既能帮助您的用户更加方便地使用位置相关服务，还能帮助您快速获取用户。Site Kit通过提供如下核心能力，帮助您快速构建基于位置服务的产品，满足用户对探索周边地点的需求：

关键字搜索：通过用户输入的关键字，返回地点列表。
周边搜索：基于用户设备位置进行地点查找。
地点详情：查询某个地点更详细的信息。
地点搜索建议：返回一个地点列表，从而实现地点预测功能。

您将建立什么

您通过位置服务SDK可以开发围绕位置搜索的App，比如：

构建位置搜索服务App，可以查询地点详细信息以及周边地点。
构建集成了地图服务SDK与位置服务SDK的App，用于将查询到的位置信息展示到地图上。

您将会学到什么

如何在华为开发者联盟中配置位置相关App。
如何从华为开发者联盟的Site Kit开发者文档获取Demo代码。
如何使用Android Studio集成位置服务SDK进行位置搜索功能开发。

硬件要求

开发计算机（台式机或笔记本电脑），运行Windows操作系统。
Android（4.4及以上）手机一部，用于运行开发调试版本的App。

软件要求

Android Studio 3.3及以上（本文档和相关附件提供的环境暂时只能支持在Windows上使用）（点击下载）
JDK（推荐使用1.8）（点击下载）

集成Site Kit能力，您需要完成以下准备工作：

创建AppGallery Connect（以下简称AGC）应用
添加应用包名
创建Android Studio工程
生成签名证书
生成签名证书指纹
配置签名证书指纹
配置Maven仓地址及AGC gradle插件
在Android Studio配置签名文件

具体操作，请按照HUAWEI HMS Core集成准备中详细说明来完成。

添加应用的AppGallery Connect配置文件

下载应用中的"agconnect-services.json"配置文件。
将"agconnect-services.json"文件配置在模块级目录下。

添加编译依赖

打开模块级的"build.gradle"文件。

在"dependencies"中添加如下编译依赖。


dependencies { 
implementation 'com.huawei.hms:site:{version}' 
}

在文件头添加配置apply plugin: ‘com.huawei.agconnect'‘。

在layout中添加EditText，用来输入查询的关键字；添加TextView，用来展示查询结果。


<?xml version="1.0" encoding="utf-8"?> 
<ScrollView xmlns:android="http://schemas.android.com/apk/res/android" 
android:layout_width="match_parent" 
android:layout_height="match_parent"> 
 
<LinearLayout 
    android:layout_width="match_parent" 
    android:layout_height="wrap_content" 
    android:orientation="vertical"> 
 
    <TextView 
        android:layout_width="match_parent" 
        android:layout_height="30dp" 
        android:layout_gravity="bottom" 
        android:background="#D3D3D3" 
        android:gravity="center_vertical" 
        android:paddingLeft="5dp" 
        android:text="Parameters" 
        android:textSize="16sp" /> 
 
    <LinearLayout 
        android:layout_width="match_parent" 
        android:layout_height="wrap_content" 
        android:orientation="horizontal"> 
 
        <TextView 
            android:layout_width="wrap_content" 
            android:layout_height="wrap_content" 
            android:text="Query: " /> 
 
        <EditText 
            android:id="@+id/edit_text_text_search_query" 
            android:layout_width="0dp" 
            android:layout_height="wrap_content" 
            android:layout_weight="1" 
            android:autofillHints="" 
            android:hint="" 
            android:imeOptions="actionGo" 
            android:inputType="text" 
            android:text="Eiffel Tower" /> 
    </LinearLayout> 
 
    <Button 
        android:id="@+id/button_text_search" 
        android:layout_width="match_parent" 
        android:layout_height="wrap_content" 
        android:onClick="search" 
        android:text="Search" 
        android:textAllCaps="false" /> 
 
    <TextView 
        android:layout_width="match_parent" 
        android:layout_height="30dp" 
        android:layout_gravity="bottom" 
        android:background="#D3D3D3" 
        android:gravity="center_vertical" 
        android:paddingLeft="5dp" 
        android:text="Result" 
        android:textSize="16sp" /> 
 
    <TextView 
        android:id="@+id/response_text_search" 
        android:layout_width="wrap_content" 
        android:layout_height="wrap_content" 
        android:textIsSelectable="true" /> 
</LinearLayout> 
</ScrollView>

声明SearchService对象，并在onCreate方法中通过SearchServiceFactory实例化SearchService。创建SearchService实例需要传入Context和API Key参数：

Context参数建议传入Activity类型，否则在升级HMS Core（APK）时不会弹出升级界面。
API Key在AppGallery Connect上创建应用的时候连同"agconnect-services.json"文件同时生成的。需要对API Key进行encodeURI编码。

Java


package com.huawei.codelab.sitecodelab; 
 
import android.os.Bundle; 
import android.util.Log; 
import android.view.View; 
import android.widget.EditText; 
import android.widget.TextView; 
 
import com.huawei.hms.site.api.SearchResultListener; 
import com.huawei.hms.site.api.SearchService; 
import com.huawei.hms.site.api.SearchServiceFactory; 
import com.huawei.hms.site.api.model.AddressDetail; 
import com.huawei.hms.site.api.model.SearchStatus; 
import com.huawei.hms.site.api.model.Site; 
import com.huawei.hms.site.api.model.TextSearchRequest; 
import com.huawei.hms.site.api.model.TextSearchResponse; 
 
import androidx.appcompat.app.AppCompatActivity; 
 
/** 
* site activity entrance class 
*/ 
public class MainActivity extends AppCompatActivity { 
private static final String TAG = "MainActivity"; 
 
private SearchService searchService; 
private TextView resultTextView; 
private EditText queryInput; 
 
@Override 
protected void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState); 
setContentView(R.layout.activity_main); 
 
try { 
    searchService = SearchServiceFactory.create(this, URLEncoder.encode("your_api_key", "utf-8")); 
} catch (UnsupportedEncodingException e) { 
    Log.e(TAG, "encode apikey error"); 
} 
 
queryInput = findViewById(R.id.edit_text_text_search_query); 
resultTextView = findViewById(R.id.response_text_search); 
} 
}

Kotlin


package com.huawei.codelab.sitecodelab 
 
import android.os.Bundle 
import android.util.Log 
import android.widget.EditText 
import android.widget.TextView 
import androidx.appcompat.app.AppCompatActivity 
import androidx.fragment.app.FragmentActivity 
import com.huawei.hms.site.api.SearchService 
import com.huawei.hms.site.api.SearchServiceFactory 
import java.io.UnsupportedEncodingException 
import java.net.URLEncoder 
 
 
class MainActivity : AppCompatActivity() { 
    companion object { 
        private const val TAG = "MainActivity" 
    } 
 
    private lateinit var searchService: SearchService 
    private lateinit var resultTextView: TextView 
    private lateinit var queryInput: EditText 
 
    override fun onCreate(savedInstanceState: Bundle?) { 
        super.onCreate(savedInstanceState) 
        setContentView(R.layout.activity_main) 
 
        // Fixme: Please replace "API key" with your API KEY 
        try { 
            searchService = SearchServiceFactory.create(this, URLEncoder.encode("your_api_key", "utf-8")) 
        } catch (e: UnsupportedEncodingException) { 
            Log.e(FragmentActivity.TAG, "encode apikey error") 
        } 
 
        queryInput = findViewById(R.id.edit_text_text_search_query) 
        resultTextView = findViewById(R.id.response_text_search) 
    } 
}

创建TextSearchRequest对象，它是位置搜索的请求体。其中query是必选参数，其他是可选参数：
- query：搜索关键字。
- location：搜索结果偏向的经纬度。
- radius：搜索半径，单位：米。默认值是50000米，取值范围是[1, 50000]。
- poiType：返回地点的POI类型，取值范围请参见LocationType。
- hwPoiType：返回地点的华为POI类型，取值范围请参见HwLocationType，推荐使用该类型。
- countryCode：在指定的国家内搜索，采用ISO 3166-1 alpha-2。
- language：搜索结果的语种，取值范围请参见语种映射的语种代码。如果不传，优先使用query字段的语种，其次使用地点的当地语言。
- pageSize：每页返回的记录数。默认值是20，取值范围是[1, 20]。
- pageIndex：当前页数。默认值是1，取值范围是[1, 60]。
如果同时设置了poiType和hwPoiType，搜索结果优先满足hwPoiType。要求：pageIndex * pageSize <= 60

TextSearchRequest textSearchRequest = new TextSearchRequest();
textSearchRequest.setHwPoiTypeHwLocationType.TOWERR);
textSearchRequest.setQuery(queryInput.getText().toString());

调用textSearch接口，需传入上一步创建的TextSearchRequest和结果监听对象SearchResultListener，从回调的onSearchResult方法中获取结果，并展示地点信息。
Java


public void search(View view) { 
TextSearchRequest textSearchRequest = new TextSearchRequest(); 
textSearchRequest.setQuery(queryInput.getText().toString()); 
textSearchRequest.setHwPoiType(HwLocationType.TOWER); 
 
searchService.textSearch(textSearchRequest, new SearchResultListener<TextSearchResponse>() { 
    @Override 
    public void onSearchResult(TextSearchResponse textSearchResponse) { 
 
        StringBuilder response = new StringBuilder("\n"); 
        response.append("success\n"); 
        int count = 1; 
        AddressDetail addressDetail; 
        if (null != textSearchResponse) { 
            if (null != textSearchResponse.getSites()) { 
                for (Site site : textSearchResponse.getSites()) { 
                    addressDetail = site.getAddress(); 
                    response 
                        .append(String.format("[%s]  name: %s, formatAddress: %s, country: %s, countryCode: %s \r\n", 
                            "" + (count++), site.getName(), site.getFormatAddress(), 
                            (addressDetail == null ? "" : addressDetail.getCountry()), 
                            (addressDetail == null ? "" : addressDetail.getCountryCode()))); 
                } 
            } else { 
                response.append("textSearchResponse.getSites() is null!"); 
            } 
        } else { 
            response.append("textSearchResponse is null!"); 
        } 
        Log.d(TAG, "search result is : " + response); 
        resultTextView.setText(response.toString()); 
    } 
 
    @Override 
    public void onSearchError(SearchStatus searchStatus) { 
        Log.e(TAG, "onSearchError is: " + searchStatus.getErrorCode()); 
    } 
}); 
}

Kotlin


fun search(view: View?) { 
    val textSearchRequest = TextSearchRequest() 
    textSearchRequest.query = queryInput.text.toString() 
    textSearchRequest.hwPoiType = HwLocationType.TOWER 
    searchService.textSearch(textSearchRequest, object : SearchResultListener<TextSearchResponse> { 
        override fun onSearchResult(textSearchResponse: TextSearchResponse) { 
            val response = StringBuilder("\n") 
            response.append("success\n") 
            var count = 1 
            var addressDetail: AddressDetail 
            for (site in textSearchResponse.sites) { 
                addressDetail = site.address 
                response.append( 
                String.format( 
                    "[%s]  name: %s, formatAddress: %s, country: %s, countryCode: %s \r\n", 
                    "" + count++, site.name, site.formatAddress, 
                        if (addressDetail == null) "" else addressDetail.country, 
                        if (addressDetail == null) "" else addressDetail.countryCode 
                    ) 
                ) 
            } 
            Log.d(FragmentActivity.TAG, "search result is : $response") 
            resultTextView.text = response.toString() 
        } 
 
        override fun onSearchError(searchStatus: SearchStatus) { 
            Log.e(FragmentActivity.TAG, "onSearchError is: " + searchStatus.errorCode) 
        } 
    }) 
}

编译、加载、调试

使用Android Studio自带的Gradle编译工具，双击"installDebug"，即可安装Demo。

打开开发调试版本的位置服务App后，查询字符串已预置Eiffel Tower，点击"Search"，查看是否能获取到结果。

干得好，您已经成功完成了Codelab并学到了：

如何在开发者联盟中配置位置相关App。
如何从开发者联盟的Site Kit开发者文档获取Demo代码。
如何使用Android Studio集成位置服务SDK进行位置搜索功能开发。

更多关于位置服务的功能请参见位置服务指南文档。
您可以点击下载源码。

Code copied