Login
      내용 x
      raster
        • 인쇄
        • PDF
        내용

        raster

          • 인쇄
          • PDF
          기사 요약

          개요

          네이버 지도에서는 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값}">

          요청 파라미터

          파라미터타입필수 여부설명
          crsstringN좌표 체계를 나타냄
          값을 생략할 경우 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
          centerstringY or N- 중심 좌표.
          'center=X 좌표,Y 좌표' 형식으로 입력
          X 좌표, Y 좌표 순서는 좌표 체계 정의를 따름
          예를 들어, WGS84 경위도 좌표 체계인 경우 입력 형식은 <경도,위도> 순서
          markers 파라미터 설정 시 생략 가능
          levelintY or N- 줌 레벨
          markers 파라미터 설정 시 생략 가능
          입력 범위: 0~20
          w, hintY- 가로, 세로 이미지 크기.
          'w=크기&h=크기' 형식으로 입력
          최소 1~1024 픽셀 지원.
          maptypestringN- 지도 유형

          입력 가능한 값:
          basic: 일반(기본값)
          satellite: 위성
          terrain: 지형도
          formatstringN- 반환 이미지 형식

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

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

          요청 헤더

          해당 헤더는 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|...
          속성값필수 여부기본값설명설정 예
          typed(default), n(number), a(alphabet), t(tooltip)Nd마커 유형type:d 또는 type:n
          sizetiny, small, midNmid마커 크기 (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
          labelA-Z, 0-9N없음생략하면 마커만 표시label:A, label:9
          posx1 y1,x2 y2, ...Y없음마커가 표시될 위치 (여러 개 입력 가능)pos:127.15(공백)38.15,126.12(공백)37.523
          viewSizeRatio0.1~2.0N1.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 형식을 지원합니다.
          속성값필수 여부기본값설명설정 예
          typee(external)Y없음커스텀 마커 타입type:e
          iconURL 경로Y없음URL 경로 (png, svg 타입 지원)icon:http://aaa/bbb.svg 또는 icon:http://aaa/bbb.png
          anchor마커 표시 위치Nbottom(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
          posx1 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

          에러 코드

          HttpStatusCodeErrorCodeErrorMessageDescription
          400100Bad request요청에 유효하지 않은 파라미터가 있음을 나타냄
          500900Internal error서버 내부에 오류 발생 의미
          지속적으로 문제 발생 시 공식 문의 채널 확인 바람
          503500Service Unavailable시스템 유지보수로 인해 일시적인 응답 불가 상태
          잠시 후 재시도 바람
          504510Gateway Timeout시스템 과부하로 인해 일시적인 응답 불가 상태
          잠시 후 재시도 바람
          이 문서가 도움이 되었습니까?
          What's Next
          Change password!
          Changing your password will log you out immediately. Use the new password to log back in.
          Change profile
          Success!
          First name must have atleast 2 characters. Numbers and special characters are not allowed.
          Last name must have atleast 1 characters. Numbers and special characters are not allowed.
          Enter a valid email
          Enter a valid password
          Your profile has been successfully updated.
          Logout