---
title: "raster"
slug: "ai-naver-mapsstaticmap-raster"
tags: ["Static Map", "Maps"]
updated: 2026-09-17T09:10:00Z
published: 2026-09-17T09:10:00Z
canonical: "api-fin.ncloud-docs.com/ai-naver-mapsstaticmap-raster"
---
> ## Documentation Index
> Fetch the complete documentation index at: https://api-fin.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-pub.fin-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.ncloud-docs.com/docs/naveropenapiv3-application#Application%EB%93%B1%EB%A1%9D%EB%B0%A9%EB%B2%95) 을 참고 하세요
```
```
### 요청 파라미터
| 파라미터 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| 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
- 요청
- 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¢er=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¢er=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¢er=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¢er=127.1054221,37.3591614&level=11&maptype=basic
```
다음과 같이 일반 지도가 표시됩니다.
#### 교통 정보 지도 요청
다음은 교통 지도 유형을 요청하는 예제입니다.
```
https://naveropenapi.apigw-pub.fin-ntruss.com/map-static/v2/raster?w=300&h=300¢er=127.1054221,37.3591614&level=11&maptype=traffic
```
다음과 같이 교통 지도가 표시됩니다.
**위성 지도 요청**
다음은 위성 지도 유형을 요청하는 예제입니다.
```
https://naveropenapi.apigw-pub.fin-ntruss.com/map-static/v2/raster?w=300&h=300¢er=127.1054221,37.3591614&level=11&maptype=satellite
```
다음과 같이 위성 지도가 표시됩니다.
#### 위성 배경 지도 요청
다음은 위성 배경 지도 유형을 요청하는 예제입니다.
```
https://naveropenapi.apigw-pub.fin-ntruss.com/map-static/v2/raster?w=300&h=300¢er=127.1054221,37.3591614&level=11&maptype=satellite_base
```
다음과 같이 위성 배경 지도가 표시됩니다.
**지형도 요청**
다음은 지형도 유형을 요청하는 예제입니다.
```
https://naveropenapi.apigw-pub.fin-ntruss.com/map-static/v2/raster?w=300&h=300¢er=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¢er=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¢er=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¢er=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¢er=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¢er=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¢er=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¢er=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¢er=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¢er=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¢er=127.1054221,37.3591614&level=16&public_transit
```
### 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