raster

개요

네이버 지도에서는 JavaScript를 사용하지 않고, 웹 페이지에서 네이버 지도를 이용해 쉽게 위치를 표시하고 안내할 수 있는 Static Map(정적 지도) 서비스를 제공합니다.
HTML 페이지 내에 원하는 이미지를 가져오려면 요청 형식에 맞는 URL을 만들어 <img> 태그에 배치하면 됩니다.

요청

ID-KEY 기반 인증

curl "https://naveropenapi.apigw-pub.fin-ntruss.com/map-static/v2/raster?w=300&h=300&center=127.1054221,37.3591614&level=16" \
	-H "X-NCP-APIGW-API-KEY-ID: {애플리케이션 등록 시 발급받은 client id값}" \
	-H "X-NCP-APIGW-API-KEY: {애플리케이션 등록 시 발급받은 client secret값}" -v

HTTP Referer 기반 인증

• 브라우져에서 IMG 태그 또는 Ajax 방식으로 호출할 경우 아래 URL을 통해 호출할 수 있습니다. Referer인증을 위해서, 해당 Application에 Web 서비스 URL을 등록 하셔야 합니다.
• 자세한 사항은 [ AI.NAVER API > 공통 가이드 > Application 사용 가이드 > Application 등록 방법] 을 참고 하세요

<img src="https://naveropenapi.apigw-pub.fin-ntruss.com/map-static/v2/raster-cors?w=300&h=300&center=127.1054221,37.3591614&level=16&X-NCP-APIGW-API-KEY-ID={애플리케이션 등록 시 발급받은 client id값}">

요청 파라미터

요청 헤더

해당 헤더는 ID-KEY 기반 인증에서만 필요로 합니다.

요청 바디

• 해당 API 는 요청 바디를 필요로 하지 않습니다.

DataVersion API 와 StaticMap API 연동

DataVersion API 연동 필요성

• StaticMap API 는 이미지 캐싱을 사용합니다.
• 클라이언트에서 동일 URL 요청 시 캐싱으로 인해, 원본 서버의 배경 타일 업데이트가 반영 안 되는 문제가 발생 할 수 있습니다.
• 이를 해결하기 위한 방법으로 클라이언트측에서 StaticMap API 호출 시 DataVersion API 에서 내려주는 버전 파라미터값을 붙여서 호출을 권장합니다.
• 배경 타일에 대한 최신성 이슈가 없을 경우 DataVersion API 와 연동할 필요가 없습니다.

Data Version API

• 요청
  • https://naveropenapi.apigw-pub.fin-ntruss.com/map-static/v2/lastversion
• 결과 포맷
• json 타입

{
   "version": "major_version.minor_version",
   "interval": 43200
}

• major_version.minor_version 문자열 + interval로 구성
  • major_version : 정기업데이트 시 변경, 원타일맵 메이저 버전과 동일하게 유지 (2달에 1번 업데이트)
  • minor_version : 부분업데이트 시 버전 올림 (1달에 1~2번 업데이트)
  • interval: 권장 업데이트 주기 (초)

StaticMap API 연동 방법

• DataVersion API 를 이용하여 dataversion 값 구하기
  • 매번 요청할 때마다 버전값을 얻어오는 것은 데이터 업데이트 주기상(1달에 1~2번 업데이트) 비효율적이므로 배치성 작업 추천
  • 1일 2회이상 정해진 시간에 DataVersion API에서 버전 정보를 가져가 저장해놓고 있다가 StaticMap API 요청할 때 사용
• StaticMap 요청 URL에 DataVersion 파라미터 값 명시하여 사용
  • 요청하는 URL에 'dataversion=버전명' 형식으로 파라미터를 추가
  • 예시 (dataversion=201.3 일 경우)
    • https://naveropenapi.apigw-pub.fin-ntruss.com/map-static/v2/raster?params&dataversion=201.3

응답

응답 바디

정상적인 요청일 경우 파라미터에 맞게 한 장의 이미지 파일(png나 jpeg)을 반환합니다.
오류가 발생하면 HTTP 상태 코드 200이 아닌 값이 JSON 형식으로 반환됩니다.

예시

요청 예시

center

지도의 중심 좌표를 설정합니다.

• 형식: center=X 좌표,Y 좌표
  

중심 좌표는 X 좌표 지점과 Y 좌표 지점으로 구성되며, X, Y 좌표 지점값은 콤마로 구분합니다. 경위도 좌표의 입력 형식은 <경도,위도>입니다.

단, markers 파라미터를 설정해 최적화된 줌 레벨과 위치로 지도를 표시할 때는 center와 level 파라미터를 생략할 수 있습니다.

다음은 WGS84 경위도 좌표 체계의 중심 좌표가 127.1054221,37.3591614인 이미지를 요청하는 예제입니다.

https://naveropenapi.apigw-pub.fin-ntruss.com/map-static/v2/raster?w=300&h=300&center=127.1054221,37.3591614&level=16

아래 그림의 정중앙이 중심 좌표가 됩니다.

level

지도의 줌 레벨을 설정합니다.

• 형식: level=줌 레벨
  

줌 레벨은 최소 0, 최대 20 레벨까지 지원합니다.
단, markers 파라미터를 설정해 최적화된 줌 레벨과 위치로 지도를 표시할 때는 center와 level 파라미터를 생략할 수 있습니다.

다음은 레벨이 11인 지도를 요청하는 예제입니다.

https://naveropenapi.apigw-pub.fin-ntruss.com/map-static/v2/raster?w=300&h=300&center=127.1054221,37.3591614&level=11

다음과 같이 11 레벨의 지도가 표시됩니다.

w, h

이미지의 크기를 가로(w), 세로(h)로 나타냅니다. 단위는 픽셀(pixel)이며, 값의 범위는 가로, 세로 각각 1~1024 픽셀입니다.

• 형식: w=크기&h=크기
  

다음은 지도의 크기를 가로 300 픽셀, 세로 200 픽셀로 요청하는 예제입니다.

https://naveropenapi.apigw-pub.fin-ntruss.com/map-static/v2/raster?w=300&h=200&center=127.1054221,37.3591614&level=16

다음과 같이 요청한 크기의 지도가 표시됩니다.

maptype

지도 유형을 설정합니다.

• 형식: maptype=basic|satellite|terrain
  • basic: 일반 지도 유형
  • traffic: 교통 정보 지도 유형 (일반 지도 베이스)
  • satellite: 위성 지도 유형
  • satellite_base: 위성 배경 지도 유형
  • terrain: 지형도 유형
    ​
    일반 지도 요청
    ​
    다음은 일반 지도 유형을 요청하는 예제입니다.

https://naveropenapi.apigw-pub.fin-ntruss.com/map-static/v2/raster?w=300&h=300&center=127.1054221,37.3591614&level=11&maptype=basic

​
다음과 같이 일반 지도가 표시됩니다.

교통 정보 지도 요청

​
다음은 교통 지도 유형을 요청하는 예제입니다.

https://naveropenapi.apigw-pub.fin-ntruss.com/map-static/v2/raster?w=300&h=300&center=127.1054221,37.3591614&level=11&maptype=traffic

​
다음과 같이 교통 지도가 표시됩니다.

위성 지도 요청

다음은 위성 지도 유형을 요청하는 예제입니다.

https://naveropenapi.apigw-pub.fin-ntruss.com/map-static/v2/raster?w=300&h=300&center=127.1054221,37.3591614&level=11&maptype=satellite

다음과 같이 위성 지도가 표시됩니다.

위성 배경 지도 요청

​
다음은 위성 배경 지도 유형을 요청하는 예제입니다.

https://naveropenapi.apigw-pub.fin-ntruss.com/map-static/v2/raster?w=300&h=300&center=127.1054221,37.3591614&level=11&maptype=satellite_base

​
다음과 같이 위성 배경 지도가 표시됩니다.

지형도 요청

다음은 지형도 유형을 요청하는 예제입니다.

https://naveropenapi.apigw-pub.fin-ntruss.com/map-static/v2/raster?w=300&h=300&center=127.1054221,37.3591614&level=11&maptype=terrain

다음과 같이 지형도가 표시됩니다.

format

​
지도 이미지의 형식을 설정 합니다

• 형식: format=이미지 형식(jpg 또는 png8 또는 png)
  ​
  반환 되는 이미지 형식은 jpg, png, png8 입니다.

• 기본값: jpg(jpeg)는 압축 품질 85%의 24 비트 JPEG 형식을 지원 합니다. (jpg와 jpeg 키워드를 모두 지원 합니다.)

• png8은 8 비트 PNG 형식을 지원 합니다.

• png는 24 비트 PNG 형식을 지원 합니다.
  ​
  ​

jpeg(jpg) 이미지 형식 요청

​
다음은 jpeg(jpg) 이미지 형식으로 지도를 요청하는 예제입니다.
​

https://naveropenapi.apigw-pub.fin-ntruss.com/map-static/v2/raster?w=300&h=300&center=127.1054221,37.3591614&level=16&format=jpg

​
다음과 같이 jpg 형식의 지도가 표시됩니다.

​

png8 이미지 형식 요청

​
다음은 png8 이미지 형식으로 지도를 요청하는 예제입니다.
​

https://naveropenapi.apigw-pub.fin-ntruss.com/map-static/v2/raster?w=300&h=300&center=127.1054221,37.3591614&level=16&format=png8

​
다음과 같이 png8 형식의 지도가 표시됩니다.

​

png 이미지 형식 요청

​
다음은 png 이미지 형식으로 지도를 요청하는 예제입니다.
​

https://naveropenapi.apigw-pub.fin-ntruss.com/map-static/v2/raster?w=300&h=300&center=127.1054221,37.3591614&level=16&format=png

​
다음과 같이 png 형식의 지도가 표시됩니다.

scale

고해상도 디스플레이 지원을 위한 옵션을 설정합니다.

• 형식: scale=1|2
  • 1: 저해상도용 이미지 요청. 요청한 w, h 크기(픽셀 단위)의 이미지를 256 x 256 타일 기반으로 생성해서 반환합니다. 이 값이 기본값이며, 생략할 수 있습니다.
  • 2: 고해상도용 이미지 요청. 요청한 w, h 크기의 이미지를 512 x 512 타일 기반으로 생성해서 반환합니다. 즉, scale=1과 동일한 지도 서비스 지역이 반환되지만 각 크기에 포함되는 픽셀은 2배로 늘어납니다. 예들 들어, 320 x 320이 요청되면 640 x 640 이미지를 반환합니다.

저해상도 요청

다음은 지도를 저해상도(scale=1)로 요청하는 예제입니다.

https://naveropenapi.apigw-pub.fin-ntruss.com/map-static/v2/raster?w=300&h=300&center=127.1054221,37.3591614&level=16&scale=1

다음과 같이 저해상도 지도 이미지가 표시됩니다.

고해상도 요청

다음은 지도를 고해상도(scale=2)로 요청하는 예제입니다.

https://naveropenapi.apigw-pub.fin-ntruss.com/map-static/v2/raster?w=300&h=300&center=127.1054221,37.3591614&level=16&scale=2

다음과 같이 고해상도 지도 이미지가 표시됩니다.

언어

​
lang 파라미터를 통해 라벨의 언어를 변경할 수 있습니다.

• 한글 (기본값)

https://naveropenapi.apigw-pub.fin-ntruss.com/map-static/v2/raster?crs=EPSG:4326&w=375&h=258&center=126.96311062857343,37.50843783043817&level=16&lang=ko

• 영어

https://naveropenapi.apigw-pub.fin-ntruss.com/map-static/v2/raster?crs=EPSG:4326&w=375&h=258&center=126.96311062857343,37.50843783043817&level=16&lang=en

• 일본어

https://naveropenapi.apigw-pub.fin-ntruss.com/map-static/v2/raster?crs=EPSG:4326&w=375&h=258&center=126.96311062857343,37.50843783043817&level=16&lang=ja

• 중국어

https://naveropenapi.apigw-pub.fin-ntruss.com/map-static/v2/raster?crs=EPSG:4326&w=375&h=258&center=126.96311062857343,37.50843783043817&level=16&lang=zh

버스 정류장 정보 노출

​
public_transit 파라미터를 통해 버스 정류장 정보를 추가로 노출할 수 있습니다.

https://naveropenapi.apigw-pub.fin-ntruss.com/map-static/v2/raster?w=300&h=300&center=127.1054221,37.3591614&level=16&public_transit

markers

지도 위에 마커를 표시합니다. 요청 개수만큼 마커를 표시하며, 최대 20개를 지원합니다.
markers 파라미터값만 지정하고 center, level 파라미터를 생략하면 요청한 지도 크기를 기준으로 마커가 포함된 최적의 위치와 줌 레벨로 지도를 표시합니다.

• 형식: markers=property:value|property:value1,value2|...

기본 마커

다음은 다양한 기본 마커(type:d) 요청 예제와 결과 이미지입니다.

• 마커 크기별 요청 - size:tiny

https://naveropenapi.apigw-pub.fin-ntruss.com/map-static/v2/raster?w=300&h=300&markers=type:d|size:tiny|pos:127.1054221%2037.3591614

• 마커 크기별 요청 - size:small

https://naveropenapi.apigw-pub.fin-ntruss.com/map-static/v2/raster?w=300&h=300&markers=type:d|size:small|pos:127.1054221%2037.3591614

• 마커 크기별 요청 - size:mid

https://naveropenapi.apigw-pub.fin-ntruss.com/map-static/v2/raster?w=300&h=300&markers=type:d|size:mid|pos:127.1054221%2037.3591614

• 다양한 크기의 마커 요청 - size:mid + small + tiny

https://naveropenapi.apigw-pub.fin-ntruss.com/map-static/v2/raster?w=300&h=300&markers=type:d|size:mid|pos:126.9865479%2037.5612557&markers=type:d|size:small|color:red|pos:126.9870479%2037.5695075%2C126.9950680%2037.5612557%2C126.9743160%2037.5620754&markers=type:d|size:tiny|color:green|pos:126.9810479%2037.5695075%2C126.9950680%2037.5672557%2C126.9843160%2037.5570754

• 색상 변경 - red

https://naveropenapi.apigw-pub.fin-ntruss.com/map-static/v2/raster?w=300&h=300&markers=type:d|size:small|pos:127.1054221%2037.3591614|color:red
https://naveropenapi.apigw-pub.fin-ntruss.com/map-static/v2/raster?w=300&h=300&markers=type:d|size:small|pos:127.1054221%2037.3591614|color:0xFF6355

• 마커 크기 변경 - 0.5배 크기

https://naveropenapi.apigw-pub.fin-ntruss.com/map-static/v2/raster?w=300&h=300&markers=type:d|size:mid|pos:127.1054221%2037.3591614|viewSizeRatio:0.5

• 마커 크기 변경 - 2배 크기

https://naveropenapi.apigw-pub.fin-ntruss.com/map-static/v2/raster?w=300&h=300&markers=type:d|size:mid|pos:127.1054221%2037.3591614|viewSizeRatio:2.0

숫자 마커

• 여러 가지 숫자 마커 조합

https://naveropenapi.apigw-pub.fin-ntruss.com/map-static/v2/raster?w=300&h=300&markers=type:n|size:mid|pos:126.9865479%2037.5612557|label:1&markers=type:n|size:small|color:blue|pos:126.9870479%2037.5695075|label:2&markers=type:n|size:small|color:blue|pos:126.9950680%2037.5612557|label:3&markers=type:n|size:small|color:blue|pos:126.9743160%2037.5620754|label:4

알파벳 마커

• 여러 가지 알파벳 마커 조합

https://naveropenapi.apigw-pub.fin-ntruss.com/map-static/v2/raster?w=300&h=300&markers=type:a|size:mid|pos:126.9865479%2037.5612557|label:a&markers=type:a|size:small|color:blue|pos:126.9870479%2037.5695075|label:b&markers=type:a|size:small|color:blue|pos:126.9950680%2037.5612557|label:c&markers=type:a|size:small|color:blue|pos:126.9743160%2037.5620754|label:d

툴팁 마커

• 마커 크기는 항상 tiny로 고정
• label 내용이 말풍선으로 표현 됩니다.

https://naveropenapi.apigw-pub.fin-ntruss.com/map-static/v2/raster?crs=EPSG:4326&scale=1&format=png&w=375&h=258&markers=type:t|pos:126.9616187%2037.507435|label:%EB%8F%99%EC%9E%91%EA%B5%AC,%20%EC%84%9C%EC%B4%88%EA%B5%AC,%20%EA%B4%80%EC%95%85%EA%B5%AC&markers=type:t|color:blue|pos:126.96060539999999%2037.507685699999996|label:%EB%8F%99%EC%9E%91%EA%B5%AC,%20%EC%84%9C%EC%B4%88%EA%B5%AC,%20%EC%9A%A9%EC%82%B0%EA%B5%AC%20%EB%B0%A9%EB%A9%B4&markers=type:t|color:0xEE3A3A|pos:126.9616377%2037.506708950000004|label:%EB%8F%99%EC%9E%91%EA%B5%AC,%20%EC%84%9C%EC%B4%88%EA%B5%AC,%20%EC%9A%A9%EC%82%B0%EA%B5%AC%20%EB%B0%A9%EB%A9%B4

커스텀 마커

커스텀 마커(external marker)를 설정합니다.
커스텀 마커 설정 시 다음과 같은 제약 사항이 있습니다.

• 커스텀 마커의 최대 크기는 기본 64 x 64 픽셀이며, 레티나 디스플레이 대응 고해상도(scale=2) 요청일 경우 128 x 128 픽셀입니다.
• 커스텀 마커 요청 URL에서 2초 이내에 응답이 없으면 작업을 중지합니다.
• 커스텀 마커는 최대 1일간 내부 캐시로 유지될 수 있습니다. 동일한 URL에 마커 이미지만 달라진 경우 최대 1일까지 갱신되지 않을 수 있습니다.
• svg, image 형식을 지원합니다.

다음은 커스텀 마커를 요청 하는 예제입니다.

https://naveropenapi.apigw-pub.fin-ntruss.com/map-static/v2/raster?w=300&h=300&scale=2&markers=type:e|anchor:center|icon:https://aaa.bbb.com/icon/construction-medium@2x.png|pos:127.0597827%2037.5118871

요청 결과는 다음과 같습니다.

오류 코드