The latest service changes have not yet been reflected in this content. We will update the content as soon as possible. Please refer to the Korean version for information on the latest updates.
Available in VPC
Load a NAVER Maps image (static map) of the specified size based on the entered coordinates without using JavaScript or loading a dynamic page. You can customize the map image through the supported parameters (map type, image format, resolution, markers, etc.).
Request
The following describes the request format for the endpoint.
| Method | URI | Description |
|---|---|---|
| GET | /raster | ID-KEY authentication |
| GET | /raster-cors | HTTP Referer authentication |
- To call the API using the HTTP Referer authentication method, you must enter the web service URL when registering your application. See the following guides.
- If you're using the HTTP Referer authentication method, you can make the request by adding an HTML tag as follows.
<img src="https://naveropenapi.apigw.ntruss.com/map-static/v2/raster-cors?w=300&h=300¢er=127.1054221,37.3591614&level=16&X-NCP-APIGW-API-KEY-ID={API Gateway API Key ID}">
Request headers
For headers common to all Maps APIs, see Common Maps headers.
Request query parameters
The following describes the request query parameters.
| Field | Type | Required | Description |
|---|---|---|---|
crs |
String | Optional | Coordinate system
|
center |
String | Conditional | Center coordinates (X coordinate,Y coordinate)
|
level |
Integer | Conditional | Zoom level
|
w, h |
Integer | Required | Image width and height
|
maptype |
String | Optional | Map type
|
format |
String | Optional | Map image format
|
scale |
Integer | Optional | Resolution
|
markers |
String | Conditional | Marker settings
|
lang |
String | Optional | Label language
|
dataversion |
String | Optional | Version information
|
markers
The following describes markers.
| Field | Value | Required | Description |
|---|---|---|---|
type |
String | Optional | Marker type
|
size |
String | Optional | Marker size
|
color |
String | Optional | Marker color
|
label |
String | Optional | Marker label
|
pos |
String | Required | Marker position (X, Y coordinates)
|
viewSizeRatio |
Float | Optional | Marker size ratio
|
icon |
String | Conditional | Custom marker icon URL
|
anchor |
String, Double | Optional | Marker display position
|
Restrictions when setting up custom markers
- The maximum size of a custom marker is 64 x 64 pixels by default, or 128 x 128 pixels if requested in high resolution (
scale=2) for retina displays. - If there is no response from the custom marker request URL within 2 seconds, the operation is stopped.
- Custom markers can be kept in an internal cache for up to 1 day, so if you change the marker image on the same URL, it may not reflect the change for up to 1 day.
Data Version API
The following describes the Data Version API.
- Request
Method URL GET https://naveropenapi.apigw.ntruss.com/map-static/v2/lastversion - Response
Field Type Required Description versionString - Version information major_version.minor_versionformatmajor_version: Change on major updates, keep the same as the one-tile map major version (updated once every 2 months)minor_version: Raise the version on minor updates (updated once or twice a month)
intervalLong - Recommended update interval (second)
Request example
The following is a sample request.
This guide provides examples of using the ID-KEY authentication method.
center
The following is a sample request for a map image with center coordinates (center) of 127.1054221, 37.3591614.
curl --location --request GET 'https://naveropenapi.apigw.ntruss.com/map-static/v2/raster?w=300&h=300¢er=127.1054221,37.3591614&level=16' \
--header 'x-ncp-apigw-api-key-id: {API Key ID}' \
--header 'x-ncp-apigw-api-key: {API Key}'
level
The following is a sample request for a map image with zoom level (level) of 11.
curl --location --request GET 'https://naveropenapi.apigw.ntruss.com/map-static/v2/raster?w=300&h=300¢er=127.1054221,37.3591614&level=11' \
--header 'x-ncp-apigw-api-key-id: {API Key ID}' \
--header 'x-ncp-apigw-api-key: {API Key}'
w, h
The following is a sample request for a map image with size (w x h) of 300 x 200 pixels.
curl --location --request GET 'https://naveropenapi.apigw.ntruss.com/map-static/v2/raster?w=300&h=200¢er=127.1054221,37.3591614&level=16' \
--header 'x-ncp-apigw-api-key-id: {API Key ID}' \
--header 'x-ncp-apigw-api-key: {API Key}'
maptype=basic
The following is a sample request for a map image with map type (maptype) of general map (basic).
curl --location --request GET 'https://naveropenapi.apigw.ntruss.com/map-static/v2/raster?w=300&h=300¢er=127.1054221,37.3591614&level=11&maptype=basic' \
--header 'x-ncp-apigw-api-key-id: {API Key ID}' \
--header 'x-ncp-apigw-api-key: {API Key}'
maptype=traffic
The following is a sample request for a map image with map type (maptype) of traffic information map (traffic).
curl --location --request GET 'https://naveropenapi.apigw.ntruss.com/map-static/v2/raster?w=300&h=300¢er=127.1054221,37.3591614&level=11&maptype=traffic' \
--header 'x-ncp-apigw-api-key-id: {API Key ID}' \
--header 'x-ncp-apigw-api-key: {API Key}'
maptype=satellite
The following is a sample request for a map image with map type (maptype) of satellite map (satellite).
curl --location --request GET 'https://naveropenapi.apigw.ntruss.com/map-static/v2/raster?w=300&h=300¢er=127.1054221,37.3591614&level=11&maptype=satellite' \
--header 'x-ncp-apigw-api-key-id: {API Key ID}' \
--header 'x-ncp-apigw-api-key: {API Key}'
maptype=satellite_base
The following is a sample request for a map image with map type (maptype) of satellite background map (satellite_base).
curl --location --request GET 'https://naveropenapi.apigw.ntruss.com/map-static/v2/raster?w=300&h=300¢er=127.1054221,37.3591614&level=11&maptype=satellite_base' \
--header 'x-ncp-apigw-api-key-id: {API Key ID}' \
--header 'x-ncp-apigw-api-key: {API Key}'
maptype=terrain
The following is a sample request for a map image with map type (maptype) of terrain map (terrain).
curl --location --request GET 'https://naveropenapi.apigw.ntruss.com/map-static/v2/raster?w=300&h=300¢er=127.1054221,37.3591614&level=11&maptype=terrain' \
--header 'x-ncp-apigw-api-key-id: {API Key ID}' \
--header 'x-ncp-apigw-api-key: {API Key}'
format=jpg
The following is a sample request for a map image with image format (format) of jpg (jpeg).
curl --location --request GET 'https://naveropenapi.apigw.ntruss.com/map-static/v2/raster?w=300&h=300¢er=127.1054221,37.3591614&level=16&format=jpg' \
--header 'x-ncp-apigw-api-key-id: {API Key ID}' \
--header 'x-ncp-apigw-api-key: {API Key}'
format=png8
The following is a sample request for a map image with image format (format) of png8.
curl --location --request GET 'https://naveropenapi.apigw.ntruss.com/map-static/v2/raster?w=300&h=300¢er=127.1054221,37.3591614&level=16&format=png8' \
--header 'x-ncp-apigw-api-key-id: {API Key ID}' \
--header 'x-ncp-apigw-api-key: {API Key}'
format=png
The following is a sample request for a map image with image format (format) of png.
curl --location --request GET 'https://naveropenapi.apigw.ntruss.com/map-static/v2/raster?w=300&h=300¢er=127.1054221,37.3591614&level=16&format=png' \
--header 'x-ncp-apigw-api-key-id: {API Key ID}' \
--header 'x-ncp-apigw-api-key: {API Key}'
scale=1
The following is a sample request for a map image with a low resolution (scale=1).
curl --location --request GET 'https://naveropenapi.apigw.ntruss.com/map-static/v2/raster?w=300&h=300¢er=127.1054221,37.3591614&level=16&scale=1' \
--header 'x-ncp-apigw-api-key-id: {API Key ID}' \
--header 'x-ncp-apigw-api-key: {API Key}'
scale=2
The following is a sample request for a map image with a high resolution (scale=2).
curl --location --request GET 'https://naveropenapi.apigw.ntruss.com/map-static/v2/raster?w=300&h=300¢er=127.1054221,37.3591614&level=16&scale=2' \
--header 'x-ncp-apigw-api-key-id: {API Key ID}' \
--header 'x-ncp-apigw-api-key: {API Key}'
lang=ko
The following is a sample request for a map image with label language (lang) of Korean (ko).
curl --location --request GET 'https://naveropenapi.apigw.ntruss.com/map-static/v2/raster?crs=EPSG:4326&w=375&h=258¢er=126.96311062857343,37.50843783043817&level=16&lang=ko' \
--header 'x-ncp-apigw-api-key-id: {API Key ID}' \
--header 'x-ncp-apigw-api-key: {API Key}'
lang=en
The following is a sample request for a map image with label language (lang) of English (en).
curl --location --request GET 'https://naveropenapi.apigw.ntruss.com/map-static/v2/raster?crs=EPSG:4326&w=375&h=258¢er=126.96311062857343,37.50843783043817&level=16&lang=en' \
--header 'x-ncp-apigw-api-key-id: {API Key ID}' \
--header 'x-ncp-apigw-api-key: {API Key}'
lang=ja
The following is a sample request for a map image with label language (lang) of Japanese (ja).
curl --location --request GET 'https://naveropenapi.apigw.ntruss.com/map-static/v2/raster?crs=EPSG:4326&w=375&h=258¢er=126.96311062857343,37.50843783043817&level=16&lang=ja' \
--header 'x-ncp-apigw-api-key-id: {API Key ID}' \
--header 'x-ncp-apigw-api-key: {API Key}'
lang=zh
The following is a sample request for a map image with label language (lang) of Chinese (Simplified) (zh).
curl --location --request GET 'https://naveropenapi.apigw.ntruss.com/map-static/v2/raster?crs=EPSG:4326&w=375&h=258¢er=126.96311062857343,37.50843783043817&level=16&lang=zh' \
--header 'x-ncp-apigw-api-key-id: {API Key ID}' \
--header 'x-ncp-apigw-api-key: {API Key}'
markers=size:tiny
The following is a sample request for a map image with a default marker size (size) of tiny.
curl --location --request GET 'https://naveropenapi.apigw.ntruss.com/map-static/v2/raster?w=300&h=300&markers=type:d|size:tiny|pos:127.1054221%2037.3591614' \
--header 'x-ncp-apigw-api-key-id: {API Key ID}' \
--header 'x-ncp-apigw-api-key: {API Key}'
markers=size:small
The following is a sample request for a map image with a default marker size (size) of small.
curl --location --request GET 'https://naveropenapi.apigw.ntruss.com/map-static/v2/raster?w=300&h=300&markers=type:d|size:small|pos:127.1054221%2037.3591614' \
--header 'x-ncp-apigw-api-key-id: {API Key ID}' \
--header 'x-ncp-apigw-api-key: {API Key}'
markers=size:mid
The following is a sample request for a map image with a default marker size (size) of mid.
curl --location --request GET 'https://naveropenapi.apigw.ntruss.com/map-static/v2/raster?w=300&h=300&markers=type:d|size:mid|pos:127.1054221%2037.3591614' \
--header 'x-ncp-apigw-api-key-id: {API Key ID}' \
--header 'x-ncp-apigw-api-key: {API Key}'
markers=size:mid&markers=size:small&markers=size:tiny
The following is a sample request for a map image that displays all default markers with (size) of mid, small, and tiny.
curl --location --request GET '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' \
--header 'x-ncp-apigw-api-key-id: {API Key ID}' \
--header 'x-ncp-apigw-api-key: {API Key}'
markers=color:red
The following is a sample request for a map image with a default marker color (color) of red (red).
- Request with predefined color value
curl --location --request GET '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' \ --header 'x-ncp-apigw-api-key-id: {API Key ID}' \ --header 'x-ncp-apigw-api-key: {API Key}' - Request with 24-bit color value
curl --location --request GET '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' \ --header 'x-ncp-apigw-api-key-id: {API Key ID}' \ --header 'x-ncp-apigw-api-key: {API Key}'
markers=viewSizeRatio:0.5
The following is a sample request for a map image that changes the ratio of the default marker size (viewSizeRatio) to 0.5 times (0.5).
curl --location --request GET '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' \
--header 'x-ncp-apigw-api-key-id: {API Key ID}' \
--header 'x-ncp-apigw-api-key: {API Key}'
markers=viewSizeRatio:2.0
The following is a sample request for a map image that changes the ratio of the default marker size (viewSizeRatio) to 2 times (2.0).
curl --location --request GET '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' \
--header 'x-ncp-apigw-api-key-id: {API Key ID}' \
--header 'x-ncp-apigw-api-key: {API Key}'
markers=type:n|label:{number}
The following is a sample request for a map image that displays numeric markers.
curl --location --request GET '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' \
--header 'x-ncp-apigw-api-key-id: {API Key ID}' \
--header 'x-ncp-apigw-api-key: {API Key}'
markers=type:a|label:{alphabet}
The following is a sample request for a map image that displays alphabetical markers.
curl --location --request GET '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' \
--header 'x-ncp-apigw-api-key-id: {API Key ID}' \
--header 'x-ncp-apigw-api-key: {API Key}'
markers=type:t|label:{tooltip}
The following is a sample request for a map image that displays tooltip markers.
curl --location --request GET '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' \
--header 'x-ncp-apigw-api-key-id: {API Key ID}' \
--header 'x-ncp-apigw-api-key: {API Key}'
markers=type:e
The following is a sample request for a map image that displays custom markers.
curl --location --request GET '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' \
--header 'x-ncp-apigw-api-key-id: {API Key ID}' \
--header 'x-ncp-apigw-api-key: {API Key}'
Response
The following describes the response format.
Response status codes
The following describes the response status codes.
| HTTP status code | Code | Message | Description |
|---|---|---|---|
| 400 | 100 | Bad request | Invalid parameters entered in the request |
| 500 | 900 | Internal error | Maps server error
|
| 503 | 500 | Service Unavailable | Temporary unavailable due to system maintenance
|
| 504 | 510 | Gateway Timeout | Temporarily unavailable due to system overload
|
For response status codes common to all Maps APIs, see Common Maps response status codes.
Response example
The following is a sample example.
center
The following is a sample response for a map image with center coordinates (center) of 127.1054221, 37.3591614.

level
The following is a sample response for a map image with zoom level (level) of 11.

w, h
The following is a sample response for a map image with size (w x h) of 300 x 200 pixels.

maptype=basic
The following is a sample response for a map image with map type (maptype) of general map (basic).

maptype=traffic
The following is a sample response for a map image with map type (maptype) of traffic information map (traffic).

maptype=satellite
The following is a sample response for a map image with map type (maptype) of satellite map (satellite).

maptype=satellite_base
The following is a sample response for a map image with map type (maptype) of satellite background map (satellite_base).

maptype=terrain
The following is a sample response for a map image with map type (maptype) of terrain map (terrain).

format=jpg
The following is a sample response for a map image with image format (format) of jpg (jpeg).

format=png8
The following is a sample response for a map image with image format (format) of png8.

format=png
The following is a sample response for a map image with image format (format) of png.

scale=1
The following is a sample response for a map image with a low resolution (scale=1).

scale=2
The following is a sample response for a map image with a high resolution (scale=2).

lang=ko
The following is a sample response for a map image with label language (lang) of Korean (ko).

lang=en
The following is a sample response for a map image with label language (lang) of English (en).

lang=ja
The following is a sample response for a map image with label language (lang) of Japanese (ja).

lang=zh
The following is a sample response for a map image with label language (lang) of Chinese (Simplified) (zh).

markers=size:tiny
The following is a sample response for a map image with a default marker size (size) of tiny.

markers=size:small
The following is a sample response for a map image with a default marker size (size) of small.

markers=size:mid
The following is a sample response for a map image with a default marker size (size) of mid.

markers=size:mid&markers=size:small&markers=size:tiny
The following is a sample response for a map image that displays all default markers with (size) of mid, small, and tiny.

markers=color:red
The following is a sample response for a map image with a default marker color (color) of red (red).

markers=viewSizeRatio:0.5
The following is a sample response for a map image that changes the ratio of the default marker size (viewSizeRatio) to 0.5 times (0.5).

markers=viewSizeRatio:2.0
The following is a sample response for a map image that changes the ratio of the default marker size (viewSizeRatio) to 2 times (2.0).

markers=type:n|label:{number}
The following is a sample response for a map image that displays numeric markers.

markers=type:a|label:{alphabet}
The following is a sample response for a map image that displays alphabetical markers.

markers=type:t|label:{tooltip}
The following is a sample response for a map image that displays tooltip markers.

markers=type:e
The following is a sample response for a map image that displays custom markers.
