raster

Prev Next

개요

네이버 지도에서는 JavaScript를 사용하지 않고, 웹 페이지에서 네이버 지도를 이용해 쉽게 위치를 표시하고 안내할 수 있는 Static Map(정적 지도) 서비스를 제공합니다.

HTML 페이지 내에 원하는 이미지를 가져오려면 요청 형식에 맞는 URL을 만들어 <img> 태그에 배치하면 됩니다.

요청

ID-KEY 기반 인증

curl "https://naveropenapi.apigw.gov-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.gov-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: 일반(기본값)
satellite: 위성
terrain: 지형도
format string N - 반환 이미지 형식

입력 가능한 값:
png: 24 비트(기본값)
jpg 또는 jpeg: 압축 품질 85%, 24 비트
scale int N - 고해상도 디스플레이 지원을 위한 옵션

입력 가능한 값:
1: 저해상도(기본값)
2: 고해상도
markers string N 마커 종류별 스타일 및 위치 지정

요청 헤더

해당 헤더는 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

  • 요청
    • https://naveropenapi.apigw.gov-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.gov-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.gov-ntruss.com/map-static/v2/raster?w=300&h=300&center=127.1054221,37.3591614&level=16

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

default-center.png

level

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

  • 형식: level=줌 레벨

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

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

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

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

default-level.png

w, h

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

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

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

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

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

default-wh.png

maptype

지도 유형을 설정합니다.

  • 형식: maptype=basic|satellite|terrain
    • basic: 일반 지도 유형
    • satellite: 위성 지도 유형
    • terrain: 지형도 유형

일반 지도 요청

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

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

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

default-maptype-basic.png

위성 지도 요청

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

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

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

default-maptype-satellite.png

지형도 요청

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

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

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

default-maptype-terrain.png

format

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

  • 형식: format=이미지 형식(png 또는 jpg 또는 jpeg)

    반환되는 이미지 형식은 png, jpeg(jpg)입니다.
  • png(기본값)는 24 비트 PNG 형식을 지원합니다. 값을 별도로 명시하지 않거나 지원되는 형식으로 명시하지 않으면 png로 간주합니다.
  • jpeg(jpg)는 압축 품질 85%의 24 비트 JPEG 형식을 지원합니다.(jpg와 jpeg 키워드를 모두 지원합니다.)

png 이미지 형식 요청

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

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

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

default-format-png.png

jpeg(jpg) 이미지 형식 요청

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

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

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

default-format-jpg.jpg

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

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

default-scale-1.png

고해상도 요청

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

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

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

default-scale-2.png

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.gov-ntruss.com/map-static/v2/raster?w=300&h=300&markers=type:d|size:tiny|pos:127.1054221%2037.3591614

marker-1.png

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

marker-2.png

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

marker-3.png

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

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

marker-5.png

  • 마커 크기 변경 - 0.5배 크기
https://naveropenapi.apigw.gov-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.png

  • 마커 크기 변경 - 2배 크기
https://naveropenapi.apigw.gov-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.png

숫자 마커

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

알파벳 마커

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

툴팁 마커

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

커스텀 마커
커스텀 마커(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.gov-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.png

에러 코드

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