Static Map API

English

Static Map API

Article summary

Did you find this summary helpful?

Thank you for your feedback

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

Note

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.
- Application User Guide
- Subscribe to Maps

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&center=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 `EPSG:4326` (default) \| `NHN:2048` \| `NHN:128` \| `EPSG:4258` \| `EPSG:4162` \| `EPSG:2096` \| `EPSG:2097` \| `EPSG:2098` \| `EPSG:3857` \| `EPSG:900913` \| `EPSG:5179` `EPSG:4326`: WGS84 longitude and latitude `NHN:2048`: UTM-K `NHN:128`: KATECH(TM128) `EPSG:4258`: GRS80 longitude and latitude `EPSG:4162`: Bessel longitude and latitude `EPSG:2096`: Korea East Belt `EPSG:2097`: Korea Central Belt `EPSG:2098`: Korea West Belt `EPSG:3857`, `EPSG:900913`: Google Maps `EPSG:5179`: Korea 2000 / Unified CS
`center`	String	Conditional	Center coordinates (X coordinate,Y coordinate) X coordinate, Y coordinate order depends on coordinate system definition <e.g.> WGS84 longitude and latitude coordinate system: `center = longitude, latitude` Must be entered when not entering `markers` Must be entered when entering `level`
`level`	Integer	Conditional	Zoom level 0 - 20 Must be entered when not entering `markers` Must be entered when entering `level`
`w`, `h`	Integer	Required	Image width and height Support for 1 to 1,024 pixels in the `w=int&h=int` format `w`: width `h`: height
`maptype`	String	Optional	Map type `basic` (default) \| `traffic` \| `satellite` \| `satellite_base` \| `terrain` `basic`: general map `traffic`: traffic information map (based on general map) `satellite`: satellite map `satellite_base`: satellite background map `terrain`: terrain map
`format`	String	Optional	Map image format `jpg`/`jpeg` (default) \| `png8` \| `png` `jpg`/`jpeg`: 85% compression quality, 24-bit `png8`: 8-bit `png`: 24-bit
`scale`	Integer	Optional	Resolution `1` (default) \| `2` `1`: Request image for low resolution. Create and return an image of the requested size `w`, `h`, based on 256 x 256 tiles `2`: Request image for high resolution. Create and return an image of the requested size `w`, `h` based on 512 x 512 tiles (return the same map coverage as `scale=1`, but with twice as many pixels in each size)
`markers`	String	Conditional	Marker settings Must be entered when not entering `center`, `level` Display map with zoom level and position optimized for the set marker if `center`, `level` are not entered Up to 20 can be entered You can set options separated by "\| (pipe char)" See `markers` <e.g.> `markers=type:n\\|size:tiny\\|color:Blue\\|pos:126.9810479%2037.5695075&markers=type:d\\|size:mid\\|color:Default\\|pos:123.524712%2024.1236547`
`lang`	String	Optional	Label language `ko` (default) \| `en` \| `ja` \| `zh` `ko`: Korean `en`: English `ja`: Japanese `zh`: Chinese (Simplified)
`dataversion`	String	Optional	Version information Image caching in the Static Map API entered to resolve an issue where background tile updates from the origin server are not reflected when the client requests the same URL It is recommended to be entered when there are recency issues with background tiles Version information is updated periodically, so batch operations are recommended for efficiency It is recommended to set the number of daily checks according to the recommended update cycle (`interval`) to save the version information checked at a set time and use it when calling the Static Map API `version` can be checked through Data Version API

`markers`

The following describes markers.

Field	Value	Required	Description
`type`	String	Optional	Marker type `d` (default) \| `n` \| `a` \| `t` \| `e` `d`: default `n`: number `a`: alphabet `t`: tooltip `e`: custom
`size`	String	Optional	Marker size `tiny` \| `small` \| `mid` (default) If `tiny`, `label` is not displayed even if it is entered
`color`	String	Optional	Marker color Enter a predefined color value or 24-bit color value format `Default` (default) \| `Blue` \| `Orange` \| `Yellow` \| `Red` \| `Brown` \| `Green` \| `Purple` \| `Gray` `Default`: `0x08DA76` `Blue`: `0x029DFF` `Orange`: `0xFE8C52` `Yellow`: `0xFFBA01` `Red`: `0xFF6355` `Brown`: `0xA4885B` `Green`: `0x63AA41` `Purple`: `0xD182C8` `Gray`: `0x666666`
`label`	String	Optional	Marker label A - Z, 0 - 9 Display only markers when not entered If `type` is `tiny`, it is not displayed even if it is entered
`pos`	String	Required	Marker position (X, Y coordinates) Multiple coordinates can be entered, separated by "," <e.g.> `pos:126.9810479,2037.5695075,2C126.9950680,2037.5672557`
`viewSizeRatio`	Float	Optional	Marker size ratio Scale marker size based on default design by `type` and `size` 0.1 - 2.0 (default: 0.1) Enter up to one decimal place, `0.1` for less than 0.1, `2.0` for more than 2.0
`icon`	String	Conditional	Custom marker icon URL Must be entered if `type` is `e` PNG and SVG files supported <e.g.> `icon:http://aaa/bbb.svg`
`anchor`	String, Double	Optional	Marker display position Can be entered only if `type` is `e` It is the offset of the marker image position from the map image; set when you need to fine-tune the marker display position When entered as String type `top` \| `bottom` (default) \| `left` \| `right` \| `center` \| `topleft` \| `topright` \| `bottomleft` \| `bottomright` `top`: center top (0.5, 0.0) `bottom`: center bottom (0.5, 1.0) `left`: center left (0.0, 0.5) `right`: center right (1.0, 0.5) `center`: center (0.5, 0.5) `topleft`: top left (0.0, 0.0) `topright`: top right (0.0, 1.0) `bottomleft`: bottom left (1.0, 0.0) `bottomright`: bottom right (1.0, 1.0) When entered as Double type Can be entered up to two decimal places <e.g.> `anchor:0.75,0.5` or `anchor:top`

Note

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

Method	URL
GET	https://naveropenapi.apigw.ntruss.com/map-static/v2/lastversion

Response

Field	Type	Required	Description
`version`	String	-	Version information `major_version.minor_version` format `major_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)
`interval`	Long	-	Recommended update interval (second)

Request example

The following is a sample request.

Examples

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&center=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&center=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&center=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&center=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&center=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&center=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&center=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&center=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&center=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&center=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&center=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&center=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&center=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&center=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&center=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&center=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&center=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 Solution: Try again after a while, and contact Support if the issue persists
503	500	Service Unavailable	Temporary unavailable due to system maintenance Solution: Try again in after a while
504	510	Gateway Timeout	Temporarily unavailable due to system overload Solution: Try again in after a while