Android용 Google 지도 인텐트

컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

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

개요

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

  1. 특정 위치 및 확대/축소 수준에서 지도를 표시합니다.
  2. 위치나 장소를 검색하여 지도에 표시합니다.
  3. 한 위치에서 다른 위치로의 경로를 요청합니다. 운전, 도보, 자전거의 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를 만든 후 시스템이 여러 가지 방법으로 관련 앱을 실행하도록 요청할 수 있습니다. 일반적인 메서드는 IntentstartActivity() 메서드에 전달하는 것입니다. 시스템에서 필요한 앱(이 경우 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 & 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"));

Kotlin

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

지도 표시

geo: 인텐트를 사용하여 지정된 위치와 확대/축소 수준에서 지도를 표시합니다.

geo:latitude,longitude?z=zoom

매개변수

  • latitudelongitude는 지도의 중심점을 설정합니다.
  • 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를 설정하지만 주소를 쿼리 문자열로 전달합니다. 매우 특정한 위치를 검색할 때는 위도 및 경도가 필요하지 않습니다. 정확한 주소를 모르는 경우 좌표를 지정하여 검색 결과를 편중할 수 있습니다. 예를 들어 '메인 스트리트'에 대해 주소 검색을 수행하면 너무 많은 결과가 반환됩니다.

자바

// 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 스트리트 뷰는 커버리지 영역 전체에서 지정된 위치에서 탁 트인 뷰를 제공합니다. 사용자 제공 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입니다. panoidcbll이 모두 지정되면 Google 지도에서 파노라마 ID를 사용합니다. Android ID는 StreetViewPanoramaLocation 객체에서 파노라마 ID를 사용할 수 있습니다.

  • cbp는 카메라의 초기 방향을 조정하는 매개변수입니다(선택사항). cbp 매개변수는 쉼표로 구분된 5개의 값을 사용하며, 모두 선택사항입니다. 가장 중요한 값은 각각 방위, 확대/축소, 기울기를 설정하는 두 번째, 네 번째, 다섯 번째입니다. 첫 번째와 세 번째 값은 지원되지 않으며 0로 설정해야 합니다.

    • bearing: 북쪽에서 시계 방향으로 도 단위로 카메라의 나침반 방위를 나타냅니다. 정북쪽은 0, 동쪽은 90, 남쪽은 180, 서쪽은 270입니다. 방위에 전달된 값은 래핑됩니다. 즉, 0°, 360°, 720°는 모두 같은 방향을 가리킵니다. 방위는 5개의 쉼표로 구분된 값 중 두 번째 값으로 정의됩니다.
    • zoom: 카메라의 확대/축소 수준을 설정합니다. 기본 확대/축소 수준은 0으로 설정됩니다. 1을 선택하면 확대율이 2배가 됩니다. 확대/축소는 현재 파노라마의 0과 최대 확대/축소 수준 사이에 고정됩니다. 즉, 이 범위를 벗어나는 모든 값은 이 범위 내에서 가장 가까운 극단값으로 설정됩니다. 예를 들어 값이 -1로 설정됩니다. 확대/축소는 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)

스트리트 뷰의 피라미드