지도 URL 또는 Places API를 사용하여 사용자를 Google 지도 장소 세부정보 및 경로로 안내

오늘날 위치 인식 환경에서 사용자는 장소 정보, 경로, 내비게이션에 원활하게 액세스할 수 있기를 기대합니다. 메신저 앱, 지역 컨텍스트 탐색 앱, 물류 및 운송 플랫폼, 여행 계획 도구, 부동산 등록 플랫폼 등 어떤 방법을 사용하든 사용자는 위치 세부정보를 빠르게 확인하거나 A에서 B로 가는 최적의 경로를 찾아야 하는 경우가 많습니다. 개발자는 자체 인앱 환경을 빌드할 수 있지만, 포괄적이고 익숙한 Google 지도 인터페이스를 활용하면 더 나은 환경을 제공할 수 있습니다.

원활한 사용자 환경을 위해서는 잘 구성된 Google 지도 URL이 필수적입니다. 잘못된 URL은 사용자를 잘못된 위치로 안내하거나, 구체적인 세부정보 대신 일반적인 지도 뷰를 표시하거나, 링크가 깨지는 등 이 환경을 저해합니다. 이로 인해 사용자는 불만을 느끼고 목표를 달성할 수 없습니다. 예를 들어 유효한 지도 URL이 있더라도 특정 비즈니스에 관한 세부정보를 기대하는 사용자가 관련 정보가 없는 일반 지도 뷰로 이동할 수 있습니다. 다음 예를 참조하시기 바랍니다. 

https://www.google.com/maps/search/?api=1&query=-33.8567%2C151.2152

이 지도 URL은 Google 지도를 열고 위도와 경도를 기반으로 위치를 표시하는 데 유효합니다. 하지만 사용자에게 특정 장소에 관한 세부정보를 제공하지는 않습니다.

위도와 경도만 사용하여 검색
위도와 경도만 사용하여 검색

정확한 URL을 통해 애플리케이션과 Google 지도를 원활하게 연결

Google 지도에서 장소 세부정보 페이지 열기
고유한 장소 이름이 포함된 지도 URL은 사용자를 Google 지도의 해당 장소 세부정보 페이지로 안내합니다

Google Maps Platform (GMP)에서는 정확한 URL을 구성하는 두 가지 기본 방법을 제공합니다. API 키가 필요한 Places API(New)와 무료이며 키가 필요하지 않은 지도 URL이 있습니다. 다음 솔루션은 다양한 시나리오와 사용 사례를 해결합니다.

GMP Places API(신규)는 특정 장소에 관한 포괄적인 정보 세트를 반환합니다. googleMapsUri 또는 googleMapsLinks 필드를 요청하면(필드 마스크에 지정) API 응답에 장소 객체가 포함됩니다. 이 객체에는 사전 형식화된 URL이 포함되어 있으며, 이 URL을 사용하여 Google 지도에서 장소 세부정보 보기와 같은 해당 보기를 직접 열 수 있습니다.

예:

장소 세부정보 요청

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: YOUR_API_KEY" \
-H "X-Goog-FieldMask: googleMapsUri,googleMapsLinks" \
https://places.googleapis.com/v1/places/ChIJ3S-JXmauEmsRUcIaWtf4MzE

장소 세부정보 응답:

{
    "googleMapsUri": "https://maps.google.com/?cid=3545450935484072529",
    "googleMapsLinks": {
        "directionsUri": "https://www.google.com/maps/dir//''/data=!4m7!4m6!1m1!4e2!1m2!1m1!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!3e0",
        "placeUri": "https://maps.google.com/?cid=3545450935484072529",
        "writeAReviewUri": "https://www.google.com/maps/place//data=!4m3!3m2!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!12e1",
        "reviewsUri": "https://www.google.com/maps/place//data=!4m4!3m3!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!9m1!1b1",
        "photosUri": "https://www.google.com/maps/place//data=!4m3!3m2!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!10e5"
    }
}

위 예시의 ChIJ3S-JXmauEmsRUcIaWtf4MzE은 시드니 오페라 하우스의 장소 ID입니다. 장소 ID는 Google 지역 정보 데이터베이스 및 Google 지도에 있는 장소를 고유하게 나타내는 텍스트 식별자입니다.

무료로 장소 ID 가져오기

프로그래매틱 방식으로 장소 ID를 검색하려면 Places API: Text Search(ID Only) 기능을 사용하면 됩니다. 장소 ID를 획득하는 데 비용이 들지 않는 방법입니다. 장소 ID 및 장소 API(신규) 요청에 대해 자세히 알아보세요.

Places API 텍스트 검색(ID만 해당) 요청:

curl -X POST -d '{"textQuery" : "Sydney Opera House"}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: places.id' \
'https://places.googleapis.com/v1/places:searchText'

Places API 텍스트 검색(ID만 해당) 응답:

{
  "places": [
    {
      "id": "ChIJ3S-JXmauEmsRUcIaWtf4MzE"
    }
  ]
}

사용자가 지도에서 관심 장소를 클릭하거나 탭할 때도 장소 ID를 가져올 수 있습니다. 클릭 가능한 관심 장소 아이콘(JavaScript, Android, iOS)에 대해 자세히 알아보기

구현

Places API를 사용하는 경우 개발자는 응답에서 googleMapsUri 또는 googleMapsLinks 필드를 추출하여 앱이 설치되지 않은 경우 Google 지도 앱 또는 브라우저에서 해당 뷰를 실행하는 데 사용할 수 있습니다.

기능 설명
directionsUri Google 지도를 열어 사용자의 현재 위치에서 이 장소까지의 경로를 표시하는 링크
placeUri 이 장소의 장소 세부정보 페이지를 Google 지도에서 여는 링크
writeAReviewUri 이 장소의 리뷰 작성 페이지로 Google 지도를 여는 링크
reviewsUri 이 장소의 리뷰 페이지로 Google 지도를 여는 링크
photosUri 이 장소의 사진 페이지로 Google 지도를 여는 링크

개발자 안내를 확인하고 지금 기능을 사용해 보세요.

지도 URL 활용

지도 URL을 사용하면 범용 교차 플랫폼 URL을 구성하여 Google 지도를 실행하고 검색하고 경로를 찾고 내비게이션을 실행하고 지도뷰 및 파노라마 이미지를 표시할 수 있습니다. URL 구문은 사용 중인 플랫폼과 관계없이 동일합니다. 지도 URL을 사용하는 데 Google API 키는 필요하지 않습니다.

사용 가능한 지도 작업은 다음과 같습니다.

  • 검색 기능은 Google 지도 앱을 실행하거나 앱이 설치되어 있지 않은 경우 브라우저에서 특정 장소의 핀을 표시하거나 일반 검색을 실행하고 지도를 실행하여 결과를 표시합니다.

  • 경로 기능은 Google 지도 앱을 실행하거나 앱이 설치되어 있지 않은 경우 브라우저에서 지점 간 경로를 표시하거나 휴대기기용 Google 지도에서 턴바이턴 내비게이션을 사용 설정합니다.

  • 스트리트 뷰 파노라마 기능을 사용하면 스트리트 뷰 이미지를 대화형 파노라마로 표시하는 뷰어를 실행할 수 있습니다.

GMP 지도 URL 개발자 문서를 방문하여 더 많은 기능과 예시를 살펴보세요.

여기에서는 지도 URL의 두 가지 주요 기능을 자세히 살펴보겠습니다.

  • Google 지도에 장소 세부정보 표시: 이 섹션에서는 Google 지도에 특정 위치의 세부정보를 표시하는 URL을 구성하는 방법을 설명합니다. 또한 장소 ID와 정확한 쿼리를 사용하여 이름이 고유하지 않은 장소를 사용하는 방법도 자세히 설명합니다.

  • 지도 URL을 사용하여 경로 제공: 이 섹션에서는 여러 경유지와 턴바이턴 내비게이션을 포함하여 위치 간 경로를 제공하는 URL을 만드는 방법을 설명합니다.

Google 지도에 장소 세부정보 표시

검색 함수는 장소 검색을 완료하기 위해 두 개의 매개변수(query(필수) 및 query_place_id(선택사항))를 사용합니다.

query 매개변수는 모든 검색 요청에 필수입니다. 장소 이름, 쉼표로 구분된 위도/경도 좌표 또는 일반 검색어를 허용합니다.

검색 URL 구조: 

https://www.google.com/maps/search/?api=1&parameters

시나리오 1: 고유한 장소 이름의 장소 세부정보 표시 

https://www.google.com/maps/search/?api=1&query=Sydney%20Opera%20House
 이 예에서는 장소 이름만 지정됩니다. 이 URL을 클릭하면 시드니 오페라 하우스의 세부정보 페이지가 열립니다.

Google 지도에서 장소 세부정보 페이지 열기
장소 이름 검색 및 장소 세부정보 표시

이제 고유하지 않은 이름이 있는 장소를 생각해 보겠습니다. 이 고유하지 않은 이름으로만 검색하면 어떻게 되나요? 다음 시나리오를 참고하세요.

시나리오 2: 고유하지 않은 장소 이름으로 장소 검색 

https://www.google.com/maps/search/?api=1&query=7-Eleven

장소 이름이 고유하지 않으므로 이 URL을 클릭하면 뷰포트 내에 있는 인근 7-Eleven 매장 목록이 열립니다. 그런 다음 사용자는 특정 매장을 선택하여 세부정보를 확인할 수 있습니다.

Google 지도에서 장소 목록 페이지 열기
고유하지 않은 이름을 검색하기 위한 장소 목록 페이지

위치 목록을 피하고 특정 세부정보 페이지에 직접 액세스하려면 더 정확한 방법을 사용하면 됩니다. 다음 예시를 참고하세요.

시나리오 3: 고유하지 않은 장소 이름의 장소 세부정보 표시

일반적인 장소 이름을 처리할 때는 간단한 이름 검색으로 위치 목록이 반환되는 경우가 많습니다. 특정 세부정보 페이지에 직접 연결하려면 다음 방법 중 하나를 사용하면 됩니다.

방법 1: 장소 이름과 주소를 사용한 정확한 쿼리 사용 

https://www.google.com/maps/search/?api=1&query=7-Eleven%2C37%20Swanston%20St%2C%20Melbourne%20Australia

이 URL에서 query 매개변수는 장소 이름, 주소 형식으로 지정됩니다. 이렇게 하면 검색 범위를 좁히고 원하는 위치로 직접 연결할 수 있습니다.

방법 2: 장소 ID 사용

장소 ID는 Google 지역 정보 데이터베이스 및 Google 지도에 있는 장소를 고유하게 나타냅니다. 

https://www.google.com/maps/search/?api=1&query=7-Elevan&query_place_id=ChIJGcmcg7ZC1moRAOacd3HoEwM

여기서 ChIJGcmcg7ZC1moRAOacd3HoEwM은 특정 장소의 고유한 장소 ID입니다. query 매개변수는 여전히 필요하지만 Google 지도에서 장소 ID를 찾을 수 없는 경우에만 사용됩니다.

시나리오 4: 위도 및 경도 좌표와 장소 ID를 사용하여 장소 세부정보 표시

장소 ID를 사용하면 Google 지도에 자세한 장소 정보가 표시됩니다.

https://www.google.com/maps/search/?api=1&query=-33.8567%2C151.2152&query_place_id=ChIJ3S-JXmauEmsRUcIaWtf4MzE
위도, 경도, 장소 ID를 사용하는 장소 세부정보 페이지
위도 및 경도와 장소 ID를 사용하는 장소 세부정보 페이지

비용 없이 장소 ID 가져오기

프로그래매틱 방식으로 장소 ID를 검색하려면 Places API: Text Search(ID Only) 기능을 사용하면 됩니다. 장소 ID를 획득하는 데 비용이 들지 않는 방법입니다. 장소 ID 및 장소 API(신규) 요청에 대해 자세히 알아보세요.

Places API 텍스트 검색(ID만 해당) 요청: 

curl -X POST -d '{"textQuery" : "Sydney Opera House"}'
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY'
-H 'X-Goog-FieldMask: places.id'
'https://places.googleapis.com/v1/places:searchText'

Places API 텍스트 검색(ID만 해당) 응답: 

{
  "places": [
    {
      "id": "ChIJ3S-JXmauEmsRUcIaWtf4MzE"
    }
  ]
}

사용자가 지도에서 관심 장소를 클릭하거나 탭할 때도 장소 ID를 가져올 수 있습니다. 클릭 가능한 관심 장소 아이콘(JavaScript, Android, iOS)에 대해 자세히 알아보기

결론

정확한 장소 세부정보를 제공하는 것은 긍정적인 경험을 위해 매우 중요합니다. 사용자가 올바른 장소 세부정보 페이지로 연결되도록 하려면 다음 권장 형식 중 하나를 사용하여 검색 URL을 구성하세요.

  • query=PLACE_NAME, ADDRESS
  • query=PLACE_NAME&query_place_id=PLACE_ID

특정 장소의 세부정보를 표시하는 것이 목표인 경우 query 매개변수에서 위도/경도 좌표만 사용하지 마세요. query=latitude,longitude, query=PLACE_NAME,latitude,longitude 또는 query=ADDRESS,latitude,longitude와 같은 형식은 원하는 장소 세부정보 페이지로 일관되게 연결되지 않습니다. 대신 위치의 위도와 경도가 표시됩니다.

지도 URL을 사용한 카테고리별 검색

카테고리 검색에서는 일반 검색어를 전달하면 Google 지도에서 지정한 위치 근처에서 기준에 맞는 등록정보를 찾으려고 시도합니다. 위치를 지정하지 않으면 Google 지도에서 현재 위치 주변의 등록정보를 찾으려고 시도합니다.

시나리오 1: 주변 장소 검색

https://www.google.com/maps/search/?api=1&query=Cafe%20near%20Sydney%20Opera%20House%20that%20are%20open%20now
카테고리 검색 - 주변 장소
카테고리 검색 - 주변 장소

지도 URL을 사용하여 경로 제공

경로 기능은 지도에서 지정된 두 개 이상의 지점 간 경로와 거리, 이동 시간을 표시합니다. 이를 통해 개발자는 제공된 경로를 더 세밀하게 제어할 수 있습니다. GMP의 지도 URL 길찾기 문서에서는 맞춤 길찾기를 위한 URL 구성에 관한 자세한 안내를 제공합니다.

Directions URL 구조: 

https://www.google.com/maps/dir/?api=1&parameters

시나리오 1: 사용자의 현재 위치에서 목적지까지의 최적 경로 찾기

https://www.google.com/maps/dir/?api=1&destination=Flinders%20Station%20Melbourne&travelmode=driving

이 URL은 Google 지도를 열고 사용자의 현재 위치에서 운전 경로를 표시합니다.

이 URL에서는 origin이 생략됩니다. origin이 생략되면 경로가 사용 가능한 경우 기기 위치와 같은 가장 관련성 높은 시작 위치로 기본 설정됩니다. 결과 지도에 원점을 입력할 수 있는 양식이 제공됩니다. 출발지와 목적지의 값은 장소 이름, 주소 또는 쉼표로 구분된 위도/경도 좌표일 수 있습니다.

travelmode은 선택적 매개변수입니다. 이동 수단을 정의합니다. 이 매개변수는 다음과 같이 설정할 수 있습니다.

  • 운전
  • 산책
  • 자전거
  • 오토바이
  • 대중교통

travelmode가 지정되지 않은 경우 Google 지도에는 지정된 경로 및/또는 사용자 환경설정에 가장 적합한 모드가 하나 이상 표시됩니다.

개발자는 origin_place_id 매개변수와 destination_place_id를 사용하여 장소 ID를 지정할 수도 있습니다. 장소 ID를 사용하면 올바른 장소로 연결될 가능성이 가장 높습니다.

비용 없이 장소 ID 가져오기

프로그래매틱 방식으로 장소 ID를 검색하려면 Places API: Text Search(ID Only) 기능을 사용하면 됩니다. 장소 ID를 획득하는 데 비용이 들지 않는 방법입니다. 장소 ID 및 장소 API(신규) 요청에 대해 자세히 알아보세요.

Places API 텍스트 검색(ID만 해당) 요청: 

curl -X POST -d '{"textQuery" : "Sydney Opera House"}'
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY'
-H 'X-Goog-FieldMask: places.id'
'https://places.googleapis.com/v1/places:searchText'

Places API 텍스트 검색(ID만 해당) 응답: 

{
  "places": [
    {
      "id": "ChIJ3S-JXmauEmsRUcIaWtf4MzE"
    }
  ]
}

사용자가 지도에서 관심 장소를 클릭하거나 탭할 때도 장소 ID를 가져올 수 있습니다. 클릭 가능한 관심 장소 아이콘(JavaScript, Android, iOS)에 대해 자세히 알아보기

사용자의 현재 위치에서 길찾기
사용자의 현재 위치에서 가는 길

시나리오 3: 내비게이션 세부 경로 제공

https://www.google.com/maps/dir/?api=1&destination=Flinders%20Station%20Melbourne&travelmode=driving&dir_action=navigate

URL에 dir_action=navigate를 설정하면 사용자의 현재 위치(기기 위치)를 사용할 수 있고 이를 출발지로 사용하는 경우 (명시적으로 제공되거나 출발지 매개변수가 생략될 때 암시적으로 사용됨) Google 지도가 경로 안내 모드로 실행됩니다. 그렇지 않으면 경로 미리보기가 표시됩니다.

dir_action=navigate가 설정되고 다음 조건이 충족되면 세부 경로 안내가 실행됩니다.

  • 출처가 지정되어 있으며 사용자의 현재 위치와 가까움
  • 출발지가 생략되고 사용자의 현재 위치를 사용할 수 있음

경로 미리보기는 다음과 같은 경우에 실행됩니다.

  • dir_action=navigate이 설정되지 않음
  • dir_action=navigate이 설정되고 출처가 지정되었으며 출처가 사용자의 현재 위치와 가깝지 않음
  • dir_action=navigate이 설정되고 출처가 생략되며 사용자의 현재 위치를 사용할 수 없음

Google 지도 웹과 같은 일부 Google 지도 제품에서는 내비게이션을 사용할 수 없으며, 일부 목적지 간에는 내비게이션을 사용할 수 없습니다. 이 경우 이 매개변수는 무시됩니다.

내비게이션 안내 경로 미리보기
세부 경로 안내
경로 미리보기

결론

지도 URL을 올바르게 구성하면 사용자가 필요한 정보를 빠르고 효율적으로 얻을 수 있습니다.

  • 항상 목적지를 지정하고 정확성을 보장하기 위해 가능한 경우 장소 ID를 사용하세요.

  • 목표가 즉각적인 탐색을 제공하는 것이라면 dir_action=navigate 매개변수를 포함하여 세부 경로 안내를 트리거하세요. 기기 위치를 사용할 수 있고 출발지로 사용되는 경우 (명시적으로 설정되거나 생략됨) 내비게이션이 사용자의 현재 위치에서 시작됩니다.

애플리케이션에 적합한 접근 방식 선택

Places API에서 제공하는 사전 형식화된 URL을 활용하거나 애플리케이션에서 지도 URL을 수동으로 구성하는 두 가지 기본 옵션이 있습니다. 각 접근 방식에는 장단점이 있습니다.

Places API:

  • 장소 세부정보 응답의 googleMapsUri 및 googleMapsLinks 필드는 바로 사용할 수 있는 URL을 제공합니다. 이렇게 하면 개발 시간이 단축되고 URL 형식 지정 시 오류 위험이 최소화됩니다.

  • 방향 구성에 대한 제어 기능이 적습니다. googleMapsLinks는 기본적인 길찾기를 제공하지만 경유지나 고급 맞춤설정은 지원하지 않습니다. 또한 턴바이턴 탐색을 직접 트리거하는 것이 상대적으로 덜 간단합니다.

지도 URL:

  • 유연성과 제어 기능을 강화합니다. 개발자는 URL을 구성하여 장소 세부정보를 표시하고, 경유지 추가, 이동 수단 지정, 단계별 안내 시작 등 경로의 다양한 측면을 구성할 수 있습니다.

  • URL 매개변수와 구조를 더 깊이 이해해야 합니다. 신중하게 수행하지 않으면 수동 구성 시 오류가 발생할 가능성이 커집니다.

UTM 매개변수를 사용하여 지도 URL 개선

개발자가 지도 URL을 통합하는 방식을 Google이 더 잘 이해하고 최적의 성능을 보장할 수 있도록 URL 구성에 UTM 추적 매개변수를 포함하는 것이 좋습니다. utm_source 및 utm_campaign 매개변수를 추가하면 Google에서 사용 패턴을 분석하고 지도 URL 제품을 개선할 수 있는 유용한 데이터를 제공할 수 있습니다.

utm_source 매개변수에는 애플리케이션 이름을 사용합니다. utm_campaign 매개변수는 'location_sharing', 'place_details_search', 'directions_request'와 같은 사용자의 의도된 작업을 반영해야 합니다.

예를 들어 UTM 매개변수가 있는 URL은 다음과 같습니다. 

https://www.google.com/maps/search/?api=1&query=Sydney+Opera+House&query_place_id=ChIJ3S-JXmauEmsRUcIaWtf4MzE&utm_source=YourAppName&utm_campaign=place_details_search

이러한 매개변수를 일관되게 사용하면 개선할 영역을 파악하고, 문제를 더 효과적으로 해결하며, 궁극적으로 모든 사용자에게 더 나은 환경을 제공할 수 있습니다.

다음 단계

추천 추가 자료:

참여자

주요 저자:

테레사 퀸 | Google Maps Platform 솔루션 엔지니어