---
title: "raster"
slug: "ai-naver-mapsstaticmap-raster"
tags: ["Static Map", "Maps"]
updated: 2026-10-22T10:46:41Z
published: 2026-10-22T10:46:41Z
canonical: "api-gov.ncloud-docs.com/ai-naver-mapsstaticmap-raster"
---
> ## Documentation Index
> Fetch the complete documentation index at: https://api-gov.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# raster
## 개요
네이버 지도에서는 JavaScript를 사용하지 않고, 웹 페이지에서 네이버 지도를 이용해 쉽게 위치를 표시하고 안내할 수 있는 Static Map(정적 지도) 서비스를 제공합니다. HTML 페이지 내에 원하는 이미지를 가져오려면 요청 형식에 맞는 URL을 만들어 ![]()
태그에 배치하면 됩니다.
## 요청
### ID-KEY 기반 인증
```
curl "https://naveropenapi.apigw.gov-ntruss.com/map-static/v2/raster?w=300&h=300¢er=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 등록 방법](https://guide-gov.ncloud-docs.com/docs/naveropenapiv3-application)** 을 참고 하세요
```
```
### 요청 파라미터
| 파라미터 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| 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¢er=127.1054221,37.3591614&level=16
```
아래 그림의 정중앙이 중심 좌표가 됩니다.
#### level
지도의 줌 레벨을 설정합니다.
- 형식: level=줌 레벨
줌 레벨은 최소 0, 최대 20 레벨까지 지원합니다. 단, markers 파라미터를 설정해 최적화된 줌 레벨과 위치로 지도를 표시할 때는 center와 level 파라미터를 생략할 수 있습니다.
다음은 레벨이 11인 지도를 요청하는 예제입니다.
```
https://naveropenapi.apigw.gov-ntruss.com/map-static/v2/raster?w=300&h=300¢er=127.1054221,37.3591614&level=11
```
다음과 같이 11 레벨의 지도가 표시됩니다.
#### 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¢er=127.1054221,37.3591614&level=16
```
다음과 같이 요청한 크기의 지도가 표시됩니다.
#### maptype
지도 유형을 설정합니다.
- 형식: maptype=basic|satellite|terrain
- basic: 일반 지도 유형
- satellite: 위성 지도 유형
- terrain: 지형도 유형
**일반 지도 요청**
다음은 일반 지도 유형을 요청하는 예제입니다.
```
https://naveropenapi.apigw.gov-ntruss.com/map-static/v2/raster?w=300&h=300¢er=127.1054221,37.3591614&level=11&maptype=basic
```
다음과 같이 일반 지도가 표시됩니다.
**위성 지도 요청**
다음은 위성 지도 유형을 요청하는 예제입니다.
```
https://naveropenapi.apigw.gov-ntruss.com/map-static/v2/raster?w=300&h=300¢er=127.1054221,37.3591614&level=11&maptype=satellite
```
다음과 같이 위성 지도가 표시됩니다.
**지형도 요청**
다음은 지형도 유형을 요청하는 예제입니다.
```
https://naveropenapi.apigw.gov-ntruss.com/map-static/v2/raster?w=300&h=300¢er=127.1054221,37.3591614&level=11&maptype=terrain
```
다음과 같이 지형도가 표시됩니다.
#### 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¢er=127.1054221,37.3591614&level=16&format=png
```
다음과 같이 png 형식의 지도가 표시됩니다.
**jpeg(jpg) 이미지 형식 요청**
다음은 jpeg(jpg) 이미지 형식으로 지도를 요청하는 예제입니다.
```
https://naveropenapi.apigw.gov-ntruss.com/map-static/v2/raster?w=300&h=300¢er=127.1054221,37.3591614&level=16&format=jpg
```
다음과 같이 jpeg 형식의 지도가 표시됩니다.
#### 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¢er=127.1054221,37.3591614&level=16&scale=1
```
다음과 같이 저해상도 지도 이미지가 표시됩니다.
**고해상도 요청**
다음은 지도를 고해상도(scale=2)로 요청하는 예제입니다.
```
https://naveropenapi.apigw.gov-ntruss.com/map-static/v2/raster?w=300&h=300¢er=127.1054221,37.3591614&level=16&scale=2
```
다음과 같이 고해상도 지도 이미지가 표시됩니다.
#### 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
```
- 마커 크기별 요청 - 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
```
- 마커 크기별 요청 - 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
```
- 다양한 크기의 마커 요청 - 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
```
- 색상 변경 - 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
```
- 마커 크기 변경 - 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
```
- 마커 크기 변경 - 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
```
**숫자 마커**
- 여러 가지 숫자 마커 조합
```
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
```
**알파벳 마커**
- 여러 가지 알파벳 마커 조합
```
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
```
#### 툴팁 마커
- 마커 크기는 항상 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
```
**커스텀 마커** 커스텀 마커(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
```
요청 결과는 다음과 같습니다.
## 에러 코드
| HttpStatusCode | ErrorCode | ErrorMessage | Description |
| --- | --- | --- | --- |
| 400 | 100 | Bad request | 요청에 유효하지 않은 파라미터가 있음을 나타냄 |
| 500 | 900 | Internal error | 서버 내부에 오류 발생 의미 지속적으로 문제 발생 시 [공식 문의 채널](https://www.gov-ncloud.com/support/question) 확인 바람 |
| 503 | 500 | Service Unavailable | 시스템 유지보수로 인해 일시적인 응답 불가 상태 잠시 후 재시도 바람 |
| 504 | 510 | Gateway Timeout | 시스템 과부하로 인해 일시적인 응답 불가 상태 잠시 후 재시도 바람 |