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를 만든 후 다양한 방법으로 시스템에 관련 앱을 실행하도록 요청할 수 있습니다. 일반적인 메서드는 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%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를 설정했지만 주소를 쿼리 문자열로 전달합니다. 매우 특정한 위치를 검색할 때 위도와 경도는 필요하지 않습니다. 하지만 정확한 주소를 모르는 경우 좌표를 지정하여 검색 결과를 상세 검색할 수 있습니다. 예를 들어 '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입니다. panoidcbll가 모두 지정된 경우 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)

스트리트 뷰의 피라미드