raster

개요

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

요청

ID-KEY 기반 인증

curl "https://naveropenapi.apigw.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 src="https://naveropenapi.apigw.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값}">

요청 파라미터

파라미터 타입 필수 여부 설명
crs string N 좌표 체계를 나타냅니다.
값을 생략할 경우 WGS84 경위도 좌표 체계(EPSG:4326)로 인식합니다.

지원하는 좌표 체계는 다음과 같습니다.
- EPSG:4326: WGS84 경위도
- NHN:2048: UTMK
- NHN:128: 카텍 TM128
- EPSG:4258: GRS80 경위도
- EPSG:4162: Bessel 경위도
- EPSG:2096: Korea East Belt
- EPSG:2097: Korea Central Belt
- EPSG:2098: Korea West Belt
- EPSG:3857 or EPSG:900913: Google Maps
- EPSG:5179: Korea 2000 / Unified CS
center string Y or N 중심 좌표.
‘center=X 좌표,Y 좌표’ 형식으로 입력합니다.
X 좌표, Y 좌표 순서는 좌표 체계 정의를 따릅니다.
예를 들어, WGS84 경위도 좌표 체계인 경우 입력 형식은 <경도,위도> 순서입니다.
markers 파라미터 설정 시 생략할 수 있습니다.
level int Y or N 줌 레벨. markers 파라미터 설정 시 생략할 수 있습니다.
- 입력 범위: 0~20
w, h int Y 가로, 세로 이미지 크기.
‘w=크기&h=크기’ 형식으로 입력.
최소 1~1024 픽셀 지원.
maptype string N 지도 유형. 입력 가능한 값은 다음과 같습니다.
- basic: 일반(기본값)
- traffic: 교통 지도
- satellite: 위성
- satellite_base: 위성 배경
- terrain: 지형도
format string N 반환 이미지 형식. 입력 가능한 값은 다음과 같습니다.
- jpg 또는 jpeg(기본값): 압축 품질 85%, 24 비트
- png8: 8 비트
- png: 24 비트
scale int N 고해상도 디스플레이 지원을 위한 옵션. 입력 가능한 값은 다음과 같습니다.
- 1: 저해상도(기본값)
- 2: 고해상도
markers string N 마커 종류별 스타일 및 위치 지정
lang string N 라벨 언어 설정. 입력 가능한 값은 다음과 같습니다.
- ko: 한글(기본값)
- en: 영어
- ja: 일본어
- zh: 중국어
public_transit boolean N public_transit 파라미터 전달시 대중교통 정보를 노출합니다
dataversion string Y 서비스에서 사용할 dataversion 파라미터를 전달합니다. (CDN 캐시 무효화)

요청 헤더

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

헤더명 설명
X-NCP-APIGW-API-KEY-ID 앱 등록 시 발급받은 Client ID
X-NCP-APIGW-API-KEY-ID:{Client ID}
X-NCP-APIGW-API-KEY 앱 등록 시 발급 받은 Client Secret
X-NCP-APIGW-API-KEY:{Client Secret}

요청 바디

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

DataVersion API 와 StaticMap API 연동

DataVersion API 연동 필요성

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

Data Version API

  • 요청
  • 결과 포맷
    • json 타입 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.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.ntruss.com/map-static/v2/raster?w=300&h=300&center=127.1054221,37.3591614&level=16

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

default-center

level

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

  • 형식: level=줌 레벨

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

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

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

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

default-level

w, h

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

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

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

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

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

default-wh

maptype

지도 유형을 설정합니다.

  • 형식: maptype=basic|satellite|terrain

    • basic: 일반 지도 유형
    • traffic: 교통 정보 지도 유형 (일반 지도 베이스)
    • satellite: 위성 지도 유형
    • satellite_base: 위성 배경 지도 유형
    • terrain: 지형도 유형 ​

      일반 지도 요청

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

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

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

default-maptype-basic

교통 정보 지도 요청

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

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

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

default-maptype-traffic

위성 지도 요청

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

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

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

default-maptype-satellite

위성 배경 지도 요청

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

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

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

default-maptype-satellite_base

지형도 요청

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

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

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

default-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.ntruss.com/map-static/v2/raster?w=300&h=300&center=127.1054221,37.3591614&level=16&format=jpg
    

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

default-format-jpg

png8 이미지 형식 요청

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

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

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

default-format-jpg

png 이미지 형식 요청

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

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

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

default-format-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.ntruss.com/map-static/v2/raster?w=300&h=300&center=127.1054221,37.3591614&level=16&scale=1

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

default-scale-1

고해상도 요청

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

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

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

default-scale-2

언어

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

  • 한글 (기본값)
https://naveropenapi.apigw.ntruss.com/map-static/v2/raster?crs=EPSG:4326&w=375&h=258&center=126.96311062857343,37.50843783043817&level=16&lang=ko

default-lang-ko

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

default-lang-en

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

default-lang-ja

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

default-lang-zh

버스 정류장 정보 노출

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

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

default-lang-zh

markers

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

  • 형식: markers=property:value|property:value1,value2|…
속성 필수 여부 기본값 설명 설정 예
type d(default), n(number), a(alphabet), t(tooltip) N d 마커 유형 type:d 또는 type:n
size tiny, small, mid N mid 마커 크기. tiny일 경우 label 표현은 생략됨. size:tiny 또는 size:small
color 사전 정의 색상 또는 0xFFFFFF(24 비트 색상값) N 없음 생략하면 기본 색상값인 0x08da76으로 표시.
사전 정의 색상은 대표적으로 사용하는 색상을 쉽게 사용할 수 있도록 문자열로 정의한 값입니다.
사전 정의 색상은 아래와 같습니다.
- Default: 0x08DA76
- Blue: 0x029DFF
- Orange: 0xFE8C52
- Yellow: 0xFFBA01
- Red: 0xFF6355
- Brown: 0xA4885B
- Green: 0x63AA41
- Purple: 0xD182C8
- Gray: 0x666666
color:green 또는 color:0x00FF00
label A-Z, 0-9 N 없음 생략하면 마커만 표시 label:A, label:9
pos x1 y1,x2 y2, … Y 없음 마커가 표시될 위치. 여러 개 입력 가능. pos:127.15(공백)38.15,126.12(공백)37.523
viewSizeRatio 0.1~2.0 N 1.0 마커 유형(type)과 크기(size)별 기본 디자인 기반으로 마커의 크기 조절.
- 소수점 1자리만 지원
- 0.1보다 작으면 0.1, 2.0보다 크면 2.0으로 설정
viewSizeRatio:2.0

기본 마커

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

  • 마커 크기별 요청 - size:tiny
https://naveropenapi.apigw.ntruss.com/map-static/v2/raster?w=300&h=300&markers=type:d|size:tiny|pos:127.1054221%2037.3591614

marker-1

  • 마커 크기별 요청 - size:small
https://naveropenapi.apigw.ntruss.com/map-static/v2/raster?w=300&h=300&markers=type:d|size:small|pos:127.1054221%2037.3591614

marker-2

  • 마커 크기별 요청 - size:mid
https://naveropenapi.apigw.ntruss.com/map-static/v2/raster?w=300&h=300&markers=type:d|size:mid|pos:127.1054221%2037.3591614

marker-3

  • 다양한 크기의 마커 요청 - size:mid + small + tiny
https://naveropenapi.apigw.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

marker-4

  • 색상 변경 - red
https://naveropenapi.apigw.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.ntruss.com/map-static/v2/raster?w=300&h=300&markers=type:d|size:small|pos:127.1054221%2037.3591614|color:0xFF6355

marker-5

  • 마커 크기 변경 - 0.5배 크기
https://naveropenapi.apigw.ntruss.com/map-static/v2/raster?w=300&h=300&markers=type:d|size:mid|pos:127.1054221%2037.3591614|viewSizeRatio:0.5

marker-6

  • 마커 크기 변경 - 2배 크기
https://naveropenapi.apigw.ntruss.com/map-static/v2/raster?w=300&h=300&markers=type:d|size:mid|pos:127.1054221%2037.3591614|viewSizeRatio:2.0

marker-7

숫자 마커

  • 여러 가지 숫자 마커 조합
https://naveropenapi.apigw.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

marker-8

알파벳 마커

  • 여러 가지 알파벳 마커 조합
https://naveropenapi.apigw.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

marker-9

툴팁 마커

  • 마커 크기는 항상 tiny로 고정
  • label 내용이 말풍선으로 표현 됩니다.
https://naveropenapi.apigw.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

marker-11

커스텀 마커

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

  • 커스텀 마커의 최대 크기는 기본 64 x 64 픽셀이며, 레티나 디스플레이 대응 고해상도(scale=2) 요청일 경우 128 x 128 픽셀입니다.
  • 커스텀 마커 요청 URL에서 2초 이내에 응답이 없으면 작업을 중지합니다.
  • 커스텀 마커는 최대 1일간 내부 캐시로 유지될 수 있습니다. 동일한 URL에 마커 이미지만 달라진 경우 최대 1일까지 갱신되지 않을 수 있습니다.
  • svg, image 형식을 지원합니다.
속성 필수 여부 기본값 설명 설정 예
type e(external) Y 없음 커스텀 마커 타입 type:e
icon URL 경로 Y 없음 URL 경로. png, svg 타입 지원 icon:http://aaa/bbb.svg 또는 icon:http://aaa/bbb.png
anchor 마커 표시 위치 N bottom(0.5, 1.0) 지도 이미지에서 마커 이미지 위치의 오프셋값. 마커 표시 위치를 세부적으로 조정해야 할 때 설정합니다.
double 또는 text 타입으로 설정할 수 있습니다.
double 타입으로 입력할 경우 소수점 이하 두 자리(0.00~1.00)까지 표현 가능하며, xOffset, yOffset 순서로 입력합니다.(예: 왼쪽 위는 0.0,0.0, 오른쪽 아래는 1.0,1.0)
text 타입으로 입력할 경우 입력 가능한 값은 다음과 같습니다.
- top: 0.5, 0.0
- bottom: 0.5, 1.0(기본값)
- left: 0.0, 0.5
- right: 1.0, 0.5
- center: 0.5, 0.5
- topleft: 0.0, 0.0
- topright: 0.0, 1.0
- bottomleft: 1.0, 0.0
- bottomright: 1.0, 1.0
예를 들어, 핀 모양의 아이콘일 경우 보통 이미지의 가운데 맨 아래쪽을 위치로 표시하므로, double형으로 입력할 때는 double:0.5,1.0으로 입력하고, text형으로 입력할 때는 text:bottom으로 입력합니다.
anchor:0.5,0.0 또는 anchor:top
pos x1 y1,x2 y2, … Y 없음 마커가 표시될 위치. 여러 개 입력 가능. pos:127 38,126 37

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

https://naveropenapi.apigw.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

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

marker-10

오류 코드

HttpStatusCode ErrorCode ErrorMessage Description
400 100 Bad request 요청에 유효하지 않은 파라미터가 있음을 나타냅니다.
500 900 Internal error 서버 내부에 오류가 발생했음을 의미합니다.
지속적으로 문제 발생 시 공식 문의 채널을 확인해 주세요.
503 500 Service Unavailable 시스템 유지보수로 인해 일시적인 응답 불가 상태입니다.
잠시 후 재시도하시기 바랍니다.
504 510 Gateway Timeout 시스템 과부하로 인해 일시적인 응답 불가 상태입니다.
잠시 후 재시도하시기 바랍니다.