구글 Place API - Place AutoComplete

구글에는 많은 API가 있지만 본인은 Place API -그 중에서도 Place Auto Complete에 대해서 학습하였다.

영어공부하듯이 한줄한줄 번역하면서 많은 사람들에게 도움이 되었으면 좋겠습니다.

저 또한 블로그들을 통해서 많은 도움을 받은 것처럼!

 

구글의 원래 주소는 아래와 같습니다.

https://developers.google.com/maps/documentation/places/web-service/autocomplete

 

오늘도 즐코시작합시다.

 

---

Place Autocomplete serce는 place prediction을 리턴하는 서비스라고 합니다. request는 text string이나 geographic bound옵션입니다. 서비스는 text 기반검색에 autocomplete를 제공하도록 사용될 수 있다. (사업, 주소, 등의 장소를 반환함으로써)

 

 

---

Place autocomplete request

*Place autocomplete 서비스는 Place Api와 ApI Key share 그리고 Place Api의 부분이다.

너는 맵없이 Place autocomplete서비스를 이용할 수 있다. 만약에 맵을 보여줄거라면, 구글맵을 보여줘라. 맵없이 Place autocomplete 서비스로부터 예측들을 보여줄거라면, "powered by Google"로고를 검색 필드/ 결과에 보여줘야한다(Must).-꼭 지킵시다!

 

 

 

 

 

---

Place autocomplete는 전체 단어와 부분물자열을 매치하여 장소이름, 주소, plus code를 확인할 수 있다.  Application들은 그래서 유저타입으로 쿼리를 보낼 수 있다(즉각적인 예측을 제공하기 위하여)

 

리턴된 예상들(Place autocomplete 된 장소들)은 유저가 목표로하는 장소를 선택하는 것을 돕도록 디자인 되어있다. 너는 리턴된 어떤 장소라도 더 많은 정보를 얻기 위해 Place detailse request(-> 주소에 대한 상세정보를 볼 수 있는 API입니다.)를 보낼 수 있다.

 

Place autocomplete의 요청은 다음 폼의 http Url입니다.

 output을 설정하면 json 또는 xml로 출력이 설정됩니다.

 특정한 파라미터는 Place autocomplete 요청을 초기화하는데 필요합니다. Url 기본으로 모든 파라미터는 "&" 를 사용해서 구분됩니다. 

파라미터 리스트와 그들의 가능한 값들이 아래에 열거되어 있습니다.

 

 

 

 

---

필요한 파라미터

input 

검색하고자하는 텍스트 .  Place autocomplete 서비스는 이 String과 인지된 관련성에 근거로 결과를 정리하여 후보들을 매치시켜 줄 겁니다. 

다른 파라미터

컴포넌트들

너의 결과들에서 제한하고 싶은 장소들의 그룹, 현재 너는 최대 5개 나라의 필터가 가능하다. 국가는 ISO 3166-1 Alpah-2 호환 국가 코드라는 두 글자 문자로 전달되어야 합니다. 예) components=country:fr ->    너의 결과에서 프랑스로 제한을 둘 것이다. 다중 국가는 country:xx filter를 | 파이프 문자와 함께 사용해야한다. 예를들어 components=country:us|country:pr|country:vi|country:gu|country:mp 는 .US와 합병되지 않은 조직된 영토들로 너의 결과를 제한할 것이다. 

*만약에 니가 예상치 못한 결과를 국가코드를 사용했을 때 받았다면, 니가 국가들을 포함하는 코드가 너가 구분하고 싶은 국가들, 소속된 영토, 특별한 지역이 사용하는 코드인지를 확인해라. 너는 위키피디아에서 정보를 확인할 수 있다.

 

---

언어 

결과를 반환하는 언어입니다.

-서포트 되는 언어의 리스트를 보라. 구글은 종종 서포트하는 언어를 업데이트한다. 그래서 이 리스트는 전부가 아닐 지도 모른다.

*언어가 제공되지 않는 경우 API는 Accept-Language 헤더에 지정된 대로 기본 언어를 사용하려고 시도합니다.

*API는 사용자와 지역 주민 모두가 읽을 수 있는 거리 주소를 제공하기 위해 최선을 다한다. 그 목표를 달성하기 위해, 그것은 지역 언어로 된 거리 주소를 반환하고, 필요한 경우 사용자가 읽을 수 있는 스크립트로 번역하여 선호 언어를 관찰한다. 다른 모든 주소는 기본 설정 언어로 반환됩니다. 주소 구성요소는 모두 첫 번째 구성요소에서 선택한 동일한 언어로 반환됩니다.

*기본 설정 언어로 이름을 사용할 수 없는 경우, API는 가장 근접하게 매치되는 언어를 사용합니다.

*선호하는 언어는 반환되는 api 결과와 결과 순서에 작은 영향을 미친다. 지오코더는 언어에 따라서 다르게 해석한다. 

 

---

위치

장소 정보를 검색할 지점입니다. 이 값은 위도, 경도로 지정해야 합니다.

*텍스트 검색 API를 사용할 때 쿼리에 Market in Barcelona와 같은 명시적 위치가 포함된 경우 'location' 매개 변수가 재정의될 수 있습니다.

 

---

오프셋

위치, 

 

입력 항에서 서비스에서 예측(Place autocomplete)을 매치시키기 위해 사용하는 마지막 문자의 위치입니다. 예를 들어서 구글로 input하고 offset이 3이면, 서비스는 goo로 검색 될 것이다. 이 글자는 첫번째 단어에만 적용된다. 예를 들어서 google abc라고 하고 offset이 3이면 서비스는 goo abc로 검색해준다. offset이 제공되지 않았다면, 서비스는 전체 글자를 사용할 것입니다. 오프셋은 텍스트 캐럿의 위치로 설정 되어 집니다.

 

---

 

Origin

목적지까지의 직선거리를 계산할 원점입니다. 만약에 이 값을 빠뜨리면, 직선거리는 리턴되지 않습니다. 꼭 위도 경도로 지정해야합니다.

Radius

장소 표시를 return할 거리를 정의한다. 너는 위치 및 반지름 parameter를 전달하여 특정한 원을 편항할 지 모른다. 이렇게 하는 것은  장소서비스를 원 안에 보여주도록 지시한다. 정의된 영역 밖의 결과는 계속 표시 될 수 있다.

Radius는 자동적으로 기본 검색유형 및 other parameter에 따라 최대값으로 정해진다. 

*자동완성 : 5만 m

*키워드 또는 이름이 없을 때 - 

순위별=순번성(기본값): 50,000m
순위별=거리: 면적의 밀도에 따라 몇 킬로미터를 이동한다.

쿼리 자동 완성: 50,000m
텍스트 검색: 50,000m

---

sessiontoken

비용청구를 목적으로 자동 완성 세션을 식별하는 임의의 문자열입니다.

세션은 유저가 쿼리를 타이핑할 때 시작 된다. 그리고 그들이 장소를 선택할때, 상세주소를 콜할때 만들어진다. 각각의 세션은 다중 쿼리를 가지고 있고, 하나의 장소를 선택할 수 있다. API KEY는 같은 구글클라우드 콘솔프로젝트에 소속된 세션을 가지고 요청하는데 사용된다. 세 션이 한 번 종료 되면, 토큰은 더이상 not valid. 너의 앱은 각각의 세션에 새로운 토큰은 생성해야한다. 만약 세션토큰 파라미터를 빠뜨렸다면, 또는 만약 니가 세션토큰을 다시 사용한다면, 세션은 제공되지 않은 것처럼 청구됩니다.(각각 요청은 개별적으로 청구 됨)

 

우리는 아래의 가이드라인을 따르는 것을 추천한다. 

*세션토큰을 모든 세션에 사용할 것

*새로운 토큰을 세션마다 생성할 것, 4uuid 버전이 추천되어짐

* 모든 Place autocomplete와 상세장소요청 상세장소 요청에 사용하는 키가 동일한 클라우드 콘솔 프로젝트에 속하는지  확인할 것

*새로운 세션에는 고유의 세션을 통과하도록 할 것. 1개이상의 세션에 같은 토큰을 사용하는 것은 각각의 요청에 비용을 각각 청구하도록 할 것이다.(모아서 하나의 금액으로 내면 될 것을 각각 금액을 추가적으로 내야한다는 말임)

 

---

strictbounds

지역과 반지름으로 엄격하게 정이된 지역내의 places들을 반환한다. 이는 편향이라기보다는 제한으로, 사용자 입력과 일치하더라도 이 영역 외부의 결과는 반환되지 않습니다.

 

---

types

type parameter를 전달하여 Place Autocomplete 요청 결과를 특정한 type으로 제한할 수 있다. 

그 매개변수는(types) 아래의 supported types에 아래에 나열한 대로 type 또는 type collection을 지정합니다. 아무것도 지정하지 않으면 , 모든 유형이 반환됩니다. 보통의 경우 싱글 type이 허용 된다. 예외적으로 geocode와 establishment type을 섞을 수 있지만 유형을 지정하지 않는 것과 같은 효과가 있다. 제공되는 유형은 아래와 같다.

* geocode 는  the Place Autocomplete service가  business 결과 대신 geocoding 결과만 반환하도록 설정한다. 보편적으로 너는 이 요청을 사용해서 지정된 위치가 명확하지 않은 결과를 명확하게 할 수 있다.

* address는 Place Autocomplete service에 정확한 주소로 지오코딩 결과만 반환하도록 지시합니다. 보편적으로 사용자가 완전히 지정된 주소를 찾을 것을 알고 있을 때 이 요청을 사용합니다.

*establishment는  the Place Autocomplete service가 비지니스 결과만 반환하도록 해줍니다.

*(지역) 유형 컬렉션은 장소 서비스에 다음 유형과 일치하는 결과를 반환합니다.

*locality
*sublocality
*postal_code
*country
*administrative_area_level_1
*administrative_area_level_2

*(cities) type 컬렉션은 장소 서비스에 지역성 또는 administration_area_level_3과 일치하는 결과를 반환하도록 지시합니다.

 

 

---

결과에서 특히 관심 있는 요소는 place_id 요소이며, 별도의 쿼리를 통해 장소에 대한 자세한 정보를 요청하는 데 사용할 수 있습니다. 장소 세부사항 요청을 참조하십시오.

 

 

XML 응답은 두 가지 유형의 하위 요소를 가진 단일 <AutocompletionResponse> 요소로 구성됩니다.

*단일 <status> 요소는 요청에 대한 메타데이터를 포함합니다. 아래 상태 코드를 참조하십시오.
*각각 한 place에 대한 정보를 포함하는 0개 이상의 <prediction> 요소. 이러한 결과에 대한 자세한 내용은  Place Autocomplete Results 결과 정보를 참조하십시오. 장소 API는 최대 5개의 결과를 반환합니다.

애플리케이션에 xml이 필요하지 않는 한 기본 출력 플래그로 json을 사용하는 것이 좋습니다. XML 트리를 처리하려면 적절한 노드와 요소를 참조할 수 있도록 주의해야 합니다. XML 처리에 대한 도움말은 XPath를 사용하여 XML 처리를 참조하십시오.

 

그 다음 조금 필요 없어보이는 부분은 중략..

 

 

---

Place Autocomplete optimization

This section describes best practices to help you make the most of the Place Autocomplete service.

Here are some general guidelines:

• The quickest way to develop a working user interface is to use the Maps JavaScript API Autocomplete widget, Places SDK for Android Autocomplete widget, or Places SDK for iOS Autocomplete UI control
• Develop an understanding of essential Place Autocomplete data fields from the start.
• Location biasing and location restriction fields are optional but can have a significant impact on autocomplete performance.
• Use error handling to make sure your app degrades gracefully if the API returns an error.
• Make sure your app handles when there is no selection and offers users a way to continue.

Place Autocomplete 최적화

이 세션은 대부분의 Place Autocomplete 서비스를 너가 만드는데 도움을 주기 위한 best practice이다.

여기 몇가지 일반적인 가이드라인이 있다.

 

*작동하는 사용자 인터페이스를 개발하는 가장 빠른 방법은 지도 JavaScript API 자동 완성 위젯, Places SDK for Android 자동 완성 위젯 또는 Places SDK for iOS 자동 완성 UI 컨트롤을 사용하는 것입니다.

* 처음부터 Place Autocomplete 필수 필드를 이해합니다.

*위치 구분 및 위치 제한 필드는 선택사항이지만 자동 완성 성능에 상당한 영향을 미칠 수 있습니다.

*api가 error를 반환할 경우 에러 핸들링을 사용하여 앱의 성능을 강화하도록 하세요.

*선택사항이 없을 때 앱이 처리하고 사용자가 계속할 수 있는 방법을 제공하는지 확인하십시오.

 

 

---

Performance best practices

The following guidelines describe ways to optimize Place Autocomplete performance:

다음 가이드라인은 Place Autocomplete 성능을 최적화하는 방법을 설명한다.

• Add country restrictions, location biasing, and (for programmatic implementations) language preference to your Place Autocomplete implementation. Language preference is not needed with widgets since they pick language preferences from the user's browser or mobile device.
• 국가 제한, 위치구분, 언어환경설정을 추가합니다. 위젯은 사용자의 브라우저 또는 모바일 장치에서 언어 환경설정을 선택하므로 언어 환경설정이 필요하지 않습니다.
• If Place Autocomplete is accompanied by a map, you can bias location by map viewport.
• 만약에 Place Autocomplete가 지도와 동반되면, 너는 맵 뷰포트로 장소를 편향할 수 있다.
• In situations when a user does not choose one of the Autocomplete predictions, generally because none of those predictions are the desired result-address, you can re-use the original user input to attempt to get more relevant results:
• 유저가  Autocomplete predictions 중 하나를 선택하지 않은 경우, 일반적으로 그 중 아무런 예상장소가 목적했던 결과 장소가 아니기 때문이라, 원래 사용자 입력을 다시 사용하여 보다 적절한 결과를 얻을 수 있습니다.
  • If you expect the user to enter only address information, re-use the original user input in a call to the Geocoding API.
  • 사용자가 주소 정보만 입력하도록 하려면 Geocoding API 호출에서 원래 사용자 입력을 다시 사용하십시오.
  • If you expect the user to enter queries for a specific place by name or address, use a Find Place request. If results are only expected in a specific region, use location biasing.
  • 사용자가 이름 또는 주소로 특정 장소에 대한 질의를 입력할 것으로 예상할 경우, Find Place request.을 사용하십시오. 특정 지역에서만 결과가 예상되는 경우 location biasing을 사용합니다.
  Other scenarios when it's best to fall back to the Geocoding API include:
  -지오코딩 API로 되돌리는 것이 가장 좋은 다른 시나리오는 다음과 같습니다. 
  • Users inputting subpremise addresses in countries other than Australia, New Zealand, or Canada. For example, the US address "123 Bowdoin St #456, Boston MA, USA" is not supported by Autocomplete. (Autocomplete supports subpremise addresses only in Australia, New Zealand, and Canada. Supported address formats in these three countries include "9/321 Pitt Street, Sydney, New South Wales, Australia" or "14/19 Langana Avenue, Browns Bay, Auckland, New Zealand" or "145-112 Renfrew Dr, Markham, Ontario, Canada".)
  • 호주, 뉴질랜드 또는 캐나다 이외의 국가에서 하위 사이트 주소를 입력하는 사용자. 예를 들어, 미국 주소 "123 Bowdoin St #456, 보스턴 MA, USA"는 자동 완성에서 지원되지 않습니다. 자동 완성 기능은 호주, 뉴질랜드 및 캐나다에서만 하위 사이트 주소를 지원합니다. 이 세 국가에서 지원되는 주소 형식은 "9/321 피트 스트리트, 시드니, 뉴사우스웨일스, 오스트레일리아", "14/19 랭가나 애비뉴, 브라운스 베이, 오클랜드, 뉴질랜드", "145-112 렌프루 닥터, 마컴, 온타리오, 캐나다" 등이다.
  •  뉴욕시의 "23-30번가 29번가 퀸스"나 하와이의 카우아이 섬의 "47-380 카메하메하 휘"와 같은 도로 구간 접두사를 사용하여 주소를 입력하는 사용자

Location biasing

You may bias results to a specified circle by passing a location and a radius parameter. This instructs the Place Autocomplete service to prefer showing results within that circle. Results outside of the defined area may still be displayed. You can use the components parameter to filter results to show only those places within a specified country.

위치 및 반지름 매개변수를 전달하여 결과를 지정된 원으로 편향할 수 있습니다. the Place Autocomplete 서비스가 해당 원 내에 결과를 표시하는 것을 선호하도록 지시합니다. 정의된 영역을 벗어난 결과도 표시될 수 있습니다. 구성요소 매개변수를 사용하여 결과를 필터링하여 지정된 국가 내의 장소만 표시할 수 있습니다.

Tip: Establishment results generally do not rank highly enough to show in results when the search area is large. If you want establishments to appear in mixed establishment/geocode results, you can specify a smaller radius. Alternatively, use types=establishment to restrict results to establishments only.

팁: 설정 결과는 일반적으로 검색 영역이 클 때 결과에 표시될 만큼 순위가 높지 않습니다. 혼합 설정/지리코드 결과에 설비가 나타나도록 하려면 더 작은 반지름을 지정할 수 있습니다. 또는 type=설치를 사용하여 결과를 설비로만 제한할 수 있습니다.

Location restrict (장소 제한)

You may also restrict results to the region defined by location and a radius parameter, by adding the strictboundsparameter. This instructs the Place Autocomplete service to return only results within that region.

엄격한 경계 매개 변수를 추가하여 위치 및 반지름 파라미터로 정의된 영역으로 결과를 제한할 수도 있습니다. 이렇게 하면 Place Autocomplete service가 해당 영역 내의 결과만 반환하도록 지시합니다.