Android용 Google 지도 인텐트

Android용 Google 지도 앱은 표시, 검색, 내비게이션 또는 스트리트 뷰 모드로 Google 지도를 실행하는 데 사용할 수 있는 여러 인텐트를 노출합니다. 앱에 지도를 삽입하려면 Google Maps Android API 시작 가이드를 참고하세요.

개요

인텐트를 사용하면 Intent 객체에서 실행하려는 간단한 작업 (예: '지도 표시' 또는 '공항까지의 경로 표시')을 설명하여 다른 앱에서 활동을 시작할 수 있습니다. Android용 Google 지도 앱은 다양한 인텐트를 지원하므로 Google 지도 앱을 실행하고 다음 4가지 작업 중 하나를 수행할 수 있습니다.

1. 특정 위치 및 확대/축소 수준에서 지도를 표시합니다.
2. 위치나 장소를 검색하여 지도에 표시합니다.
3. 한 위치에서 다른 위치로 이동하는 경로를 요청합니다. 경로는 자동차, 도보, 자전거 등 세 가지 이동 모드에 대해 반환될 수 있습니다.
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);

// 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) {
  ...
}

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);
}

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() 메서드를 사용하여 문자열을 인코딩할 수 있습니다. 예를 들면 다음과 같습니다.

Uri gmmIntentUri =
  Uri.parse("geo:37.7749,-122.4192?q=" + Uri.encode("1st & Pike, Seattle"));

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);

// 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);

// 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);

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);

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의 위도/경도를 설정하지만 주소를 쿼리 문자열로 전달합니다. 매우 구체적인 위치를 검색할 때는 위도와 경도가 필요하지 않습니다. 그러나 정확한 주소를 모르면 좌표를 지정하여 검색 결과를 편중할 수 있습니다. 예를 들어 '중앙로'를 검색하면 너무 많은 결과가 반환됩니다.

// Searching for 'Main Street' will return too many results
Uri gmmIntentUri = Uri.parse("geo:0,0?q=101+main+street");

// Searching for 'Main Street' will return too many results
val gmmIntentUri = Uri.parse("geo:0,0?q=101+main+street")

인텐트 URI에 위도/경도를 추가하면 결과가 특정 지역으로 편중됩니다.

// 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);

// 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);

// 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

// 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는 경로에서 피해야 할 지형지물을 설정합니다. remember는 선택사항이며 다음 중 하나 이상으로 설정할 수 있습니다.

  • 유료도로: 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);

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);

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);

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);

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를 사용합니다. 파노라마 ID는 Android 앱의 StreetViewPanoramaLocation 객체에서 사용할 수 있습니다.

• 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은 똑바로 위를 향합니다.

예시

아래는 스트리트 뷰 인텐트를 사용하는 몇 가지 예시입니다.

// 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);

// 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)