Android용 Google 지도 인텐트

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

개요

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

  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를 만든 후 시스템에서 여러 가지 방법으로 관련 앱을 실행하도록 요청할 수 있습니다. 일반적인 메서드는 IntentstartActivity() 메서드에 전달하는 것입니다. 시스템에서 필요한 앱(이 경우 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

매개변수

  • latitudelongitude는 지도의 중심점을 설정합니다.
  • 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입니다. panoidcbll가 모두 지정된 경우 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)

스트리트 뷰의 피라미드