Android용 Google 지도 앱은 표시, 검색, 내비게이션 또는 스트리트 뷰 모드로 Google 지도를 실행하는 데 사용할 수 있는 여러 인텐트를 노출합니다. 앱에 지도를 삽입하려면 Google Maps Android API 시작 가이드를 참고하세요.
개요
인텐트를 사용하면 Intent
객체에서 실행할 간단한 작업 (예: '지도 표시' 또는 '공항 경로 표시')을 설명하여 다른 앱에서 활동을 시작할 수 있습니다. Android용 Google 지도 앱은 다양한 인텐트를 지원하므로 Google 지도 앱을 실행하고 다음 네 가지 작업 중 하나를 실행할 수 있습니다.
- 특정 위치 및 확대/축소 수준에서 지도를 표시합니다.
- 위치나 장소를 검색하여 지도에 표시합니다.
- 한 위치에서 다른 위치로의 경로를 요청합니다. 길찾기는 운전, 도보, 자전거의 세 가지 이동 모드에 대해 반환될 수 있습니다.
- 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
를 시작합니다.
Java
// 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
이면 이 인텐트를 사용해서는 안 되며 가능하면 인텐트를 호출하는 기능을 사용 중지해야 합니다.
Java
if (mapIntent.resolveActivity(getPackageManager()) != null) { ... }
Kotlin
mapIntent.resolveActivity(packageManager)?.let { ... }
예를 들어, 샌프란시스코의 지도를 표시할 때 다음 코드를 사용할 수 있습니다.
Java
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 & Pike, Seattle' 문자열은 1st%20%26%20Pike%2C%20Seattle
이 되어야 합니다.
문자열 내의 공백은 %20으로 인코딩하거나 더하기 부호(+)로 대체할 수 있습니다.
android.net.Uri
parse()
메서드를 사용하여 문자열을 인코딩할 수 있습니다.
예를 들면 다음과 같습니다.
Java
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 (개별 건물)까지입니다. 상한은 선택한 위치에서 사용할 수 있는 지도 데이터에 따라 달라질 수 있습니다.
예시
Java
// 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 지도에서 주변 목록을 찾으려고 시도합니다. 예를 들면 다음과 같습니다.
Java
// 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으로 설정하면 근처가 아닌 도시 수준에서 식당을 찾으려고 시도합니다.
Java
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)
위치 검색
특정 주소를 검색하면 그 장소에 핀을 표시합니다.
Java
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
로 설정하지만 주소를 쿼리 문자열로 전달합니다. 매우 구체적인 위치를 검색하는 경우 위도와 경도가 필요하지 않습니다. 그러나 정확한 주소를 모르는 경우 좌표를 지정하여 검색 결과를 상세 검색할 수 있습니다. 예를 들어 'Main Street'의 주소를 검색하면 너무 많은 결과가 반환됩니다.
Java
// 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에 위도/경도를 추가하면 결과가 특정 지역으로 편중됩니다.
Java
// 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
가 경도/위도 좌표로 지정된 경우에만 라벨을 사용할 수 있습니다.
Java
// 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)
상세 주소 또는 위도/경도 대신 플러스 코드를 사용하여 알려진 위치에 핀을 표시할 수 있습니다.
Java
// 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
는 오스트레일리아 시드니 타롱가 동물원의 세부 경로 안내 내비게이션을 요청합니다.
Java
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)
통행료를 지불하거나 페리를 타지 않으려면 이러한 것을 피하기 위해 경로를 요청할 수 있습니다.
Java
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)
약간 운동을 하고 싶다면 대신 자전거 경로를 요청할 수 있습니다.
Java
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
는 인도의 경로를 반환합니다.
Java
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 스트리트 뷰는 지정된 위치부터 커버리지 영역 전체에 걸쳐 파노라마 뷰를 제공합니다.
사용자 제공 Photo Sphere 및 스트리트 뷰 특별 컬렉션도 사용할 수 있습니다.
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로 설정하면 배율이 두 배가 됩니다. 확대/축소는 0과 현재 파노라마의 최대 확대/축소 수준 사이로 고정됩니다. 즉, 이 범위를 벗어나는 값은 범위 내에서 가장 가까운 최댓값으로 설정됩니다. 예를 들어 -1 값은 0으로 설정됩니다. 확대/축소는 5개의 쉼표로 구분된 값 중 네 번째 값입니다.tilt
: 카메라의 각도(위 또는 아래)를 지정합니다. 범위는 -90~0~90입니다. 90도는 똑바로 아래를 향하고, 0도는 수평선 중앙에, -90도는 똑바로 위를 향합니다.
예시
아래는 스트리트 뷰 인텐트를 사용하는 몇 가지 예시입니다.
Java
// 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)