소개
지도 URL을 사용하면 범용 교차 플랫폼 URL을 만들어 Google 지도를 실행하고 검색하고 경로를 찾고 내비게이션을 실행하고 지도뷰 및 파노라마 이미지를 표시할 수 있습니다. URL 구문은 사용 중인 플랫폼에 관계없이 동일합니다.
Google API 키가 없어도 지도 URL을 사용할 수 있습니다.
범용 크로스 플랫폼 구문
Android 앱, iOS 앱 또는 웹사이트의 개발자는 공통 URL을 구성할 수 있습니다. 그러면 지도가 열릴 때 사용 중인 플랫폼에 관계없이 Google 지도가 열리고 요청된 작업이 실행됩니다.
- Android 기기에서:
- Android용 Google 지도 앱이 설치되어 활성 상태인 경우 URL은 지도 앱에서 Google 지도를 실행하고 요청된 작업을 실행합니다.
- Google 지도 앱이 설치되지 않았거나 사용 중지된 경우 URL은 브라우저에서 Google 지도를 실행하고 요청된 작업을 실행합니다.
- iOS 기기에서:
- iOS용 Google 지도 앱이 설치된 경우 URL이 지도 앱에서 Google 지도를 실행하고 요청된 작업을 실행합니다.
- Google 지도 앱이 설치되어 있지 않으면 URL이 브라우저에서 Google 지도를 실행하고 요청된 작업을 실행합니다.
- 다른 기기의 경우 URL은 브라우저에서 Google 지도를 실행하고 요청된 작업을 실행합니다.
크로스 플랫폼 URL을 사용하여 앱이나 웹사이트에서 Google 지도를 실행하는 것이 좋습니다. 범용 URL을 사용하면 사용 중인 플랫폼에 관계없이 지도 요청을 더 광범위하게 처리할 수 있습니다. 세부 경로 안내 내비게이션과 같이 모바일 플랫폼에서만 작동할 수 있는 기능의 경우 Android 또는 iOS의 플랫폼별 옵션을 선호할 수 있습니다. 다음 문서를 참조하세요.
- Android용 Google 지도 인텐트 — 특히 Android용 Google 지도 앱을 실행하기 위한 용도입니다.
- iOS용 Google 지도 URL 스키마: iOS용 Google 지도 앱을 실행하기 위한 용도입니다.
Google 지도 실행 및 특정 작업 수행하기
Google 지도를 실행하고 지원되는 함수 중 하나를 선택적으로 실행하려면 요청된 작업에 따라 다음 형식 중 하나의 URL 스키마를 사용합니다.
- 검색
— 특정 장소의 핀을 표시하는 Google 지도를 실행하거나 일반 검색을 실행한 후 지도를 실행하여 결과를 표시합니다.
https://www.google.com/maps/search/?api=1¶meters
- 경로 — 경로를 요청하고 결과가 포함된 Google 지도를 실행합니다.
https://www.google.com/maps/dir/?api=1¶meters
- 지도 표시 - 마커나 경로 없이 Google 지도를 실행하세요.
https://www.google.com/maps/@?api=1&map_action=map¶meters
- 스트리트 뷰 파노라마 표시 — 대화형 파노라마 이미지 실행:
https://www.google.com/maps/@?api=1&map_action=pano¶meters
중요: api=1
매개변수는 이 URL의 대상인 지도 URL 버전을 식별합니다. 이 매개변수는 모든 요청에서 필수입니다. 유일하게 유효한 값은 1입니다. URL에 api=1
가 없으면
모든 매개변수가 무시되고
사용 중인 플랫폼에 따라 브라우저 또는 Google 지도
모바일 앱에서 기본 Google 지도 앱이 실행됩니다(예: https://www.google.com/maps).
유효한 URL 구성하기
URL을 올바르게 인코딩해야 합니다.
예를 들어 일부 매개변수는 파이프 문자(|
)를 구분자로 사용하므로 최종 URL에서 %7C
로 인코딩해야 합니다. 다른 매개변수는 위도/경도 좌표 또는 시, 주와 같이 쉼표로 구분된 값을 사용합니다. 쉼표를 %2C
로 인코딩해야 합니다. 공백을 %20
로 인코딩하거나 더하기 기호 (+
)로 대체합니다.
또한 URL은 요청당 2,048자로 제한됩니다. URL을 구성할 때 이 한도에 유의하세요.
지도 액션수
사용 가능한 지도 작업은 검색, 경로, 지도 표시, 스트리트 뷰 파노라마 표시입니다. 필수 및 선택 매개변수와 함께 요청 URL에 작업을 지정합니다. URL의 표준에 따라 앰퍼샌드(&
) 문자를 사용하여 매개변수를 구분합니다. 각 작업의 매개변수 목록과 가능한 값은 검색 매개변수 섹션에 열거됩니다.
검색
검색 작업은 표시된 지도 영역 전체에 걸쳐 검색결과를 표시합니다. 특정 장소를 검색하면 결과 지도에서 지정된 위치에 핀을 배치하고 사용 가능한 장소 세부정보를 표시합니다.
검색 URL 만들기
https://www.google.com/maps/search/?api=1¶meters
매개변수
query
(필수): 지도에서 강조 표시할 장소를 정의합니다. 검색어 매개변수는 모든 검색 요청에 필요합니다.query_place_id
(선택사항): 장소 ID는 장소를 고유하게 식별하는 텍스트 식별자입니다.search
작업의 경우query
를 지정해야 하지만query_place_id
를 지정할 수도 있습니다. 두 매개변수를 모두 지정하면 Google 지도에서 장소 ID를 찾을 수 없는 경우에만query
가 사용됩니다. 특정 시설에 확실하게 연결하려는 경우 올바른 장소에 연결할 수 있도록 장소 ID를 사용하는 것이 가장 좋습니다. 위도/경도 좌표를 사용하여 특정 위치를 쿼리할 때query_place_id
를 제출하는 것도 좋습니다.
검색 예
위치 검색
위치 검색에서는 장소 이름, 주소 또는 쉼표로 구분된 위도/경도 좌표를 사용하여 특정 위치를 검색하면 결과 지도에 해당 위치에 핀이 표시됩니다. 다음 세 가지 예는 동일한 위치인 CenturyLink Field (워싱턴주 시애틀의 스포츠 경기장)에 서로 다른 위치 값을 사용하여 검색하는 방법을 보여줍니다.
예 1: 장소 이름 'CenturyLink Field'를 검색하면 다음 지도가 나타납니다.
https://www.google.com/maps/search/?api=1&query=centurylink+field
예 2: 위도/경도 좌표와 장소 ID를 사용하여 CenturyLink 필드를 검색하면 다음 지도에 결과가 표시됩니다.
예 3: 위도/경도 좌표만 사용하여 CenturyLink 필드를 검색하면 다음 지도가 표시됩니다. 지도에 핀이 있지만 지도 또는 측면 패널에 추가 장소 정보가 제공되지 않습니다.
https://www.google.com/maps/search/?api=1&query=47.5951518%2C-122.3316393
범주형 검색
범주형 검색에서 일반 검색어를 전달하면 Google 지도에서 지정된 위치 근처에서 기준과 일치하는 등록정보를 찾습니다.
위치를 지정하지 않으면 Google 지도에서 현재 위치 주변의 비즈니스 정보를 찾으려고 시도합니다. 카테고리 검색의 위치를 제공하려면 일반 검색 문자열에 위치를 포함합니다(예: pizza+seattle+wa
).
이 예에서 워싱턴주 시애틀의 피자 전문점을 검색하면 다음 지도가 표시됩니다.
https://www.google.com/maps/search/?api=1&query=pizza+seattle+wa
Directions
경로 작업은 지도에 지정된 두 개 이상의 지점 간의 경로와 거리 및 이동 시간을 표시합니다.
경로 URL 만들기
https://www.google.com/maps/dir/?api=1¶meters
매개변수
origin
: 경로를 표시할 출발지를 정의합니다. 가능한 경우 기기 위치와 같이 가장 관련성 높은 시작 위치로 기본값이 설정됩니다. 없는 경우 결과 지도에서 사용자가 출발지를 입력할 수 있는 빈 양식을 제공할 수도 있습니다. 값은 장소 이름, 주소 또는 쉼표로 구분된 위도/경도 좌표가 될 수 있습니다. 문자열은 URL로 인코딩되어야 하므로 'City Hall, New York, NY'와 같은 주소는City+Hall%2C+New+York%2C+NY
로 변환되어야 합니다.참고: URL에
origin_place_id
를 지정하지 않는 한 이 매개변수는 선택사항입니다.origin_place_id
를 지정하도록 선택한 경우 URL에origin
도 포함해야 합니다.origin_place_id
(선택사항): 장소 ID는 장소를 고유하게 식별하는 텍스트 식별자입니다. 시설을 확실하게 지정하려는 경우 올바른 장소에 연결할 수 있도록 장소 ID를 사용하는 것이 가장 좋습니다. 이 매개변수를 사용하는 URL에는origin
도 포함되어야 합니다.destination
: 경로의 끝점을 정의합니다. 없는 경우 결과 지도에서는 사용자가 목적지를 입력할 수 있는 빈 양식을 제공할 수도 있습니다. 값은 장소 이름, 주소 또는 쉼표로 구분된 위도/경도 좌표가 될 수 있습니다. 문자열은 URL로 인코딩되어야 하므로 'City Hall, New York, NY'와 같은 주소는City+Hall%2C+New+York%2C+NY
로 변환되어야 합니다.참고: URL에
destination_place_id
를 지정하지 않는 한 이 매개변수는 선택사항입니다.destination_place_id
를 지정하도록 선택한 경우 URL에destination
도 포함해야 합니다.destination_place_id
(선택사항): 장소 ID는 장소를 고유하게 식별하는 텍스트 식별자입니다. 시설을 확실하게 지정하려는 경우 올바른 장소에 연결할 수 있도록 장소 ID를 사용하는 것이 가장 좋습니다. 이 매개변수를 사용하는 URL에는destination
도 포함되어야 합니다.travelmode
(선택사항): 이동 방법을 정의합니다. 옵션은driving
,walking
(가능한 경우 보행자 전용 도로 및 인도 선호),bicycling
(가능한 경우 자전거 전용 도로 및 선호하는 도로를 경유) 또는transit
입니다.travelmode
을 지정하지 않으면 Google 지도에는 지정된 경로 또는 사용자 환경설정과 가장 관련성이 높은 모드가 하나 이상 표시됩니다.dir_action=navigate
(선택사항): 출발지를 사용할 수 있는지에 따라 지정된 목적지에 대한 세부 경로 안내 내비게이션 또는 경로 미리보기를 실행합니다. 사용자가 출발지를 지정했는데 출발지가 사용자의 현재 위치와 가깝지 않거나 현재 기기 위치를 사용할 수 없는 경우 지도에서 경로 미리보기를 실행합니다. 사용자가 출발지를 지정하지 않거나 출발지가 기본적으로 현재 기기 위치에 가까워지면 지도에서 세부 경로 안내 내비게이션을 실행합니다. 일부 Google 지도 제품 또는 모든 목적지 간에 내비게이션을 사용할 수 있는 것은 아닙니다. 이러한 경우 이 매개변수가 무시됩니다.waypoints
:origin
와destination
사이의 경로를 통과할 하나 이상의 중간 장소를 지정합니다. 파이프 문자 (|
)를 사용해 장소를 구분하는 방식으로 여러 경유지를 지정할 수 있습니다 (예:Berlin,Germany|Paris,France
). 허용되는 경유지 수는 링크가 열리는 플랫폼에 따라 다르며, 모바일 브라우저에서는 최대 3개의 경유지가 지원되며 그 외의 경우에는 최대 9개의 경유지가 지원됩니다. 경유지는 URL에서와 동일한 순서로 지도에 표시됩니다. 각 경유지는 장소 이름, 주소 또는 쉼표로 구분된 위도/경도 좌표가 될 수 있습니다. 문자열은 URL로 인코딩되어야 하므로 'Berlin,Germany|Paris,France'와 같은 경유지는Berlin%2CGermany%7CParis%2CFrance
로 변환해야 합니다.참고:
- 일부 Google 지도 제품에서는 경유지가 지원되지 않습니다. 이러한 경우 이 매개변수가 무시됩니다.
- URL에
waypoint_place_ids
를 지정하지 않는 한 이 매개변수는 선택사항입니다.waypoint_place_ids
를 지정하는 경우 URL에waypoints
도 포함해야 합니다.
waypoint_place_ids
(선택사항): 장소 ID는 장소를 고유하게 식별하는 텍스트 식별자입니다.Waypoint_place_ids
를 사용하면waypoints
목록과 일치하는 장소 ID 목록을 제공할 수 있습니다. 장소 ID는 경유지와 동일한 순서로 나열되어야 하며 파이프 문자 '|
' (%7C
로 URL 인코딩)를 사용하여 구분해야 합니다. 특정 시설을 명확하게 지정하려는 경우 올바른 장소에 연결되도록 장소 ID를 사용하는 것이 가장 좋습니다. 이 매개변수를 사용하는 URL에는waypoints
도 포함되어야 합니다.avoid
(선택사항): 경로에서 피해야 할 지형지물을 설정합니다. 쉼표 문자 ',
'(%2C
로 URL 인코딩)로 구분된 다음 옵션 중 하나 이상으로 설정할 수 있습니다.ferries
highways
tolls
경로 예시
다음 URL은 경로 모드의 지도를 시작하고 사용자가 출발지와 목적지를 입력할 수 있는 양식을 제공합니다.
https://www.google.com/maps/dir/?api=1
다음 예에서는 스페이스 니들에서 워싱턴주 시애틀에 있는 파이크 플레이스 마켓까지의 자전거 경로가 포함된 지도를 시작합니다.
다음 예에서는 오스트레일리아 시드니의 Google에서 퀸 빅토리아 빌딩까지의 도보 경로가 포함된 지도를 시작합니다.
지도 표시
지도 작업은 마커나 경로가 없는 지도를 반환합니다.
지도 URL 구성
https://www.google.com/maps/@?api=1&map_action=map¶meters
매개변수
map_action=map
(필수): 표시할 지도뷰의 유형을 지정합니다. 지도와 스트리트 뷰는 동일한 엔드포인트를 공유합니다. 지도를 표시하려면map_action
을map
로 지정해야 합니다.center
(선택사항): 지도 창의 중심을 정의하고 위도/경도 좌표를 쉼표로 구분된 값(예:-33.8569,151.2152
)으로 허용합니다.zoom
(선택사항): 지도의 초기 확대/축소 수준을 설정합니다. 허용되는 값은 0 (전 세계)에서 21 (개별 건물) 사이의 정수입니다. 상한은 선택한 위치에서 사용할 수 있는 지도 데이터에 따라 달라질 수 있습니다. 기본값은 15입니다.basemap
(선택사항): 표시할 지도의 유형을 정의합니다. 값은roadmap
(기본값),satellite
또는terrain
가 될 수 있습니다.layer
(선택사항): 지도에 표시할 추가 레이어를 정의합니다(있는 경우). 값은none
(기본값),transit
,traffic
,bicycling
중 하나일 수 있습니다.
지도 예
이 예시 URL은 사용자의 현재 위치를 중심으로 기본 Google 지도를 실행합니다.
https://www.google.com/maps/@?api=1&map_action=map
다음 예에서는 오스트레일리아(-33.712206,150.311941
) 카툼바를 중심으로 지도를 표시하고 zoom
및 basemap
매개변수(선택사항)를 설정합니다.
스트리트 뷰 파노라마 표시
파노라마 작업을 통해 뷰어를 실행하여 스트리트 뷰 이미지를 대화형 파노라마로 표시할 수 있습니다. 각 스트리트 뷰 파노라마는 단일 위치에서 완전한 360도 뷰를 제공합니다. 이미지에는 360도 가로 뷰 (완전한 래핑)와 180도 세로 뷰 (위에서 아래로 수직)가 포함됩니다. 파노라마 작업은 카메라를 중앙에 두고 파노라마를 구로 렌더링하는 뷰어를 실행합니다. 카메라를 조작하여 카메라의 확대/축소와 방향을 제어할 수 있습니다.
Google 스트리트 뷰는 지정된 위치부터 커버리지 영역 전반에 걸쳐 파노라마 뷰를 제공합니다. 사용자 제공 Photo Sphere 및 스트리트 뷰 특별 컬렉션도 이용할 수 있습니다.
스트리트 뷰 URL 구성
https://www.google.com/maps/@?api=1&map_action=pano¶meters
매개변수
map_action=pano
(필수): 표시할 뷰의 유형을 지정합니다. 지도와 스트리트 뷰는 동일한 엔드포인트를 공유합니다. 파노라마를 표시하려면action
을pano
로 지정해야 합니다.
다음 URL 매개변수 중 하나도 필요합니다.
viewpoint
: 뷰어는 쉼표로 구분된 위도/경도 좌표 (예: 46.414382,10.013988)로 지정된viewpoint
위치에서 가장 가까운 곳에서 촬영된 파노라마를 표시합니다. 스트리트 뷰 이미지는 주기적으로 새로고침되고 사진이 매번 약간 다른 위치에서 촬영될 수 있으므로 이미지가 업데이트될 때 위치가 다른 파노라마에 맞춰질 수도 있습니다.pano
: 표시할 이미지의 특정 파노라마 ID입니다.pano
를 지정하는 경우viewpoint
를 지정할 수도 있습니다.viewpoint
는 Google 지도에서 파노라마 ID를 찾을 수 없는 경우에만 사용됩니다.pano
를 지정했지만 찾을 수 없고viewpoint
를 지정하지 않으면 파노라마 이미지가 표시되지 않습니다. 대신 Google 지도가 기본 모드로 열리고 사용자의 현재 위치를 중심으로 지도가 표시됩니다.
선택적 URL 매개변수:
heading
: 카메라의 나침반 방향을 북쪽에서부터 시계 방향의 도 단위로 나타냅니다. 허용되는 값은 -180~360도입니다. 생략하면 쿼리의 관점 (지정된 경우)과 이미지의 실제 위치를 기반으로 기본 제목이 선택됩니다.pitch
: 카메라의 각도(위/아래)를 지정합니다. 피치는 -90~90도 단위로 지정됩니다. 양수 값은 카메라 각도를 올리고 음수 값은 카메라 각도를 내립니다. 기본 피치 0은 이미지가 캡처되었을 때의 카메라 위치를 기반으로 설정됩니다. 이 때문에 피치 0은 대개 수평적이지만 항상 그렇지는 않습니다. 예를 들어 언덕에서 촬영한 이미지의 기본 피치는 수평이 아닐 수 있습니다.fov
: 이미지의 수평 시야를 결정합니다. 시야는 도 단위로 표현되며 10~100 범위의 값입니다. 기본값은 90입니다. 고정된 크기의 표시 영역을 다루는 경우 시야는 확대/축소 수준으로 간주되며 숫자가 작을수록 확대/축소 수준이 높아집니다.
스트리트 뷰의 예
처음 두 예는 에펠탑의 파노라마를 표시합니다. 첫 번째 예에서는 위치에 viewpoint
만 사용하고 선택적 heading
, pitch
, fov
매개변수를 설정합니다. 비교를 위해 두 예에서는 pano
ID뿐만 아니라 첫 번째 예에서 설정한 것과 동일한 매개변수를 사용합니다. 세 번째 예는 실내 파노라마 이미지를 표시합니다.
예 1: viewpoint
만 사용하여 위치를 지정합니다.
예 2: pano
ID와 viewpoint
위치 사용
pano
ID는 viewpoint
보다 우선 적용됩니다.
이 예에서는 파노라마 ID가 있으므로 viewpoint
는 무시됩니다. pano
ID에 표시되는 파노라마 이미지는 viewpoint
만 사용하여 찾은 이미지와 약간 다르며 더 최신입니다.
예 3: 영국 런던에 있는 사라스트로(Sarastro) 식당의 내부 파노라마를 파노라마 ID로 표시합니다.
https://www.google.com/maps/@?api=1&map_action=pano&pano=4U-oRQCNsC6u7r8gp02sLA
파노라마 ID 찾기
여러 가지 메서드를 사용하여 특정 파노라마 이미지의 ID를 찾을 수 있습니다.
- 자바스크립트의 경우 StreetViewPanorama 클래스를 사용합니다.
- Android의 경우 공개 클래스 StreetViewPanoramaLocation을 사용합니다.
- iOS의 경우 GMSPanorama 클래스를 사용합니다.
- Google Street View Image API를 사용하여 메타데이터를 요청할 수도 있습니다. 이미지 메타데이터 요청은 파노라마 ID를 포함하여 스트리트 뷰 파노라마에 대한 데이터를 제공합니다.
사례 더보기
경유지를 사용한 경로의 예
다음 경로 예는 Google 지도를 실행하고 다음 경유지를 통과하는 프랑스 파리에서 프랑스 셰르부르까지의 운전 경로를 표시합니다.
시, 국가 | 장소 이름 | 장소 ID |
---|---|---|
1. 프랑스 베르사유 | 베르사유 궁전 | ChIJdUyx15R95kcRj85ZX8H8OAU |
2. 프랑스 샤르트르 | 샤르트르 대성당 | ChIJKzGHdEgM5EcR_OBTT3nQoEA |
3. 프랑스 르망 | 르망 성 훌리아누스 대성당 | ChIJG2LvQNCI4kcRKXNoAsPi1Mc |
4. 프랑스 캉 | 캉 성 | ChIJ06tnGbxCCkgRsfNjEQMwUsc |
예시 URL에서는 경유지가 다양한 방식으로 정의되므로 결과 지도에서 경유지가 어떻게 표시되는지 비교할 수 있습니다.
예 1: 도시, 국가로 정의된 경유지:
예 2: 특정 장소 이름으로 정의된 경유지:
예 3: 도시, 국가로 정의된 경유지이며 각 경유지의 특정 시설에 waypoint_place_ids
도 제공합니다.
예 4: 경유지를 도시, 국가로 정의하지만 이전 예와 다른 순서로 경유지를 나열합니다. 경유지가 URL에 나열된 순서대로 지도에 표시됨을 보여줍니다.
지도 예
지정된 basemap
(위성) 및 layer
(대중교통)로 지도를 표시합니다.
스트리트 뷰의 예
FIFE 이미지 키를 pano
ID로 사용하여 스트리트 뷰 파노라마를 표시합니다. pano
ID는 F:로 시작합니다.