Azure Maps Search Service를 사용하여 위치 검색

아티클
03/10/2024

Search Service는 개발자가 이름, 범주, 기타 지리적 정보를 사용하여 주소, 장소, 비즈니스 목록을 검색할 수 있도록 설계한 RESTful API 집합입니다. 관련 서비스는 기존의 지오코딩을 지원할 뿐만 아니라 위도와 경도를 바탕으로 주소와 교차로를 역으로 지오코딩할 수 있습니다. 검색에서 얻은 위도와 경도 값을 Route 및 Weather와 같은 다른 Azure Maps에서 매개 변수로 사용할 수 있습니다.

이 문서에서는 다음을 수행하는 방법을 보여줍니다.

Search Address를 사용하여 주소의 위도와 경도 좌표(지역 코드 주소 위치)를 요청합니다.
Fuzzy Search를 사용하여 주소나 POI(관심 지점)를 검색합니다.
역 주소 검색을 사용하여 좌표 위치를 주소로 변환합니다.
주소 역방향 교차로 검색을 사용하여 좌표 위치를 인간이 이해할 수 있는 교차로로 변환합니다. 이는 디바이스나 자산에서 GPS 피드를 수신하고 좌표가 어디에 있는지 알고 싶어하는 추적 애플리케이션에 가장 자주 필요합니다.

필수 조건

이 자습서에서는 Postman 애플리케이션을 사용하지만 다른 API 개발 환경을 선택할 수도 있습니다.

주소의 위도와 경도 요청(지오코딩)

이 섹션의 예에서는 검색 주소 가져오기를 사용하여 주소를 위도 및 경도 좌표로 변환합니다. 이 프로세스를 ‘지오코딩’이라고도 합니다. 응답은 좌표뿐만 아니라 거리, 우편 번호, 시, 국가/지역 정보와 같은 자세한 주소 속성까지 반환합니다.

팁

지오코딩할 주소 집합이 있는 경우 Post Search Address Batch를 사용하여 한 번의 요청으로 쿼리를 일괄 전송할 수 있습니다.

Postman 앱에서 새로 만들기를 선택하여 요청을 만듭니다. 새로 만들기 창에서 HTTP 요청을 선택합니다. 요청에 대한 요청 이름을 입력합니다.
작성기 탭에서 GET HTTP 메서드를 선택하고 다음 URL을 입력합니다. 이번 요청에서는 특정 주소 400 Braod St, Seattle, WA 98109를 검색합니다. 이 요청 및 이 문서에 언급된 기타 요청에 대해 {Your-Azure-Maps-Subscription-key}을(를) Azure Maps 구독 키로 바꿉니다.
```
https://atlas.microsoft.com/search/address/json?&subscription-key={Your-Azure-Maps-Subscription-key}&api-version=1.0&language=en-US&query=400 Broad St, Seattle, WA 98109
```
파란색 보내기 단추를 선택합니다. 응답 본문에는 단일 위치에 대한 데이터가 포함됩니다.
다음으로 가능한 위치가 두 개 이상인 주소를 검색합니다. Params 섹션에서 query 키를 400 Broad, Seattle로 변경합니다. 파란색 보내기 단추를 선택합니다.
그런 다음, query 키를 400 Broa로 설정해 봅니다.
보내기 단추를 선택합니다. 응답에는 여러 국가/지역의 결과가 포함됩니다. 결과를 사용자와 관련 있는 영역에 지오바이어싱하려면 항상 가능한 한 많은 위치 정보를 요청에 추가합니다.

유사 항목 검색

Fuzzy Search는 표준 단일 줄과 자유 형식 검색을 지원합니다. 검색 요청의 사용자 입력 유형을 모르는 경우 Azure Maps Search Fuzzy API를 사용하는 것이 좋습니다. 쿼리 입력은 전체 또는 부분 주소가 될 수 있습니다. POI(관심 지점) 토큰(예: POI 이름, POI 범주, 브랜드 이름)이 될 수도 있습니다. 또한 검색 결과의 관련성을 높이려면 좌표 위치와 반경을 사용하거나 경계 상자를 정의하여 쿼리 결과를 제한합니다.

팁

성능을 개선하고 비정상적인 결과를 줄이기 위해 대부분의 쿼리는 기본적으로 maxFuzzyLevel=1로 설정됩니다. maxFuzzyLevel 또는 minFuzzyLevel 매개 변수를 사용하여 퍼지 수준을 조정합니다. maxFuzzyLevel 및 선택적 매개 변수의 전체 목록에 대한 자세한 내용은 유사 항목 검색 URI 매개 변수를 참조하세요.

유사 항목 검색을 사용하여 주소 검색

이 섹션의 예에서는 Fuzzy Search를 사용하여 전 세계에서 피자를 검색한 다음 특정 국가/지역 범위를 검색합니다. 마지막으로 좌표 위치와 반경을 사용하여 특정 영역에 대한 검색 범위를 지정하고 반환되는 결과 수를 제한하는 방법을 보여 줍니다.

Important

결과를 사용자와 관련 있는 영역에 지오바이어싱하려면 항상 최대한 많은 위치 정보를 추가합니다. 자세한 내용은 검색 관련 모범 사례를 참조하세요.

Postman 앱에서 새로 만들기를 선택하여 요청을 만듭니다. 새로 만들기 창에서 HTTP 요청을 선택합니다. 요청에 대한 요청 이름을 입력합니다.
작성기 탭에서 GET HTTP 메서드를 선택하고 다음 URL을 입력합니다. 이 요청 및 이 문서에 언급된 기타 요청에 대해 {Your-Azure-Maps-Subscription-key}을(를) Azure Maps 구독 키로 바꿉니다.
```
https://atlas.microsoft.com/search/fuzzy/json?&api-version=1.0&subscription-key={Your-Azure-Maps-Subscription-key}&language=en-US&query=pizza
```
참고 항목

URL 경로의 json 특성은 응답 형식을 결정합니다. 이 문서에서는 사용 편의성과 가독성을 위해 json을 사용합니다. 지원되는 기타 응답 형식을 찾으려면 URI 매개 변수 참조 설명서에서 format 매개 변수 정의를 참조하세요.
보내기를 선택하고 응답 본문을 검토합니다.

“pizza”라는 모호한 쿼리 문자열을 사용하자 “pizza”(피자) 범주와 “restaurant”(음식점) 범주에 모두 속하는 POI(관심 지점) 결과 10개가 반환되었습니다. 각 결과는 해당 위치에 대한 주소, 위도와 경도 값, 뷰포트, 진입점과 같은 세부 정보를 포함합니다. 이제 이 쿼리에 대한 결과가 다양하며 참조 위치에 연결되지 않습니다.

다음 단계에서는 countrySet 매개 변수를 사용하여 애플리케이션의 검색 범위를 특정한 국가/지역으로 한정합니다. 지원되는 국가/지역의 전체 목록은 검색 범위를 참조하세요.
기본 동작은 전 세계를 검색하여 불필요할 수 있는 결과까지 반환하는 것입니다. 다음으로 미국에서만 피자를 검색해 보세요. Params 섹션에 countrySet 키를 추가하고 해당 값을 US로 설정합니다. countrySet 키를 US로 설정하면 결과가 미국으로 제한됩니다.

이제 결과는 국가 코드로 경계가 구분되며 쿼리는 미국의 피자 음식점을 반환합니다.
더욱 대상이 명확한 검색을 가져오려면 위도/경도 좌표 쌍의 범위를 검색할 수 있습니다. 다음 예에서는 시애틀 스페이스 니들의 위도/경도 좌표를 사용합니다. 400미터 반경 안에 있는 결과만 반환하고자 하기 때문에 radius 매개 변수를 추가합니다. 또한 limit 매개 변수를 추가하여 가장 가까운 5개의 피자 가게로 결과를 제한합니다.

Params 섹션에서 다음 키/값 쌍을 추가합니다.

키 값

lat 47.620525

lon -122.349274

radius 400

limit 5
보내기를 선택합니다. 응답에는 시애틀 스페이스 니들 근처의 피자 식당에 대한 결과가 포함됩니다.

키	값
lat	47.620525
lon	-122.349274
radius	400
limit	5

역방향 주소 검색을 사용하여 주소 검색

Get Search Address Reverse는 좌표를 사람이 읽을 수 있는 주소로 변환합니다. GPS 피드를 사용하여 특정 좌표점에 있는 주소를 검색하려는 애플리케이션에서 해당 API가 자주 사용됩니다.

Important

결과를 사용자와 관련 있는 영역에 지오바이어싱하려면 항상 최대한 많은 위치 정보를 추가합니다. 자세한 내용은 검색 관련 모범 사례를 참조하세요.

팁

역방향 지오코딩할 좌표 위치 집합이 있는 경우 Post Search Address Reverse Batch를 사용하여 한 번의 요청으로 쿼리를 일괄 전송할 수 있습니다.

이 예에서는 사용 가능한 몇 가지 선택적 매개 변수를 사용하여 역방향 검색을 수행하는 방법을 보여 줍니다. 선택적 매개 변수의 전체 목록은 역방향 검색 매개 변수를 참조하세요.

Postman 앱에서 새로 만들기를 선택하여 요청을 만듭니다. 새로 만들기 창에서 HTTP 요청을 선택합니다. 요청에 대한 요청 이름을 입력합니다.
작성기 탭에서 GET HTTP 메서드를 선택하고 다음 URL을 입력합니다. 이 요청 및 이 문서에 언급된 기타 요청에 대해 {Your-Azure-Maps-Subscription-key}을(를) Azure Maps 구독 키로 바꿉니다. 요청은 다음 URL과 같습니다.
```
https://atlas.microsoft.com/search/address/reverse/json?api-version=1.0&subscription-key={Your-Azure-Maps-Subscription-key}&language=en-US&query=47.591180,-122.332700&number=1
```
보내기를 선택하고 응답 본문을 검토합니다. 하나의 쿼리 결과가 표시됩니다. 응답에는 Safeco Field에 대한 주요 주소 정보가 포함됩니다.

그런 후 다음 키/값 쌍을 Params 섹션에 추가합니다.

키	값	반환
number	1	응답은 도로의 측면(왼쪽/오른쪽) 및 해당 번호에 대한 오프셋 위치를 포함할 수 있습니다.
returnSpeedLimit	true	해당 주소에서의 제한 속도를 반환합니다.
returnRoadUse	true	해당 주소에서의 도로 용도 유형을 반환합니다. 가능한 도로 용도 유형을 모두 확인하려면 도로 용도 유형을 참조하세요.
returnMatchType	true	일치 유형을 반환합니다. 가능한 값을 모두 확인하려면 역방향 주소 검색 결과를 참조하세요.

보내기를 선택하고 응답 본문을 검토합니다.
다음으로 entityType 키를 추가하고 해당 값을 Municipality로 설정합니다. entityType 키는 이전 단계의 returnMatchType 키를 재정의합니다. 지방자치단체에 대한 정보를 요청하고 있으므로 returnSpeedLimit 및 returnRoadUse도 제거해야 합니다. 가능한 엔터티 형식을 모두 확인하려면 엔터티 형식을 참조하세요.
보내기를 선택합니다. 해당 결과를 5단계에서 반환된 결과와 비교합니다. 이번에 요청된 엔터티 형식은 municipality이므로 응답에 주소 정보가 포함되어 있지 않습니다. 또한 반환된 geometryId를 사용하여 Azure Maps Get Search Polygon API를 통해 경계 다각형을 요청할 수 있습니다.

팁

이러한 매개 변수와 기타 매개 변수에 대한 자세한 내용은 역방향 검색 매개 변수를 참조하세요.

역방향 주소 교차로 검색을 사용하여 교차로 검색

이 예에서는 주소 좌표를 기준으로 교차로를 검색하는 방법을 보여 줍니다.

Postman 앱에서 새로 만들기를 선택하여 요청을 만듭니다. 새로 만들기 창에서 HTTP 요청을 선택합니다. 요청에 대한 요청 이름을 입력합니다.
작성기 탭에서 GET HTTP 메서드를 선택하고 다음 URL을 입력합니다. 이 요청 및 이 문서에 언급된 기타 요청에 대해 {Your-Azure-Maps-Subscription-key}을(를) Azure Maps 구독 키로 바꿉니다. 요청은 다음 URL과 같습니다.
```
https://atlas.microsoft.com/search/address/reverse/crossstreet/json?&api-version=1.0&subscription-key={Your-Azure-Maps-Subscription-key}&language=en-US&query=47.591180,-122.332700
```
보내기를 선택하고 응답 본문을 검토합니다. 응답에는 South Atlantic Street의 crossStreet 값이 포함되어 있습니다.

다음 단계

Azure Maps Search Service

Azure Maps Search Service 모범 사례