지도앱 연동 URL Scheme

Classic/VPC 환경에서 이용 가능합니다.

URL Scheme 소개

네이버 지도 앱 URL Scheme을 사용하면 외부 앱이나 웹 페이지에서 네이버 지도 앱을 실행해 장소 표시, 검색, 길찾기, 내비게이션 등 다양한 지도 기능을 수행할 수 있습니다.

URL Scheme 사용하기

기본 정보

네이버 지도 앱 URL Scheme은 nmap://으로 시작하며, 기본 구조는 다음과 같습니다.

nmap://actionPath?parameter=value&appname={YOUR_APP_NAME}

actionPath부분에는 호출 기능의 유형을, parameter=value부분에는 각 기능별로 필요한 파라미터를 지정합니다. 자세한 내용은 기능별 파라미터 설명을 참고하세요.

appname

appname은 URL Scheme을 사용하는 앱 또는 웹 페이지를 식별하는 문자열입니다. 모든 URL에는 appname 파라미터가 반드시 포함되어야 합니다. 다음과 같은 값을 지정합니다.

Android: 앱의 applicationId
iOS: 앱의 번들 ID
웹 페이지: 웹 페이지의 URL

지도 메인 표시

지도 앱의 메인 화면을 보여줍니다.

액션 경로

/map

파라미터

파라미터	타입	필수 여부	설명
lat	double	N	지도의 중심 위도. -입력값: `31.43`~`44.35` -기본값: 앱의 기존 상태 유지
lng	double	N	지도의 중심 경도. -입력값: `122.37`~`132.00` -기본값: 앱의 기존 상태 유지
zoom	double	N	지도의 줌 레벨. -입력값: `4`~`20` -기본값: 앱의 기존 상태 유지

예제

다음은 별도의 파라미터 없이 지도 앱의 메인 화면을 표시하는 예제입니다.

nmap://map?&appname=com.example.myapp

호출 결과는 다음과 같습니다.

다음은 지도의 중심점을 (37.4979502, 127.0276368), 줌 레벨을 20으로 지정해 지도 앱의 메인 화면을 표시하는 예제입니다.

nmap://map?lat=37.4979502&lng=127.0276368&level=13&mode=3&traffic=false&appname=com.example.myapp

호출 결과는 다음과 같습니다.

검색

통합 검색

검색어에 맞는 지도 검색 결과를 보여줍니다.

액션 경로

/search

파라미터

파라미터	타입	필수 여부	설명
query	string	Y	검색어. -입력값: URL 인코딩된 문자열

예제

다음은 "강남역"을 검색어로 넣어 지도를 검색하는 예제입니다.

nmap://search?query=%EA%B0%95%EB%82%A8%EC%97%AD&appname=com.example.myapp

호출 결과는 다음과 같습니다.

버스 검색

검색어에 맞는 버스 검색 결과를 보여줍니다.

액션 경로

/search/bus

파라미터

파라미터	타입	필수 여부	설명
query	string	Y	버스 번호. -입력값: URL 인코딩된 문자열

예제

다음은 "222"번 버스를 검색하는 예제입니다.

nmap://search/bus?query=222&appname=com.example.myapp

호출 결과는 다음과 같습니다.

장소 표시

지정된 좌표에 마커를 표시합니다.

액션 경로

/place

파라미터

파라미터	타입	필수 여부	설명
lat	double	Y	위도. -입력값: `31.43`~`44.35`
lng	double	Y	경도. -입력값: `122.37`~`132.00`
name	string	Y	이름. -입력값: URL 인코딩된 문자열

예제

다음은 (37.4979502, 127.0276368) 위치에 "경기도 성남시 분당구 정자동" 마커를 표시하는 예제입니다.

nmap://place?lat=37.4979502&lng=127.0276368&name=%EA%B2%BD%EA%B8%B0%EB%8F%84%20%EC%84%B1%EB%82%A8%EC%8B%9C%20%EB%B6%84%EB%8B%B9%EA%B5%AC%20%EC%A0%95%EC%9E%90%EB%8F%99&appname=com.example.myapp

호출 결과는 다음과 같습니다.

길찾기

대중교통 길찾기

대중교통 길찾기를 수행합니다.

액션 경로

/route/public

파라미터

경로 탐색 공통 파라미터 항목을 참고하세요.

예제

다음은 서울대학교에서 올림픽 공원까지 대중교통으로 가는 경로를 탐색하는 예제입니다.

nmap://route/public?slat=37.4640070&slng=126.9522394&sname=%EC%84%9C%EC%9A%B8%EB%8C%80%ED%95%99%EA%B5%90&dlat=37.5209436&dlng=127.1230074&dname=%EC%98%AC%EB%A6%BC%ED%94%BD%EA%B3%B5%EC%9B%90&appname=com.example.myapp

호출 결과는 다음과 같습니다.

자동차 길찾기

자동차 길찾기를 수행합니다.

액션 경로

/route/car

파라미터

경로 탐색 공통 파라미터 항목을 참고하세요.

예제

다음은 서울대학교에서 올림픽 공원까지 자동차로 가는 경로를 탐색하는 예제입니다.

nmap://route/car?slat=37.4640070&slng=126.9522394&sname=%EC%84%9C%EC%9A%B8%EB%8C%80%ED%95%99%EA%B5%90&dlat=37.5209436&dlng=127.1230074&dname=%EC%98%AC%EB%A6%BC%ED%94%BD%EA%B3%B5%EC%9B%90&appname=com.example.myapp

호출 결과는 다음과 같습니다.

다음은 그린팩토리에서 서울대학교를 경유해 성남시청까지 자동차로 가는 경로를 탐색하는 예제입니다.

nmap://route/car?slat=37.3595953&slng=127.1053971&sname=%EA%B7%B8%EB%A6%B0%ED%8C%A9%ED%86%A0%EB%A6%AC&secoords=37.359761,127.10527&dlng=127.1267772&dlat=37.4200267&dname=%EC%84%B1%EB%82%A8%EC%8B%9C%EC%B2%AD&decoords=37.4189564,127.1256827&v1lng=126.9522394&v1lat=37.464007&v1name=%20%EC%84%9C%EC%9A%B8%EB%8C%80%ED%95%99%EA%B5%90&v1ecoords=37.466358,126.948357&appname=com.example.myapp

호출 결과는 다음과 같습니다.

도보 길찾기

도보 길찾기를 수행합니다.

액션 경로

/route/walk

파라미터

경로 탐색 공통 파라미터 항목을 참고하세요.

예제

다음은 서울대학교에서 동원 낙성대 아파트까지 도보로 가는 경로를 탐색하는 예제입니다.

nmap://route/walk?slat=37.4640070&slng=126.9522394&sname=%EC%84%9C%EC%9A%B8%EB%8C%80%ED%95%99%EA%B5%90&dlat=37.4764356&dlng=126.9618302&dname=%EB%8F%99%EC%9B%90%EB%82%99%EC%84%B1%EB%8C%80%EC%95%84%ED%8C%8C%ED%8A%B8&appname=com.example.myapp

호출 결과는 다음과 같습니다.

자전거 길찾기

자전거 길찾기를 수행합니다.

액션 경로

/route/bicycle

파라미터

경로 탐색 공통 파라미터 항목을 참고하세요.

예제

다음은 서울대학교에서 올림픽 공원까지 자전거로 가는 경로를 탐색하는 예제입니다.

nmap://route/bicycle?slat=37.4640070&slng=126.9522394&sname=%EC%84%9C%EC%9A%B8%EB%8C%80%ED%95%99%EA%B5%90&dlat=37.5209436&dlng=127.1230074&dname=%EC%98%AC%EB%A6%BC%ED%94%BD%EA%B3%B5%EC%9B%90&appname=com.example.myapp

호출 결과는 다음과 같습니다.

경로 탐색 공통 파라미터

길찾기(/route)와 내비게이션(/navigation)에서 사용하는 공통 파라미터입니다.

파라미터	타입	필수 여부	설명
slat	double	N	출발지 위도. -입력값: `31.43`~`44.35` -기본값: 사용자의 현 위치 사용
slng	double	N	출발지 경도. -입력값: `122.37`~`132.00` -기본값: 사용자의 현 위치 사용
sname	string	N	출발지 이름. -입력값: URL 인코딩된 문자열 -기본값: 사용자의 현 위치 사용
dlat	double	Y	도착지 위도. -입력값: `31.43`~`44.35`
dlng	double	Y	도착지 경도. -입력값: `122.37`~`132.00`
dname	string	N	도착지 이름. -입력값: URL 인코딩된 문자열 -기본값: 도착지 주소 표시
v1lat	double	N	경유지 1 위도. -입력값: `31.43`~`44.35` -기본값: 경유지 없음
v1lng	double	N	경유지 1 경도. -입력값: `122.37`~`132.00` -기본값: 경유지 없음
v1name	string	N	경유지 1 이름. -입력값: URL 인코딩된 문자열 -기본값: 경유지 없음
v2lat	double	N	경유지 2 위도. -입력값: `31.43`~`44.35` -기본값: 경유지 없음
v2lng	double	N	경유지 2 경도. -입력값: `122.37`~`132.00` -기본값: 경유지 없음
v2name	string	N	경유지 2 이름. -입력값: URL 인코딩된 문자열 -기본값: 경유지 없음
v3lat	double	N	경유지 3 위도. -입력값: `31.43`~`44.35` -기본값: 경유지 없음
v3lng	double	N	경유지 3 경도. -입력값: `122.37`~`132.00` -기본값: 경유지 없음
v3name	string	N	경유지 3 이름. -입력값: URL 인코딩된 문자열 -기본값: 경유지 없음
v4lat	double	N	경유지 4 위도. -입력값: `31.43`~`44.35` -기본값: 경유지 없음
v4lng	double	N	경유지 4 경도. -입력값: `122.37`~`132.00` -기본값: 경유지 없음
v4name	string	N	경유지 4 이름. -입력값: URL 인코딩된 문자열 -기본값: 경유지 없음
v5lat	double	N	경유지 5 위도. -입력값: `31.43`~`44.35` -기본값: 경유지 없음
v5lng	double	N	경유지 5 경도. -입력값: `122.37`~`132.00` -기본값: 경유지 없음
v5name	string	N	경유지 5 이름. -입력값: URL 인코딩된 문자열 -기본값: 경유지 없음

URL Scheme 사용 시 처리 사항

웹 페이지나 앱에서 네이버 지도 URL Scheme을 호출하면 네이버 지도 앱이 열리면서 URL Scheme이 처리됩니다. 이때, 사용자의 기기에 네이버 지도 앱이 설치되어 있지 않으면 App Store나 Google Play의 네이버 지도 앱 설치 페이지로 연결해 사용자가 앱을 설치할 수 있도록 해야 합니다.

모바일 앱

Android

다음과 같이 queryIntentActivities를 호출해 네이버 지도 앱이 설치되어 있는지 확인하고, 설치되어 있지 않으면 Google Play로 이동합니다.

String url = "nmap://actionPath?parameter=value&appname={YOUR_APP_NAME}";

Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(url));
intent.addCategory(Intent.CATEGORY_BROWSABLE);

List<ResolveInfo> list = getPackageManager().queryIntentActivities(intent, PackageManager.MATCH_DEFAULT_ONLY);
if (list == null || list.isEmpty()) {
    context.startActivity(new Intent(Intent.ACTION_VIEW, Uri.parse("market://details?id=com.nhn.android.nmap")));
} else {
    context.startActivity(intent);
}

iOS

info.plist에 LSApplicationQueriesSchemes를 생성하고 nmap을 추가합니다.

<key>LSApplicationQueriesSchemes</key>
<array>
    <string>nmap</string>
</array>

다음과 같이 canOpenURL을 호출해 네이버 지도 앱이 설치되어 있는지 확인하고, 설치되어 있지 않으면 App Store로 이동합니다.

let url = URL(string: "nmap://actionPath?parameter=value&appname={YOUR_APP_NAME}")!
let appStoreURL = URL(string: "http://itunes.apple.com/app/id311867728?mt=8")!

if UIApplication.shared.canOpenURL(url) {
  UIApplication.shared.open(url)
} else {
  UIApplication.shared.open(appStoreURL)
}

모바일 웹 페이지

Android

인텐트 URL을 사용하면 앱이 설치되어 있지 않은 경우 자동으로 Google Play 스토어로 이동합니다. 인텐트 URL의 구조는 다음과 같습니다.

intent://actionPath?parameter=value&appname={YOUR_APP_NAME}#Intent;scheme=nmap;action=android.intent.action.VIEW;category=android.intent.category.BROWSABLE;package=com.nhn.android.nmap;end

다음은 (37.4979502, 127.0276368) 위치에 "경기도 성남시 분당구 정자동" 마커를 표시하는 URL Scheme을 인텐트 URL로 나타낸 예제입니다.

intent://place?lat=37.4979502&lng=127.0276368&name=%EA%B2%BD%EA%B8%B0%EB%8F%84%20%EC%84%B1%EB%82%A8%EC%8B%9C%20%EB%B6%84%EB%8B%B9%EA%B5%AC%20%EC%A0%95%EC%9E%90%EB%8F%99&appname=com.example.myapp#Intent;scheme=nmap;action=android.intent.action.VIEW;category=android.intent.category.BROWSABLE;package=com.nhn.android.nmap;end

iOS

다음과 같이 웹 페이지에서 JavaScript 타이머를 이용해 App Store로 분기시키는 방법을 사용합니다.

<script>
function openNaverMapApp(url) {
    var clickedAt = +new Date();

    location.href = url;

    setTimeout(function() {
        if (+new Date() - clickedAt < 2000) {
            location.href = 'http://itunes.apple.com/app/id311867728?mt=8';
        }
    }, 1500);
}

window.onload = function() {
    openNaverMapApp("nmap://actionPath?parameter=value&appname={YOUR_APP_NAME}");
};
</script>

인앱 브라우저

인앱 브라우저에서 URL Scheme을 처리하려면 추가 작업이 필요합니다.

Android

다음과 같이 WebViewClient의 shouldOverrideUrlLoading을 오버라이드해 URL Scheme 처리 코드를 추가합니다.

@Override
public boolean shouldOverrideUrlLoading(WebView view, String url) {
    if (url.startsWith("intent:")) {
        Intent intent;
        try {
            intent = Intent.parseUri(url, Intent.URI_INTENT_SCHEME);
        } catch (URISyntaxException e) {
            return false;
        }
        if (TextUtils.isEmpty(intent.getPackage())) {
            return false;
        }
        List<ResolveInfo> list = getPackageManager().queryIntentActivities(intent, PackageManager.MATCH_DEFAULT_ONLY);
        if (list == null || list.isEmpty()) {
            startActivity(new Intent(Intent.ACTION_VIEW, Uri.parse("market://details?id=" + intent.getPackage())));
        } else {
            startActivity(intent);
        }
        return true;
    }

    return false;
}

iOS

다음과 같이 WKWebview의 decidePolicyFor에 URL Scheme 처리 코드를 추가합니다.

func webView(_ webView: WKWebView, decidePolicyFor navigationAction: WKNavigationAction, decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
    if let url = navigationAction.request.url {
        if url.scheme == "nmap" {
            UIApplication.shared.open(url)
            decisionHandler(.cancel)
            return
        }
    }
    decisionHandler(.allow)
}