Login
      Contents x
      raster
        • Print
        • PDF
        Contents

        raster

          • Print
          • PDF
          Article Summary

          We are preparing a localization service for the content. We will do our best to provide the localization service as soon as possible.

          Overview

          Static Map is a service that helps you easily use NAVER Maps to display locations on your web page, without requiring JavaScript.

          To get the image you want within an HTML page, you should create a URL that fits the request format and place it in the <img> tag.

          Request

          ID-KEY based authentication

          curl "https://naveropenapi.apigw.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 issued when registering an application}" \
	-H "X-NCP-APIGW-API-KEY: {Client Secret issued when registering an application}" -v

          HTTP Referer based authentication

          <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={Client ID issued when registering an application}">

          Request Parameters

          ParameterTypeRequiredDescription
          crsstringNCoordinate system.
          It is WGS8 coordinate system (EPSG:4326) if not specified.

          Supported coordinate systems are as follows:
          - EPSG:4326: WGS84 longitude and latitude
          - NHN:2048: UTMK
          - 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 or EPSG:900913: Google Maps
          - EPSG:5179: Korea 2000 / Unified CS
          centerstringY or NCenter coordinates.
          Enter a value in the “center=x-coordinate,y-coordinate” format.
          The order of x and y coordinates is based on the coordinate system specified.
          For example, if you choose the WGS84 lng-lat coordinate system, you should specify coordinates in the order of <longitude,latitude>.
          This parameter can be omitted if you specify the markers parameter.
          levelintY or NZoom level.
          This parameter can be omitted if you specify the markers parameter.
          - Input range: 0-20
          w, hintYWidth and height of the image.
          Enter a value in the “w=width&h=height” format.
          At least 1-1024 pixels supported.
          maptypestringNMap type. Available values are as follows:
          - basic: Basic map image (default)
          - satellite: Satellite map image
          - terrain: Terrain map
          formatstringNFormat of the image to return. Available values are as follows:
          - png: 24 bit (default)
          - jpg or jpeg: Compression quality of 85%, 24 bit
          scaleintNOption for supporting high resolution displays. Available values are as follows:
          - 1: Low resolution (default)
          - 2: High resolution
          markersstringNSpecifies marker styles and locations.

          Request Header

          The header is required only for ID-KEY-based authentication.

          HeaderDescription
          X-NCP-APIGW-API-KEY-IDClient ID issued when registering an app
          X-NCP-APIGW-API-KEY-ID:{Client ID}
          X-NCP-APIGW-API-KEYClient Secret issued when registering an app
          X-NCP-APIGW-API-KEY:{Client Secret}

          Request Body

          • No request body required.

          Response

          Response Body

          It returns an image file (in png or jpeg) based on the parameters specified, if the request is successfully made.
          If an error occurs, an HTTP status code other than 200 is returned in JSON.

          Examples

          Request Example

          center

          Defines the coordinates of the center of the map.

          • Format: center=x-coordinate,y-coordinate

          The center coordinates are a comma-separated pair of x- and y-coordinates. The coordinates should be in the order of <longitude,latitude>.
          Note that you can omit the center and level parameters if you specify the markers parameter to display a map at the optimized zoom level and location.

          The following example requests an image of which the center coordinates are 127.1054221,37.3591614 based on the WGS86 coordinate system.

          https://naveropenapi.apigw.ntruss.com/map-static/v2/raster?w=300&h=300&center=127.1054221,37.3591614&level=16

          The center of the following image is the center coordinates.

          default-center.png

          level

          Sets the zoom level of the map.

          • Format: level=Zoom level

          The zoom level is at least 1 and up to 20.
          Note that you can omit the center and level parameters if you specify the markers parameter to display a map at the optimized zoom level and location.

          The following example requests a map at level 11.

          https://naveropenapi.apigw.ntruss.com/map-static/v2/raster?w=300&h=300&center=127.1054221,37.3591614&level=11

          A map at level 11 is displayed as follows.

          default-level.png

          w, h

          Sets the width and height of the map image. The width and height can be between 1 and 1024 pixels, respectively.

          • Format: w=Width&h=Height

          The following example requests a map 300 pixels wide and 200 pixels high.

          https://naveropenapi.apigw.ntruss.com/map-static/v2/raster?w=300&h=200&center=127.1054221,37.3591614&level=16

          A map in the requested size is displayed as follows.

          default-wh.png

          maptype

          Defines the map type.

          • Format: maptype=basic|satellite|terrain
            • basic: Basic map type.
            • satellite: Satellite map type.
            • terrain: Terrain map type.

          Basic

          The following example requests a basic map.

          https://naveropenapi.apigw.ntruss.com/map-static/v2/raster?w=300&h=300&center=127.1054221,37.3591614&level=11&maptype=basic

          A basic map is displayed as follows.

          default-maptype-basic.png

          Satellite

          The following example requests a satellite map.

          https://naveropenapi.apigw.ntruss.com/map-static/v2/raster?w=300&h=300&center=127.1054221,37.3591614&level=11&maptype=satellite

          A satellite map is displayed as follows.

          default-maptype-satellite.png

          Terrain

          The following example requests a terrain map.

          https://naveropenapi.apigw.ntruss.com/map-static/v2/raster?w=300&h=300&center=127.1054221,37.3591614&level=11&maptype=terrain

          A terrain map is displayed as follows.

          default-maptype-terrain.png

          format

          Sets the format of the map image.

          • Format: format=Image format (png or jpg or jpeg)

            The format of the image to return is png or jpeg (jpg).
          • png (default) is a 24-bit PNG format. If this parameter is not specified or it is set to an unsupported format, it is considered “png.”
          • jpeg (jpg) is a 24-bit JPEG format with the compression quality of 85%. (Both jpg and jpeg keywords are supported.)

          png

          The following example requests a map image in PNG.

          https://naveropenapi.apigw.ntruss.com/map-static/v2/raster?w=300&h=300&center=127.1054221,37.3591614&level=16&format=png

          A map in JPEG is displayed as follows.

          default-format-png.png

          jpeg (jpg)

          The following example requests a map image in JPEG (JPG).

          https://naveropenapi.apigw.ntruss.com/map-static/v2/raster?w=300&h=300&center=127.1054221,37.3591614&level=16&format=jpg

          A map in JPEG is displayed as follows.

          default-format-jpg.jpg

          scale

          Sets the option for supporting high resolution displays.

          • Format: scale=1|2
            • 1: Low resolution image. It returns a 256 x 256 tile based image created with the requested w and h (in pixels). It is the default value, and can be omitted.
            • 2: High resolution image. It returns a 512 x 512 tile based image created with the requested w and h. That is, it returns the same map coverage area as a request with scale=1, but with twice as many pixels in each dimension. For example, if a map with 320 x 320 is requested, a 640 x 640 image is returned.

          Low resolution

          The following example requests a low resolution map (scale=1).

          https://naveropenapi.apigw.ntruss.com/map-static/v2/raster?w=300&h=300&center=127.1054221,37.3591614&level=16&scale=1

          A low resolution map is displayed as follows.

          default-scale-1.png

          High resolution

          The following example requests a high resolution map (scale=2).

          https://naveropenapi.apigw.ntruss.com/map-static/v2/raster?w=300&h=300&center=127.1054221,37.3591614&level=16&scale=2

          A high resolution map is displayed as follows.

          default-scale-2.png

          markers

          Adds markers at specified locations on the map. It adds as many markers as the requested number, which can be up to 20.
          If you specify the markers parameter without specifying the center and level parameters, the API returns a map containing markers at the optimized zoom level and locations.

          • Format: markers=property:value|property:value1,value2|...
          PropertyValueRequiredDefaultDescriptionExample
          typed (default), n (number), a (alphabet)NdMarker typetype:d or type:n
          sizetiny, small, midNmidMarker size. If it is type, the label is omitted.size:tiny or size:small
          colorPre-defined color or 0xFFFFFF (24-bit color code)NNoneIt is 0x08da76 by default if not specified.
          Pre-defined colors are character strings defined for frequently used colors.
          Pre-defined colors are listed below:
          - Default: 0x08DA76
          - Blue: 0x029DFF
          - Orange: 0xFE8C52
          - Yellow: 0xFFBA01
          - Red: 0xFF6355
          - Brown: 0xA4885B
          - Green: 0x63AA41
          - Purple: 0xD182C8
          - Gray: 0x666666          		color:green or color:0x00FF00
          labelA-Z, 0-9NNoneDisplays only markers if not specified.label:A, label:9
          posx1 y1,x2 y2, ...YNoneLocation at which a marker is to be displayed. Multiple locations can be added.pos:127.15(empty space)38.15,126.12(empty space)37.523
          viewSizeRatio0.1~2.0N1.0Adjusts the marker size based on the default design for each marker type and size.
          - Only one decimal place allowed.
          - It is 0.1 if less than 0.1, and 2.0 if greater than 2.0.          		viewSizeRatio:2.0

          Default markers

          The following examples request various default markers (type:d) and show result images.

          • Request by size - size:tiny
          https://naveropenapi.apigw.ntruss.com/map-static/v2/raster?w=300&h=300&markers=type:d|size:tiny|pos:127.1054221%2037.3591614

          marker-1.png

          • Request by size - size:small
          https://naveropenapi.apigw.ntruss.com/map-static/v2/raster?w=300&h=300&markers=type:d|size:small|pos:127.1054221%2037.3591614

          marker-2.png

          • Request by size - size:mid
          https://naveropenapi.apigw.ntruss.com/map-static/v2/raster?w=300&h=300&markers=type:d|size:mid|pos:127.1054221%2037.3591614

          marker-3.png

          • Request multiple sized markers - size:mid + small + tiny
          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

          marker-4.png

          • Change color - red
          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
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

          marker-5.png

          • Change size - 0.5
          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

          marker-6.png

          • Change size - 2
          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

          marker-7.png

          Number markers

          • Combination of multiple number markers
          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

          marker-8.png

          Alphabet markers

          • Combination of multiple alphabet markers
          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

          marker-9.png

          Tooltip markers

          • Marker size is fixed to tiny
          • label contents will be presented as tooltip
          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

          marker-11.png

          Custom markers
          Defines custom markers (external markers).

          Customer markers have the following limitations.

          • The maximum size of a custom marker is 64 x 64 pixels for default displays, and 128 x 128 pixels for high resolution retina displays (scale=2).
          • If there is no response within 2 seconds from the request URL of a custom marker, creating a custom marker will stop.
          • Custom markers can remain with internal cache for up to 1 day. If only the marker image is changed with the same URL, the custom marker may not be updated for up to 1 day.
          • The svg and image formats are supported.
          PropertyValueRequiredDefaultDescriptionExample
          typee (external)YNoneCustom marker typetype:e
          iconURL pathYNoneURL path. png and svg formats are available.icon:http://aaa/bbb.svg or icon:http://aaa/bbb.png
          anchorLocation where the marker is displayedNbottom(0.5, 1.0)Offset value of the marker image location on the map. It is used to delicately adjust the location where the marker is displayed.
          It can be set to a double or text type.
          A double type can have a precision to two decimal places (0.00-1.00), and can be specified in the order of xOffset and yOffset. (Example: 0.0,0.0 for the top left, and 1.0,1.0 for the bottom right)
          A text type can be specified as follows.
          - top: 0.5, 0.0
          - bottom: 0.5, 1.0 (default)
          - 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
          For example, for a pin-shaped icon which is usually displayed based on the bottom center of the image, a double type value is “double:0.5,1.0” and a text type value is “text:bottom.”          		anchor:0.5,0.0 or anchor:top
          posx1 y1,x2 y2, ...YNoneLocation at which a marker is to be displayed. Multiple locations can be added.pos:127 38,126 37

          The following example requests a custom marker.

          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

          The following map is displayed as a result.

          marker-10.png

          Error Codes

          HTTP status codeError codeError messageDescription
          400100Bad requestThe request contains invalid parameters.
          500900Internal errorAn internal error has occurred.
          If the problem persists, contact us.
          503500Service UnavailableThe service is temporarily unavailable for system maintenance.
          Please try again later.
          504510Gateway TimeoutThe service is temporarily unavailable because of system overload.
          Please try again later.
          Was this article helpful?
          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