Android용 Google 지도 앱에서는 디스플레이, 검색, 내비게이션 또는 스트리트 뷰 모드로 Google 지도를 실행하는 데 사용할 수 있는 여러 인텐트를 표시합니다. 앱에 지도를 삽입하려면 Google Maps Android API 시작 가이드를 참고하세요.
개요
인텐트를 사용하면 Intent
객체에서 실행하려는 간단한 작업 (예: '지도 표시' 또는 '공항까지의 경로 표시')을 설명하여 다른 앱에서 활동을 시작할 수 있습니다. Android용 Google 지도 앱은 다양한 인텐트를 지원하여 Google 지도 앱을 실행하고 4가지 작업 중 하나를 실행할 수 있습니다.
- 특정 위치 및 확대/축소 수준에서 지도를 표시합니다.
- 위치나 장소를 검색하여 지도에 표시합니다.
- 한 위치에서 다른 위치로의 길찾기를 요청합니다. 길찾기는 세 가지 이동 모드(운전, 도보, 자전거)에 대해 반환될 수 있습니다.
- Google 스트리트 뷰에 파노라마 이미지를 표시합니다.
이 페이지에서는 Android용 Google 지도 앱에서 사용할 수 있는 인텐트를 설명합니다. 인텐트 및 인텐트 필터 또는 Android 플랫폼에 공통되는 인텐트에 관한 자세한 내용은 Android 개발자 문서를 참고하세요.
인텐트 요청
인텐트가 포함된 Google 지도를 실행하려면 먼저 Intent
객체를 만들어 작업의 동작과 URI, 패키지를 지정해야 합니다.
- 작업: 모든 Google 지도 인텐트는 보기 작업(
ACTION_VIEW
)으로 호출됩니다. - URI: Google 지도 인텐트는 원하는 작업을 지정하는 URL로 인코딩된 데이터와 그 작업을 실행할 데이터를 함께 사용합니다.
- 패키지:
setPackage("com.google.android.apps.maps")
를 호출하면 Android용 Google 지도 앱에서 인텐트를 처리합니다. 패키지가 설정되지 않으면Intent
를 처리할 수 있는 앱이 시스템에서 결정됩니다. 여러 앱을 사용할 수 있는 경우 사용자에게 어떤 앱을 사용할지 묻는 메시지가 표시될 수 있습니다.
Intent
를 만든 후 다양한 방법으로 시스템에 관련 앱을 실행하도록 요청할 수 있습니다. 일반적인 메서드는 Intent
를 startActivity()
메서드에 전달하는 것입니다. 시스템에서 필요한 앱(이 경우에는 Google 지도)을 실행하고 해당 Activity
를 시작합니다.
자바
// Create a Uri from an intent string. Use the result to create an Intent. Uri gmmIntentUri = Uri.parse("google.streetview:cbll=46.414382,10.013988"); // Create an Intent from gmmIntentUri. Set the action to ACTION_VIEW Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri); // Make the Intent explicit by setting the Google Maps package mapIntent.setPackage("com.google.android.apps.maps"); // Attempt to start an activity that can handle the Intent startActivity(mapIntent);
Kotlin
// Create a Uri from an intent string. Use the result to create an Intent. val gmmIntentUri = Uri.parse("google.streetview:cbll=46.414382,10.013988") // Create an Intent from gmmIntentUri. Set the action to ACTION_VIEW val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri) // Make the Intent explicit by setting the Google Maps package mapIntent.setPackage("com.google.android.apps.maps") // Attempt to start an activity that can handle the Intent startActivity(mapIntent)
시스템이 인텐트에 응답할 수 있는 앱을 식별하지 못하면 앱이 다운될 수 있습니다. 따라서 사용자에게 이러한 인텐트 중 하나를 제공하기 전에 먼저 수신 애플리케이션이 설치되어 있는지 확인해야 합니다.
앱이 인텐트를 수신할 수 있는지 확인하려면 Intent
객체에서 resolveActivity()
를 호출합니다. 결과가 null이 아니면 인텐트를 처리할 수 있는 앱이 하나 이상 있는 것이므로 startActivity()
를 호출해도 안전합니다.
결과가 null
이면 인텐트를 사용해서는 안 되며 가능한 경우 인텐트를 호출하는 기능을 사용 중지해야 합니다.
자바
if (mapIntent.resolveActivity(getPackageManager()) != null) { ... }
Kotlin
mapIntent.resolveActivity(packageManager)?.let { ... }
예를 들어, 샌프란시스코의 지도를 표시할 때 다음 코드를 사용할 수 있습니다.
자바
Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194"); Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri); mapIntent.setPackage("com.google.android.apps.maps"); if (mapIntent.resolveActivity(getPackageManager()) != null) { startActivity(mapIntent); }
Kotlin
val gmmIntentUri = Uri.parse("geo:37.7749,-122.4194") val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri) mapIntent.setPackage("com.google.android.apps.maps") mapIntent.resolveActivity(packageManager)?.let { startActivity(mapIntent) }
URL 인코딩 쿼리 문자열
Google Maps 인텐트에 전달되는 모든 문자열은 URI 인코딩되어야 합니다. 예를 들어 '첫 번째 및 파이크, 시애틀' 문자열은 1st%20%26%20Pike%2C%20Seattle
여야 합니다.
문자열 내의 공백은 %20으로 인코딩하거나 더하기 부호(+)로 대체할 수 있습니다.
android.net.Uri
parse()
메서드를 사용하여 문자열을 인코딩할 수 있습니다.
예를 들면 다음과 같습니다.
자바
Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4192?q=" + Uri.encode("1st & Pike, Seattle"));
Kotlin
val gmmIntentUri = Uri.parse("geo:37.7749,-122.4192?q=" + Uri.encode("1st & Pike, Seattle"))
지도 표시
geo:
인텐트를 사용하여 지정된 위치와 확대/축소 수준으로 지도를 표시합니다.
geo:latitude,longitude?z=zoom
매개변수
latitude
및longitude
는 지도의 중심점을 설정합니다.z
는 지도의 초기 확대/축소 수준을 선택적으로 설정합니다. 허용되는 값의 범위는 0 (전 세계)에서 21 (개별 건물)까지입니다. 상한은 선택한 위치에서 사용 가능한 지도 데이터에 따라 달라질 수 있습니다.
예
자바
// Creates an Intent that will load a map of San Francisco Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194"); Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri); mapIntent.setPackage("com.google.android.apps.maps"); startActivity(mapIntent);
Kotlin
// Creates an Intent that will load a map of San Francisco val gmmIntentUri = Uri.parse("geo:37.7749,-122.4194") val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri) mapIntent.setPackage("com.google.android.apps.maps") startActivity(mapIntent)
위치 검색
이 인텐트를 사용하여 지정된 뷰포트 내에 검색 쿼리를 표시합니다. 쿼리에 단일 결과가 있는 경우 이 인텐트를 사용하여 명소, 비즈니스, 지형지물, 마을 등 특정 장소 또는 주소에 핀을 표시할 수 있습니다.
geo:latitude,longitude?q=query geo:0,0?q=my+street+address geo:0,0?q=latitude,longitude(label)
매개변수
지도를 표시하는 데 사용되는 매개변수 외에 Google 검색에서는 다음 매개변수를 지원합니다.
q
는 지도에서 강조표시할 장소를 정의합니다.q
매개변수는 모든 검색 요청에 필요합니다. 위치를 장소 이름이나 주소로 허용합니다. 문자열은 URL 인코딩되어야 하므로 'City Hall, New York, NY'와 같은 주소는 City+Hall,New+York,NY로 변환되어야 합니다.label
를 사용하면 지도에서 식별된 장소에 맞춤 라벨을 설정할 수 있습니다.label
를 문자열로 지정해야 합니다.
범주형 검색
일반 검색어를 전달하면 Google 지도에서 지정된 경도/위도 근처에 위치를 찾습니다. 위치를 지정하지 않으면 Google 지도에서 주변 목록을 찾습니다. 예를 들면 다음과 같습니다.
자바
// Search for restaurants nearby Uri gmmIntentUri = Uri.parse("geo:0,0?q=restaurants"); Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri); mapIntent.setPackage("com.google.android.apps.maps"); startActivity(mapIntent); // Search for restaurants in San Francisco Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194?q=restaurants"); Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri); mapIntent.setPackage("com.google.android.apps.maps"); startActivity(mapIntent);
Kotlin
// Search for restaurants nearby val gmmIntentUri = Uri.parse("geo:0,0?q=restaurants") val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri) mapIntent.setPackage("com.google.android.apps.maps") startActivity(mapIntent) // Search for restaurants in San Francisco val gmmIntentUri = Uri.parse("geo:37.7749,-122.4194?q=restaurants") val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri) mapIntent.setPackage("com.google.android.apps.maps") startActivity(mapIntent)
쿼리 문자열과 함께 확대/축소 매개변수를 지정하여 검색결과를 추가로 편중할 수 있습니다. 아래 예에서 확대/축소 10을 추가하면 근처가 아닌 도시 수준에서 식당을 찾으려고 시도합니다.
자바
Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194?z=10&q=restaurants"); Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri); mapIntent.setPackage("com.google.android.apps.maps"); startActivity(mapIntent);
Kotlin
val gmmIntentUri = Uri.parse("geo:37.7749,-122.4194?z=10&q=restaurants") val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri) mapIntent.setPackage("com.google.android.apps.maps") startActivity(mapIntent)
위치 검색
특정 주소를 검색하면 그 장소에 핀을 표시합니다.
자바
Uri gmmIntentUri = Uri.parse("geo:0,0?q=1600 Amphitheatre Parkway, Mountain+View, California"); Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri); mapIntent.setPackage("com.google.android.apps.maps"); startActivity(mapIntent);
Kotlin
val gmmIntentUri = Uri.parse("geo:0,0?q=1600 Amphitheatre Parkway, Mountain+View, California") val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri) mapIntent.setPackage("com.google.android.apps.maps") startActivity(mapIntent)
위 예에서는 0
, 0
의 lat/lng를 설정했지만 주소를 쿼리 문자열로 전달합니다. 매우 특정한 위치를 검색할 때 위도와 경도는 필요하지 않습니다. 하지만 정확한 주소를 모르는 경우 좌표를 지정하여 검색 결과를 상세 검색할 수 있습니다. 예를 들어 'Main Street'로 주소를 검색하면 너무 많은 결과가 반환됩니다.
자바
// Searching for 'Main Street' will return too many results Uri gmmIntentUri = Uri.parse("geo:0,0?q=101+main+street");
Kotlin
// Searching for 'Main Street' will return too many results val gmmIntentUri = Uri.parse("geo:0,0?q=101+main+street")
인텐트 URI에 lat/lng를 추가하면 결과가 특정 영역으로 편중됩니다.
자바
// Searches for 'Main Street' near San Francisco Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194?q=101+main+street"); Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri); mapIntent.setPackage("com.google.android.apps.maps"); startActivity(mapIntent);
Kotlin
// Searches for 'Main Street' near San Francisco val gmmIntentUri = Uri.parse("geo:37.7749,-122.4194?q=101+main+street") val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri) mapIntent.setPackage("com.google.android.apps.maps") startActivity(mapIntent)
검색에서 단일 값을 반환한다는 것을 알고 있는 경우 라벨(선택사항)을 전달할 수 있습니다. 라벨은 문자열로 지정해야 하며 지도 마커 아래에 표시됩니다. 라벨은 q
가 경도/위도 좌표로 지정될 때만 사용할 수 있습니다.
자바
// Display a label at the location of Google's Sydney office Uri gmmIntentUri = Uri.parse("geo:0,0?q=Google+Sydney@-33.8666,151.1957"); Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri); mapIntent.setPackage("com.google.android.apps.maps"); startActivity(mapIntent);
Kotlin
// Display a label at the location of Google's Sydney office val gmmIntentUri = Uri.parse("geo:0,0?q=-33.8666,151.1957(Google+Sydney)") val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri) mapIntent.setPackage("com.google.android.apps.maps") startActivity(mapIntent)
상세 주소 또는 위도/경도의 대안으로 플러스 코드를 사용하여 알려진 위치에 핀을 표시할 수도 있습니다.
자바
// Display the location of Google, San Francisco using a global plus code. Uri gmmIntentUri = Uri.parse("http://plus.codes/849VQJQ5+XX"); // Equivalently, define the same location using a local plus code gmmIntentUri = Uri.parse("https://plus.codes/QJQ5+XX,San%20Francisco"); // Construct and use the Intent as in the examples above
Kotlin
// Display the location of Google, San Francisco using a global plus code. var gmmIntentUri = Uri.parse("http://plus.codes/849VQJQ5+XX") // Equivalently, define the same location using a local plus code gmmIntentUri = Uri.parse("https://plus.codes/QJQ5+XX,San%20Francisco") // Construct and use the Intent as in the examples above
세부 경로 안내 내비게이션 시작
이 인텐트를 사용하여 지정된 주소 또는 좌표에 대한 세부 경로 안내를 사용하여 Google 지도 내비게이션을 실행합니다. 경로는 항상 사용자의 현재 위치에서 가져옵니다.
google.navigation:q=a+street+address google.navigation:q=latitude,longitude
매개변수
q
: 탐색 검색의 엔드포인트를 설정합니다. 이 값은 위도, 경도 좌표 또는 쿼리 형식의 주소일 수 있습니다. 결과를 두 개 이상 반환하는 쿼리 문자열인 경우 첫 번째 결과가 선택됩니다.mode
는 교통수단을 설정합니다. 모드는 선택사항이며 다음 중 하나로 설정할 수 있습니다.- 운전을 위한
d
(기본값) - 자전거로
b
이동 - 오토바이로
l
이용 - 도보:
w
- 운전을 위한
avoid
는 경로에서 피해야 할 지형지물을 설정합니다. 선택사항은 선택사항이며 다음 중 하나 이상으로 설정할 수 있습니다.- 유료도로의 경우
t
- 고속도로의 경우
h
- 페리:
f
- 유료도로의 경우
예
아래 Intent
는 오스트레일리아 시드니 타롱가 동물원의 세부 경로 안내 내비게이션을 요청합니다.
자바
Uri gmmIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia"); Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri); mapIntent.setPackage("com.google.android.apps.maps"); startActivity(mapIntent);
Kotlin
val gmmIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia") val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri) mapIntent.setPackage("com.google.android.apps.maps") startActivity(mapIntent)
통행료를 지불하거나 페리를 타지 않으려면 해당 경로를 우회하는 경로를 요청할 수 있습니다.
자바
Uri gmmIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&avoid=tf"); Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri); mapIntent.setPackage("com.google.android.apps.maps"); startActivity(mapIntent);
Kotlin
val gmmIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&avoid=tf") val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri) mapIntent.setPackage("com.google.android.apps.maps") startActivity(mapIntent)
운동을 좀 하고 싶다면 대신 자전거 경로를 요청하시면 됩니다.
자바
Uri gmmIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&mode=b"); Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri); mapIntent.setPackage("com.google.android.apps.maps"); startActivity(mapIntent);
Kotlin
val gmmIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&mode=b") val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri) mapIntent.setPackage("com.google.android.apps.maps") startActivity(mapIntent)
전동 이륜차를 타고 싶다면 자동차로 이용할 수 없는 좁은 도로와 트레일이 경로에 포함되도록 요청할 수 있습니다. 아래 intent
는 인도의 경로를 반환합니다.
자바
Uri gmmIntentUri = Uri.parse("google.navigation:q=Connaught+Place,+New+Delhi,Delhi&mode=l"); Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri); mapIntent.setPackage("com.google.android.apps.maps"); startActivity(mapIntent);
Kotlin
val gmmIntentUri = Uri.parse("google.navigation:q=Connaught+Place,+New+Delhi,Delhi&mode=l") val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri) mapIntent.setPackage("com.google.android.apps.maps") startActivity(mapIntent)
스트리트 뷰 파노라마 표시
google.streetview
인텐트를 사용하여 Google 스트리트 뷰를 실행합니다. Google 스트리트 뷰는 커버리지 영역 전체에서 지정된 위치에서 파노라마 뷰를 제공합니다.
사용자 제공 포토스피어 및 스트리트 뷰 특별 컬렉션도 사용할 수 있습니다.
google.streetview:cbll=latitude,longitude&cbp=0,bearing,0,zoom,tilt google.streetview:panoid=id&cbp=0,bearing,0,zoom,tilt
매개변수
모든 google.streetview
URI에는 cbll
또는 panoid
매개변수가 포함되어야 합니다.
cbll
에서는 위도와 경도를 쉼표로 구분된 값(46.414382,10.013988
)으로 허용합니다. 앱에서 이 위치에서 가장 가까운 곳에서 찍은 파노라마를 표시합니다. 스트리트 뷰 이미지는 주기적으로 갱신되므로 사진이 매번 약간 다른 위치에서 촬영될 수 있으므로 이미지가 업데이트될 때 내 위치가 다른 파노라마에 스냅될 수 있습니다.panoid
는 특정한 파노라마 ID입니다.panoid
와cbll
가 모두 지정된 경우 Google 지도에서 파노라마 ID를 사용합니다. Android 앱은StreetViewPanoramaLocation
객체에서 파노라마 ID를 사용할 수 있습니다.cbp
은 카메라의 초기 방향을 조정하는 매개변수입니다(선택사항).cbp
매개변수는 쉼표로 구분된 값 5개를 사용하며 모두 선택사항입니다. 가장 중요한 값은 방위, 확대/축소, 기울기를 각각 설정하는 두 번째, 네 번째 및 다섯 번째 값입니다. 첫 번째와 세 번째 값은 지원되지 않으며0
로 설정해야 합니다.bearing
: 카메라의 북쪽에서 도 단위로 시계 방향의 나침반 방향을 나타냅니다. 정북쪽은 0, 동쪽은 90, 남쪽은 180, 서쪽은 270입니다. 방위에 전달된 값은 래핑됩니다. 즉, 0°, 360°, 720° 모두 동일한 방향을 가리킵니다. 방위는 쉼표로 구분된 5개의 값 중 두 번째로 정의됩니다.zoom
: 카메라의 확대/축소 수준을 설정합니다. 기본 확대/축소 수준은 0으로 설정됩니다. 1의 확대/축소는 2배로 확대됩니다. 확대/축소는 0과 현재 파노라마의 최대 확대/축소 수준 사이에 고정됩니다. 즉, 이 범위를 벗어나는 모든 값은 범위 내에서 가장 가까운 극단으로 설정됩니다. 예를 들어 -1 값은 0으로 설정됩니다. Zoom은 5개의 쉼표로 구분된 값 중 네 번째 값입니다.tilt
: 카메라의 각도, 즉 위/아래 방향을 지정합니다. 범위는 -90~0, 0~90입니다. 90은 똑바로 아래를 향하고, 0은 수평이고, -90은 똑바로 위를 향합니다.
예
아래는 스트리트 뷰 인텐트를 사용하는 몇 가지 예시입니다.
자바
// Displays an image of the Swiss Alps Uri gmmIntentUri = Uri.parse("google.streetview:cbll=46.414382,10.013988"); Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri); mapIntent.setPackage("com.google.android.apps.maps"); startActivity(mapIntent); // Uses a PanoID to show an image from Maroubra beach in Sydney, Australia Uri gmmIntentUri = Uri.parse("google.streetview:panoid=Iaa2JyfIggYAAAQfCZU9KQ"); Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri); mapIntent.setPackage("com.google.android.apps.maps"); startActivity(mapIntent); // Opens Street View between two Pyramids in Giza. The values passed to the // cbp parameter will angle the camera slightly up, and towards the east. Uri gmmIntentUri = Uri.parse("google.streetview:cbll=29.9774614,31.1329645&cbp=0,30,0,0,-15"); Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri); mapIntent.setPackage("com.google.android.apps.maps"); startActivity(mapIntent);
Kotlin
// Displays an image of the Swiss Alps val gmmIntentUri = Uri.parse("google.streetview:cbll=46.414382,10.013988") val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri) mapIntent.setPackage("com.google.android.apps.maps") startActivity(mapIntent) // Uses a PanoID to show an image from Maroubra beach in Sydney, Australia val gmmIntentUri = Uri.parse("google.streetview:panoid=Iaa2JyfIggYAAAQfCZU9KQ") val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri) mapIntent.setPackage("com.google.android.apps.maps") startActivity(mapIntent) // Opens Street View between two Pyramids in Giza. The values passed to the // cbp parameter will angle the camera slightly up, and towards the east. val gmmIntentUri = Uri.parse("google.streetview:cbll=29.9774614,31.1329645&cbp=0,30,0,0,-15") val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri) mapIntent.setPackage("com.google.android.apps.maps") startActivity(mapIntent)