Application Service > Maps > API User Guide

Describes APIs that are required to use the Maps Service.

Common API Information

Prerequisites

• Appkey is required to use APIs.
• To check your appkey, go to URL & Appkey on top of the NHN Cloud Console.

Common Request Information

URL Information

Environment	Domain
Real	https://kr1-maps.api.nhncloudservice.com

Common Response Information

Search/Navigate API

• Respond with '200 OK' for all API requests. See header at the response body for more detail response results.

{
    "header": {
        "isSuccessful": true,
        "resultCode": 0,
        "resultMessage": ""
    }
}

Search

1. Search of Address (Search -> Coordinates)

• Search coordinates (TW/WGS84/TM Coordinates) with address.

Request

[URI]

Method	URI
GET	/maps/v1.0/appkeys/{appkey}/coordinates?query={query}&coordtype={coordtype}&startposition={startposition}&reqcount={reqcount}&admcode={admcode}

[Path parameter]

Name	Type	Required	Valid Range	Description
appkey	String	Required		Origin Appkey

[Query Parameters]

Name	Type	Required	Valid Range	Description
query	String	Required		Search words
coordtype	String	Optional		Type of Coordinates 0: TW 1: WGS84 2: TM
startposition	String	Optional		Start position of search 0: Initial location Query by 0, if left blank
reqcount	String	Optional		Number of search requests Return max count, if it is set with 0
admcode	String	Optional		Administrative code

Response

Body

{
  "header": {
    "isSuccessful": true,
    "resultCode": 0,
    "resultMessage": ""
  },
  "address": {
    "result": true,
    "totalcount": 2,
    "admtotalcount": 2,
    "admcount": 2,
    "res_type": "NNYN",
    "adm": [
      {
        "type": 2,
        "posx": "168425",
        "posy": "516725",
        "admcode": "4113510800",
        "jibun": "",
        "address": "Sampyeong-dong, Bundang-gu, Seongnam-si, Gyeonggi-do",
        "roadname": "",
        "roadjibun": "",
        "accuracy": 3
      },
      {
        "type": 2,
        "posx": "167300",
        "posy": "515526",
        "admcode": "4113511000",
        "jibun": "",
        "address": "Baekhyeon-dong (Pangyo-dong), Bundang-gu, Seongnam-si, Gyeonggi-do",
        "roadname": "",
        "roadjibun": "",
        "accuracy": 3
      }
    ]
  }
}

Field

Name	Type	Description
header	Object	Header area
header.isSuccessful	Boolean	Successful or not
header.resultCode	Integer	Failure code
header.resultMessage	String	Failure message
address	Object	Body area
address.result	Boolean	Successful or not
address.totalcount	Integer	Total number of search results
address.res_type	String	Name of search result type In the order of Name, Category, Address, and Phone Number (e.g.) NYNN: No for name, Yes for category, No for address, and No for phone number
address.adm	Array	Search result
address.adm[0].type	String	Search type 1: Search administrative system 2: Search land-lot number 3: Search new address system
address.adm[0].posx	String	X coordinates
address.adm[0].posy	String	Y coordinates
address.adm[0].admcode	String	Administrative code
address.adm[0].address	String	Address
address.adm[0].roadname	String	Road name for new address system
address.adm[0].roadjibun	String	Land-lot number for new address system
address.adm[0].accuracy	Integer	Accuracy of land-lot numbers 0: Search accuracy
1: Extend the last land-lot number digit
e.g.) For the search of 963-2, return the search result of 963-X.
2 : Extend the initial land-lot number digits
e.g) For the search of 963-2, return the search result of 96X
3: Coordinates of Dong by the administrative unit
e.g.) In case input is available only down to Sampyeong-dong
4: Coordinates of Dong or higher unit, or administrative Dong
e.g.) In case input is available down to Bundang-gu only

2. Search of Coordinates (Coordinates -> Address)

• Search address with coordinates (TW/WGS84).

Request

[URI]

Method	URI
GET	/maps/v1.0/appkeys/{appkey}/addresses?query={query}&posX={posX}&posY={posY}&coordtype={coordtype}

[Path parameter]

Name	Type	Required	Valid Range	Description
appkey	String	Required		Origin appkey

[Query Parameters]

Name	Type	Required	Valid Range	Description
posX	String	Required		X coordinates
posY	String	Required		Y coordinates
coordtype	String	Optional		Requested coordinate type 0: TW coordinates 1: WGS84 coordinates Search by TW coordinates, if left blank.

Response

Body

{
  "header": {
    "isSuccessful": true,
    "resultCode": 0,
    "resultMessage": ""
  },
  "location": {
    "result": true,
    "adm": {
      "posx": "168434",
      "posy": "516700",
      "admcode": "4113511000",
      "address": "Baekhyeon-dong, Bundang-gu, Seongnam-si, Gyeonggi-do",
      "jibun": "519-7",
      "roadname": "",
      "roadjibun": "",
      "distance": 25
    }
  }
}

Field

Name	Type	Description
header	Object	Header area
header.isSuccessful	Boolean	Successful or not
header.resultCode	Integer	Failure code
header.resultMessage	String	Failure message
location	Object	Body area
location.result	Boolean	Successful or not
location.adm	Object	Search result
location.adm.posx	String	X coordinates
location.adm.posy	String	Y coordinates
location.adm.admcode	String	Administrative code
location.adm.address	String	Address
location.adm.jibun	String	Land lot address
location.adm.roadname	String	Road name for new address system
location.adm.roadjibun	String	Land-lot number for new address system
location.adm.distance	Integer	Distance from coordinates (if available)
location.adm.accuracy	String	Accuracy of land-lot numbers 0: Search accuracy
1: Extend the last digit of land-lot numbers
e.g.) For the search of 963-2, return the search result of 963-X.
2 : Extend the initial digit of land-lot numbers
e.g) For the search of 963-2, return the search result of 96X
3: Coordinates of Dong by the administrative unit
e.g.) In case input is available only down to Sampyeong-dong
4: Coordinates of Dong or higher unit, or administrative Dong
e.g.) In case input is available down to Bundang-gu only

3. Integrated Search

• Search integrated information, including phone number, address, and POI data.

Request

[URI]

Method	URI
GET	/maps/v1.0/appkeys/{appkey}/searches&query={query}&coordtype&startposition={startposition}&reqcount={reqcount}&spopt={spopt}&radius={radius}&admcode={admcode}&depth={depth}&x1={x1}&y1={y1}&x2={x2}&y2={y2}&sortopt={sortopt}&catecode={catecode}

[Path parameter]

Name	Type	Required	Valid Range	Description
appkey	String	Required		Origin appkey

[Query Parameters]

Name	Type	Required	Valid Range	Description
query	String	Required		Search words
coordtype	String	Optional		Type of coordinates 0: TW coordinates
1: WGS84 coordinates
2: TM coordinates
startposition	String	Optional		Start position of search 0: Initial location; query by 0, if left blank
reqcount	String	Optional		Number of search requests Return max count, if it is set with 0
spopt	String	Optional		Optional space search 0: Disabled
1: Search of extent
2: Search of range
*Without spopt value setting, set 0.
radius	String	Optional		Radius Enabled when the spopt value is 2
Set by meter
admcode	String	Optional		Administrative code
depth	String	Optional		Requirements for sub-facilities 1: Request by depth 1 only (the highest depth)
2: Request by depth 2
3: Request by depth 3
* Set 1, if depth value is not configured
* With depth configuration, subpoi detail information is returned for the depth, like Response as below
x1	String	Optional		X1 coordinates X coordinate of the control point, if spopt is 0
X coordinate on top left of Extent, if spopt is 1
X coordinate of the control point, if spopt is 2
y1	String	Optional		Y1 coordinates Y coordinate of the control point, if spopt is 0
Y coordinate on top left of Extent, if spopt is 1
Y coordinate of the control point, if spopt is 2
x2	String	Optional		X2 coordinates X coordinate on bottom right of Extent, if spopt is 1; disabled if spopt is 2
y2	String	Optional		Y2 coordinates Y coordinate on bottom right of Extent, if spopt is 1; disabled if spopt is 2
sortopt	String	Optional		Sorting option 1: Sort by name
2: Sort by distance (with coordinates)
3: Match names ->Sort by distance (with coordinates)
4: Sort by weight of a search word (for engine)
5: Sort by weight + length of a search word (for engine)
6: Sort by preferred category [V8.1.5 is not supported]
7: Sort by most-updated data
8: Sort by weight in the order of (Landmark>Distance>PoiWeight) + distance (if coordinates are available) of a search word
*Set 4, if sortopt is not set
catecode	String	Optional		Preferred Category If a category name is entered for a search word, for the search of a preferred category, search is made for the search word rather than the preferred category, according to search word-first policy
e.g.) Search Word: "Beauty salon", Preferred Category: "100000"(restaurant) ->Search is made for a beauty salon

Response

Body

{
    "header": {
        "isSuccessful": true,
        "resultCode": 0,
        "resultMessage": ""
    },
    "search": {
        "result": true,
        "type": 0,
        "totalcount": 1,
        "count": 1,
        "poitotalcount": 1,
        "poicount": 1,
        "ucp_poitotalcount": 0,
        "ucp_poicount": 0,
        "tel_poitotalcount": 0,
        "tel_poicount": 0,
        "admtotalcount": 0,
        "admcount": 0,
        "reftotalcount": 0,
        "refcount": 0,
        "res_type": "YYYY",
        "poi": [
            {
                "poiid": 4722977,
                "depth": 0,
                "dpx": "169031",
                "dpy": "517906",
                "rpx": "169039",
                "rpy": "517941",
                "name1":"Samhwan HIPEX",
                "name2": "HIPIEX",
                "name3": "Samhwan HIPEX",
                "name4": "HIPEX",
                "admcode": "4113510900",
                "jibun": "678",
                "address": "Sampyeong-dong, Bundang-gu, Seongnam-si, Gyeonggi-do",
                "roadname": "Pangyoyeok-ro, Bundang-gu, Seongnam-si, Gyeonggi-do",
                "roadjibun": "240",
                "detailaddress": "",
                "catecode": "130301",
                "catename": "Company",
                "dp_catecode": "150",
                "userid": "",
                "imagecount": 0,
                "userimagecount": 0,
                "badgeflag": false,
                "distance": 0,
                "tel": "",
                "islandmark": false,
                "updateTS": "2017-10-12 00:00:00",
                "data_source": "Thinkware",
                "hasoildata": false,
                "hasdetailinfo": false,
                "hassubpoi": true,
                "subpoi": {
                    "count": 5,
                    "poi": [
                        {
                            "poiid": 4828295,
                            "depth": 1,
                            "dpx": "169031",
                            "dpy": "517910",
                            "rpx": "169039",
                            "rpy": "517941",
                            "name1": "Builiding A",
                            "name2": "Sanhwan HIPEX Building A",
                            "name3": "",
                            "name4": "",
                            "admcode": "4113510900",
                            "jibun": "678",
                            "address": "Sampyeong-dong, Bundang-gu, Seongnam-si, Gyeonggi-do",
                            "roadname": "Pangyoyeok-ro, Bundang-gu, Seongnam-si, Gyeonggi-do",
                            "roadjibun": "240",
                            "detailaddress": "",
                            "catecode": "130301",
                            "catename": "기업",
                            "dp_catecode": "150",
                            "userid": "",
                            "imagecount": 0,
                            "userimagecount": 0,
                            "badgeflag": false,
                            "distance": 0,
                            "tel": "",
                            "islandmark": false,
                            "updateTS": "2017-10-13 00:00:00",
                            "hasoildata": false,
                            "hasdetailinfo": false,
                            "hassubpoi": true,
                            "subpoi": {
                                "count": 36,
                                "poi": [
                                    {
                                        "poiid": 4722978,
                                        "depth": 2,
                                        "dpx": "169039",
                                        "dpy": "517941",
                                        "rpx": "169039",
                                        "rpy": "517941",
                                        "name1": "entrance",
                                        "name2": "",
                                        "name3": "",
                                        "name4": "",
                                        "admcode": "4113510900",
                                        "jibun": "678",
                                        "address": "Sampyeong-dong, Bundang-gu, Seongnam-si, Gyeonggi-do",
                                        "roadname": "",
                                        "roadjibun": "",
                                        "detailaddress": "",
                                        "catecode": "181100",
                                        "catename": "road facilities",
                                        "dp_catecode": "000",
                                        "userid": "",
                                        "imagecount": 0,
                                        "userimagecount": 0,
                                        "badgeflag": false,
                                        "distance": 0,
                                        "tel": "",
                                        "islandmark": false,
                                        "updateTS": "2017-10-13 00:00:00",
                                        "hasoildata": false,
                                        "hasdetailinfo": false,
                                        "hassubpoi": false
                                    },
        ....
        ]
    }
}

Field

Name	Type	Description
header	Object	Header area
header.isSuccessful	Boolean	Successful or not
header.resultCode	Integer	Failure code
header.resultMessage	String	Failure message
search	Object	Body area
search.result	Boolean	Successful or not
search.type	Integer	0: General search 1: Reference search
search.totalcount	Integer	Total number of search results
search.count	Integer	Number of search results
search.poitotalcount	Integer	Total number of search results (Thinkware POI)
search.poicount	Integer	Number of search results (Thinkware POI)
search.tel_poitotalcount	Integer	Total number of search results (Tel POI)
search.tel_poicount	Integer	Number of search results (Tel POI)
search.ucp_poitotalcount	Integer	Total number of search results (User POI)
search.ucp_poicount	Integer	Number of search results (User POI)
search.admtotalcount	Integer	Total number of adm search results
search.admcount	Integer	Number of adm search results
search.reftotalcount	Integer	Total number of ref search results
search.refcount	Integer	Number of ref search results
search.recommendedQuery	String	Provides typo correction result if search result is unavailable (NULL is available)
search.recommendedCost	Integer	Typo correction result Cost (0~10000)
search.res_type	String	Type name from search result In the order of name, category, address, and phone number (e.g.) NYNN: NO for name, YES for category, NO for address, and NO for phone number
search.poi	Array	List of POI search results
search.poi[0].poiid	Integer	POI ID
search.poi[0].depth	String	POI depth
search.poi[0].dpx	String	X coordinates for display (longitude for WGS84)
search.poi[0].dpy	String	Y coordinates for display (latitude for WGS84)
search.poi[0].rpx	String	X coordinates for navigation (longitude for WGS84)
search.poi[0].rpy	String	Y coordinates for navigation (latitude for WGS84)
search.poi[0].name1	String	Official name
search.poi[0].name2	String	Short name
search.poi[0].name3	String	Expanded name 1
search.poi[0].name4	String	Expanded name 2
search.poi[0].admcode	String	Administrative code
search.poi[0].address	String	Address
search.poi[0].jibun	String	Land-lot number
search.poi[0].roadname	String	Road name for new address system
search.poi[0].roadjibun	String	Land lot number for new address system
search.poi[0].detailaddress	String	Address details
search.poi[0].catecode	String	Classification code
search.poi[0].catename	String	Classification name
search.poi[0].dp_catecode	String	DP classification code
search.poi[0].distance	Integer	Distance from coordinates (if available)
search.poi[0].tel	String	Phone number
search.poi[0].hasoildata	Boolean	Availability of oil price data
search.poi[0].hasdetailinfo	Boolean	Availability of detail information
search.poi[0].hassubpoi	Boolean	Availability of sub-facility
search.poi[0].adv_count	Integer	Number of ad codes
search.poi[0].islandmark	Boolean	Landmark or not
search.poi[0].updateTS	String	Format of last updated date (Y4-MM-DD HH:mm:ss)
search.poi[0].data_source	String	Category of POI creation data (Thinkware/Tel/User)
search.poi[0].badgeflag	Boolean	Availability of badge (Not Yet : FALSE, Badged : TRUE)
search.poi[0].userid	String	User ID registering POI (only for UCP)
search.poi[0].imagecount	Integer	Number of POI images
search.poi[0].oildata	Object	Oil price data
search.poi[0].oildata.g_price	Integer	Gas price
search.poi[0].oildata.hg_price	Integer	Premium gas price
search.poi[0].oildata.d_price	Integer	Light oil price
search.poi[0].oildata.l_price	Integer	LPG price
search.poi[0].oildata.updatetime	String	Updated time
search.poi[0].oildata.priceinfo	String	Highest/Lowest oil price data (H: Highest, L: Lowest, X: N/A) in the order of gas, premium gas, light oil, and LPG
search.poi[0].oildata.wash	Boolean	Availability of car wash
search.poi[0].oildata.fix	Boolean	Availability of car repairs
search.poi[0].oildata.mart	Boolean	Availability of a store
search.poi[0].AdInfo	Array	Ad code of the ad provider
search.poi[0].AdInfo.ADCODE	Integer	Ad codes Assignable from 1 to 99 (up to 99)
search.poi[0].subpoi	Object	Sub-facility information
search.poi[0].subpoi.count	Integer	Number of sub-facilities
search.poi[0].subpoi.poi	Array	Same as POI information
search.tel	Array	List of TEL search results (same as POI information)
search.ucp	Array	List of UCP search results (same as POI information)
search.adm	Array	List of DM search results
search.adm[0].type	String	Type of search 1: Search administrative system 2: Search land-lot number 3: Search new address system
search.adm[0].posx	String	X coordinates (longitude for WGS84)
search.adm[0].posy	String	Y coordinates (latitude for WGS84)
search.adm[0].admcode	String	Administrative code
search.adm[0].address	String	Address
search.adm[0].jibun	String	Land-lot number
search.adm[0].roadname	String	Road name for new address system
search.adm[0].roadjibun	String	Land-lot number for new address system
search.adm[0].accuracy	Integer	Accuracy of land-lot numbers 0: Search accuracy
1: Extend the last digit of land-lot numbers
2: Extend the initial digit of land-lot numbers
search.hasgasstation	Boolean	Availability of oil price data
search.oilprice	Object	Oil price data
search.oilprice.max_g_price	Integer	Highest gas price
search.oilprice.min_g_price	Integer	Lowest gas price
search.oilprice.avg_g_price	Integer	Average gas price
search.oilprice.max_hg_price	Integer	Highest premium gas price
search.oilprice.min_hg_price	Integer	Lowest premium gas price
search.oilprice.avg_hg_price	Integer	Average premium gas price
search.oilprice.max_d_price	Integer	Highest light oil price
search.oilprice.min_d_price	Integer	Lowest light oil price
search.oilprice.avg_d_price	Integer	Average light oil price
search.oilprice.max_l_price	Integer	Highest LPG price
search.oilprice.min_l_price	Integer	Lowest LPG price
search.oilprice.avg_l_price	Integer	Average LPG price

4. Search of Recommended Words

• Search recommended search words.

Request

[URI]

Method	URI
GET	/maps/v1.0/appkeys/{appkey}/proposers?query={query}

[Path parameter]

Name	Type	Required	Valid Range	Description
appkey	String	Required		Origin appkey

[Query Parameters]

Name	Type	Required	Valid Range	Description
query	String	Required	50 bytes	50 bytes of Korean/English/Numbers (25 Korean letters)

Response

Body

{
  "header": {
    "isSuccessful": true,
    "resultCode": 0,
    "resultMessage": ""
  },
  "proposer": {
    "result": true,
    "count": 10,
    "keyword": [
      {
        "keyword": "Pangyo Station",
        "frequency": 3729938
      },
      {
        "keyword": "Pangyo",
        "frequency": 3729326
      },
      {
        "keyword": "Pangyo IC",
        "frequency": 3729362
      },
      {
        "keyword": "Pangyo Library",
        "frequency": 3729514
      },
      {
        "keyword": "Pangyo One Village",
        "frequency": 3730051
      },
      {
        "keyword": "Pangyo Lottemart",
        "frequency": 3729602
      },
      {
        "keyword": "Pangyo Innovalley",
        "frequency": 3730186
      },
      {
        "keyword": "Pangyo Museum",
        "frequency": 3729654
      },
      {
        "keyword": "Pangyo Middle School",
        "frequency": 3730256
      },
      {
        "keyword": "Court by Marriott Seoul Pangyo",
        "frequency": 3729626
      }
    ]
  }
}

Field

Name	Type	Description
header	Object	Header area
header.isSuccessful	Boolean	Successful or not
header.resultCode	Integer	Failure code
header.resultMessage	String	Failure message
proposer	Object	Body area
proposer.result	Boolean	Successful or not
proposer.count	Integer	Number of recommended search words
proposer.keyword	Array	List of recommended search words
proposer.keyword[0].keyword	String	Recommended search words
proposer.keyword[0].frequency	Integer	Query frequency

5. Search of POI Details

• Search details of POI.

Request

[URI]

Method	URI
GET	/maps/v1.0/appkeys/{appkey}/pois?poiid={poiid}

[Path parameter]

Name	Type	Required	Valid Range	Description
appkey	String	Required		Origin appkey

[Query Parameters]

Name	Type	Required	Valid Range	Description
poiid	String	Required	186	POI ID Enter poiid with the delimiter, "," (multiple input is available, up to 186) e.g.) poiid=123,234,567

Response

Body

{
  "header": {
    "isSuccessful": true,
    "resultCode": 0,
    "resultMessage": ""
  },
  "poi": {
    "result": true,
    "totalcount": 2,
    "count": 2,
    "poiinfo": [
      {
        "poiid": 510835,
        "dpx": "164939",
        "dpy": "530708",
        "rpx": "164929",
        "rpy": "530731",
        "name1": "Hyundai Department Store(the Trade Center Store)",
        "name2": "Hyundai Department Store Trade Center",
        "name3": "Trade Center Hyundai Department Store",
        "name4": "",
        "admcode": "1168010500",
        "jibun": "159-7",
        "address": "Samseong-dong, Gangnam-gu, Seoul",
        "roadname": "Teheran-ro, Samseong 1-dong, Gangnam-gu, Seoul",
        "roadjibun": "517",
        "detailaddress": "",
        "fulladdress": "159-7 Samseong-dong, Gangnam-gu, Seoul",
        "zip": "",
        "homepage": "http://www.e-hyundai.com",
        "email": "",
        "howtogo": "",
        "tel1": "025522233",
        "tel2": "",
        "fax1": "",
        "fax2": "",
        "catecode": "110102",
        "catename": "shopping",
        "dp_catecode": "250",
        "icode": "493-070-3606",
        "externallink": [],
        "detail_count": 10,
        "etc_count": 2,
        "imagecount": 0,
        "badgeflag": false,
        "detailinfo": [
          {
            "name": "Closed Day",
            "value": "Store closed twice a month"
          },
          {
            "name": "Business Hours",
            "value": "10:30~20:00"
          },
          {
            "name": "Parking lot",
            "value": "Holds around 1400 vehicles"
          },
          {
            "name": "Parking fee",
            "value": "1-hour free ticket for a purchase worth of 10 thousand won or more"
          },
          {
            "name": "Sub-facilities 1",
            "value": "Emerald Hall(Event Hall)"
          },
          {
            "name": "Sub-facilities 2",
            "value": "Terrace garden"
          },
          {
            "name": "Size",
            "value": "10-storey building with 4 underground floors"
          },
          {
            "name": ""Floor Guide 1",
            "value": "1F Luxury Boutique/2F Fashion Accessories"
          },
          {
            "name": "Floor Guide 2",
            "value": "3F~4F Women's Fashion/6F Golf Fashion/Unisex Casual"
          },
          {
            "name": "Floor Guide 3",
            "value": "9F Restaurants/10F Cultural Space"
          }
        ],
        "etcinfo": [
          {
            "name": "Others 1",
            "value": "Located at the heart of the finanial hub of Teheran-ro"
          },
          {
            "name": "Others 2",
            "value": "The show window for the Korean commerce, satisfying global clients"
          }
        ],
        "hasoildata": false
      },
      ....
    ]
  }
}

Field

Name	Type	Description
header	Object	Header area
header.isSuccessful	Boolean	Successful
header.resultCode	Integer	Failure code
header.resultMessage	String	Failure message
poi	Object	Body area
poi.result	Boolean	Successful or not
poi.totalcount	Integer	Total number of search results
poi.count	Integer	Number of search results
poi.poiinfo	Array	List of POI search results
poi.poiinfo[0].poiid	Integer	POI ID
poi.poiinfo[0].dpx	String	X coordinates for display (longitude for WGS84)
poi.poiinfo[0].dpy	String	Y coordinates for display (latitude for WGS84)
poi.poiinfo[0].rpx	String	X coordinates for navigation (longitude for WGS84)
poi.poiinfo[0].rpy	String	Y coordinates for navigation (latitude for WGS84)
poi.poiinfo[0].name1	String	Official name
poi.poiinfo[0].name2	String	Short name
poi.poiinfo[0].name3	String	Expanded name 1
poi.poiinfo[0].name4	String	Expanded name 2
poi.poiinfo[0].admcode	String	Administrative code
poi.poiinfo[0].jibun	String	Land-lot number
poi.poiinfo[0].address	String	Address
poi.poiinfo[0].roadname	String	Road name for new address system
poi.poiinfo[0].roadjibun	String	Land lot number for new address system
poi.poiinfo[0].detailaddress	String	Address details
poi.poiinfo[0].catecode	String	Classification code
poi.poiinfo[0].catename	String	Classification name
poi.poiinfo[0].fulladdress	String	Entire address (Administrative address+land-lot number+details)
poi.poiinfo[0].zip	String	Zip code
poi.poiinfo[0].homeage	String	URL for website
poi.poiinfo[0].email	String	Email
poi.poiinfo[0].howtogo	String	How to access
poi.poiinfo[0].tel1	String	Phone number 1
poi.poiinfo[0].tel2	String	Phone number 2
poi.poiinfo[0].fax1	String	Fax number 1
poi.poiinfo[0].fax2	String	Fax number 2
poi.poiinfo[0].icode	String	ICODE
poi.poiinfo[0].detail_count	Integer	Number of detail classification items
poi.poiinfo[0].etc_count	Integer	Number of other classification items
poi.poiinfo[0].badgeflag	Boolean	Availability of badge (Not Yet:FALSE, Badged:TRUE)
poi.poiinfo[0].imagecount	Integer	Number of POI images
poi.poiinfo[0].hasoildata	Boolean	Availability of oil price data
poi.poiinfo[0].detailinfo	Array	Detail classification item
poi.poiinfo[0].detailinfo[0].name	String	Description of detail classification item
poi.poiinfo[0].detailinfo[0].value	String	Content of detail classification item
poi.poiinfo[0].etcinfo	Array	Other classification item
poi.poiinfo[0].etcinfo[0].name	String	Description of other classification item
poi.poiinfo[0].etcinfo[0].value	String	Content of other classification item
poi.poiinfo[0].oildata	Object	Oil price data
poi.poiinfo[0].oilda.tag_price	Integer	Gas price
poi.poiinfo[0].oilda.hg_price	Integer	Premium gas price
poi.poiinfo[0].oilda.d_price	Integer	Light oil price
poi.poiinfo[0].oilda.l_price	Integer	LPG price
poi.poiinfo[0].oilda.updatetime	String	Updated time
poi.poiinfo[0].oilda.priceinfo	String	Highest/Lowest oil price data (H: Highest, L: Lowest, X: N/A) In the order of gas, premium gas, light oil, and LPG
poi.poiinfo[0].oilda.wash	Boolean	Availability of car wash
poi.poiinfo[0].oilda.fix	Boolean	Availability of car repairs
poi.poiinfo[0].oilda.mart	Boolean	Availability of a store

6. Search of POI Sub-Facilities

• Search sub-facilities for a specific POI.

Request

[URI]

Method	URI
GET	/maps/v1.0/appkeys/{appkey}/sub-pois?poiid={poiid}&x1={x1}&y1={y1}

[Path parameter]

Name	Type	Required	Valid Range	Description
appkey	String	Required		Origin appkey

[Query Parameters]

Name	Type	Required	Valid Range	Description
poiid	String	Required		POI ID Multiple number is not supported
x1	String	Optional	Current location or map center coordinates If both X and Y coordinates are NULL or 0, distance is not calculated.
y1	String	Optional	Current location or map center coordinates If both X and Y coordinates are NULL or 0, distance is not calculated.

Response

Body

{
  "header": {
    "isSuccessful": true,
    "resultCode": 0,
    "resultMessage": ""
  },
  "subpoi": {
    "result": true,
    "totalcount": 5,
    "count": 5,
    "poi": [
      {
        "poiid": 4521976,
        "depth": 1,
        "dpx": "169172",
        "dpy": "517030",
        "rpx": "169172",
        "rpy": "517030",
        "name1": "Transfer parking lot",
        "name2": "",
        "name3": "",
        "name4": "",
        "admcode": "4113511000",
        "jibun": "",
        "address": "Baekhyeon-dong, Bundang-gu,Seongnam, Gyeonggi Province",
        "roadname": "",
        "roadjibun": "",
        "detailaddress": "",
        "catecode": "161701",
        "catename": "Parking lot",
        "dp_catecode": "360",
        "userid": "",
        "imagecount": 0,
        "userimagecount": 0,
        "badgeflag": false,
        "distance": 0,
        "tel": "",
        "islandmark": false,
        "updateTS": "1970-01-01 09:00:00",
        "hasoildata": false,
        "hasdetailinfo": false,
        "hassubpoi": false
      },
      {
        "poiid": 4521977,
        "depth": 1,
        "dpx": "169088",
        "dpy": "517090",
        "rpx": "169088",
        "rpy": "517090",
        "name1": "Exit no.1",
        "name2": "",
        "name3": "",
        "name4": "",
        "admcode": "4113511000",
        "jibun": "",
        "address": "Baekhyeon-dong, Bundang-gu,Seongnam, Gyeonggi Province",
        "roadname": "",
        "roadjibun": "",
        "detailaddress": "",
        "catecode": "173000",
        "catename": "Subway",
        "dp_catecode": "370",
        "userid": "",
        "imagecount": 0,
        "userimagecount": 0,
        "badgeflag": false,
        "distance": 0,
        "tel": "",
        "islandmark": false,
        "updateTS": "1970-01-01 09:00:00",
        "hasoildata": false,
        "hasdetailinfo": false,
        "hassubpoi": false
      },
      ...
    ]
  }
}

Field

Name	Type	Description
header	Object	Header area
header.isSuccessful	Boolean	Successful or not
header.resultCode	Integer	Failure code
header.resultMessage	String	Failure message
subpoi	Object	Body area
subpoi.result	Boolean	Successful or not
subpoi.totalcount	String	Total number of search results
subpoi.count	String	Number of search results
subpoi.poi	Array	List of POI search results
subpoi.poi[0].poiid	Integer	POI ID
subpoi.poi[0].depth	String	POI depth
subpoi.poi[0].dpx	String	X coordinates for display (longitude for WGS84)
subpoi.poi[0].dpy	String	Y coordinates for display (latitude for WGS84)
subpoi.poi[0].rpx	String	X coordinates for navigation (longitude for WGS84)
subpoi.poi[0].rpy	String	Y coordinates for navigation (latitude for WGS84)
subpoi.poi[0].name1	String	Official name
subpoi.poi[0].name2	String	Short name
subpoi.poi[0].name3	String	Expanded name1
subpoi.poi[0].name4	String	Expanded name2
subpoi.poi[0].admcode	String	Administrative code
subpoi.poi[0].address	String	Address
subpoi.poi[0].jibun	String	Land-lot number
subpoi.poi[0].roadname	String	Road name for new address system
subpoi.poi[0].roadjibun	String	Land-lot number for new address system
subpoi.poi[0].detailaddress	String	Address details
subpoi.poi[0].catecode	String	Classification code
subpoi.poi[0].catename	String	Classification name
subpoi.poi[0].dp_catecode	String	DP classification code
subpoi.poi[0].distance	Integer	Distance from coordinates (if available)
subpoi.poi[0].tel	String	Phone number
subpoi.poi[0].hasoildata	Boolean	Availability of oil price data
subpoi.poi[0].hasdetailinfo	Boolean	Availability of detail information
subpoi.poi[0].hassubpoi	Boolean	Availability of sub-facilities
subpoi.poi[0].adv_count	Boolean	Number of ad codes
subpoi.poi[0].islandmark	Boolean	Landmark or not
subpoi.poi[0].updateTS	String	Format of last updated date and time (Y4-MM-DD HH:mm:ss)
subpoi.poi[0].data_source	String	Category of POI creation data (Thinkware/Tel/User)
subpoi.poi[0].badgeflag	Boolean	Availability of badge (Not Yet: FALSE, Badged: TRUE)
subpoi.poi[0].userid	String	User ID for POI registration (only for UCP)
subpoi.poi[0].imagecount	Integer	Number of POI images
subpoi.poi[0].oildata	Object	Oil price data
subpoi.poi[0].oildata.g_price	Integer	Gas price
subpoi.poi[0].oildata.hg_price	Integer	Premium gas price
subpoi.poi[0].oildata.d_price	Integer	Light oil price
subpoi.poi[0].oildata.l_price	Integer	LPG price
subpoi.poi[0].oildata.updatetime	String	Updated time
subpoi.poi[0].oildata.priceinfo	String	Highest/Lowest oil price data (H: Highest, L: Lowest, X: N/A) In the order of gas, premium gas, light oil, and LPG
subpoi.poi[0].oildata.wash	Boolean	Availability of car wash
subpoi.poi[0].oildata.fix	Boolean	Availability of car repairs
subpoi.poi[0].oildata.mart	Boolean	Availability of a store
subpoi.poi[0].AdInfo	Array	List of ad codes
subpoi.poi[0].AdInfo[0].ADCODE	Integer	Ad codes Assignable from 1 to 99 (up to 99)
subpoi.poi[0].subpoi	Object	Sub-facility data
subpoi.poi[0].subpoi.count	Integer	Number of subpois
subpoi.poi[0].subpoi.poi	Array	Same as POI information

7. Conversion of Coordinates

• Return conversion value between WGS84 <-> TM coordinates.

Request

[URI]

Method	URI
GET	/maps/v1.0/appkeys/{appkey}/trans-coordinates?coordtype={coordtype}&x={x}&y={y}

[Path parameter]

Name	Type	Required	Valid Range	Description
appkey	String	Required		Origin appkey

[Query Parameters]

Name	Type	Required	Valid Range	Description
coordtype	String	Required		0 : WGS84 -> TM 1 : TM -> WGS84
x	double	Required	Current location or map center coordinates WGS84 or TM coordinates
y	double	Required	Current location or map center coordinates WGS84 or TM coordinates

Response

Body

{
  "header": {
    "isSuccessful": true,
    "resultCode": 0,
    "resultMessage": ""
  },
  "coordinate": {
    "coordtype": "WGS84",
    "x": "128.662952",
    "y": "38.058678"
  }
}

Field

Name	Type	Description
header	Object	Header area
header.isSuccessful	Boolean	Successful or not
header.resultCode	Integer	Failure code
header.resultMessage	String	Failure message
coordinate	Object	Body area
coordinate.coordtype	String	Conversion type of coordinates
coordinate.x	String	X coordinates for conversion
coordinate.y	String	Y coordinates for conversion

Navigate

1. Summary of Route Navigation

• Search summary information on route navigation results for coordinates.

Request

[URI]

Method	URI
GET	/maps/v1.0/appkeys/{appkey}/routes?startX={startX}&startY={startY}&endX={endX}&endY={endY}&viaCount={viaCount}&via1X={via1X}&via1Y={via1Y}&via2X={via2X}&via2Y={via2Y}&option={option}

[Path parameter]

Name	Type	Required	Valid Range	Description
appkey	String	Required		Origin appkey

[Query Parameters]

Name	Type	Required	Valid Range	Description
startX	String	Required		X coordinates at departure
startY	String	Required		Y coordinates at departure
endX	String	Required		X coordinates at destination
endY	String	Required		Y coordinates at destination
viaCount	String	Optional		Number of stopovers
via1X	String	Optional		X coordinates at stopover 1
via1Y	String	Optional		Y coordinates at stopover 1
via2X	String	Optional		X coordinates at stopover 2
via2Y	String	Optional		Y coordinates at stopover 2
option	String	Required		Optional route navigation Request by the navigation option, "," br>ex) option=real_traffic\,real_traffic2 freeroad_priority: Free highway_priority: Highway real_traffic: Real-time real_traffic_freeroad: Real-time (free) real_traffic: Recommendation 1 real_traffic2: Recommendation 2 rt_stats: Real-time statistics rt_stats_freeroad: Real-time statistics (free) short_distance_priority: Short distance stats: Statistics stats_freeroad: Statistics (free) motorcycle: Two-wheeler

Response

Body

{
  "header": {
    "isSuccessful": true,
    "resultCode": 0,
    "resultMessage": ""
  },
  "route": {
    "SummaryResult": [
      [
        "freeroad_priority",
        68418,
        122
      ],
      [
        "highway_priority",
        77303,
        89
      ],
      [
        "real_traffic",
        63641,
        94
      ],
      [
        "real_traffic_freeroad",
        64469,
        119
      ],
      [
        "recoomendation1",
        4294967295,
        0
      ],
      ...
    ]
  }
}

Field

Name	Type	Description
header	Object	Header area
header.isSuccessful	Boolean	Successful or not
header.resultCode	Integer	Failure code
header.resultMessage	String	Failure message
route	Object	Body area
route.SummaryResult	Array	List of route request result
route.SummaryResult[0].0	String	Name of option
route.SummaryResult[0].1	Integer	Distance of route navigation (unit: m)
route.SummaryResult[0].2	Integer	Time of route navigation (unit: minute)

2. Route Navigation Details

• Search detail information of route navigation results on coordinates.

Request

[URI]

Method	URI
GET	/maps/v1.0/appkeys/{appkey}/route-details?startX={startX}&startY={startY}&endX={endX}&endY={endY}&viaCount={viaCount}&via1X={via1X}&via1Y={via1Y}&via2X={via2X}&via2Y={via2Y}&option={option}

[Path parameter]

Name	Type	Required	Valid Range	Description
appkey	String	Required		Origin appkey

[Query Parameters]

Name	Type	Required	Valid Range	Description
startX	String	Required		X coordinates at departure
startY	String	Required		Y coordinates at departure
endX	String	Required		X coordinates at destination
endY	String	Required		Y coordinates at destination
viaCount	String	Optional		Number of stopovers
via1X	String	Optional		X coordinates at stopover 1
via1Y	String	Optional		Y coordinates at stopover 1
via2X	String	Optional		X coordinates at stopover 2
via2Y	String	Optional		Y coordinates at stopover 2
option	String	Required		Optional route navigation Only one navigation option is available e.g.) option=real_traffic freeroad_priority: Free highway_priority: Highway real_traffic: Real-time real_traffic_freeroad: Real-time (free) real_traffic: Recommendation 1 real_traffic2: Recommendation 2 rt_stats: Real-time statistics rt_stats_freeroad: Real-time statistics (free) short_distance_priority: Short distance stats: Statistics stats_freeroad: Statistics (free) motorcycle: Two-wheeer

Response

Body

{
  "header": {
    "isSuccessful": true,
    "resultCode": 0,
    "resultMessage": ""
  },
  "routeDetail": {
    "DtlInfoRec": [
      [
        8,
        0,
        0,
        -1,
        -1,
        5,
        1
      ],
      [
        79,
        12,
        1,
        -1,
        -1,
        5,
        2
      ],
      ...
    ],
    "NameRec": [
      "National Road",
      "Pangyoyeok-ro 242beon-gil",
      "Pangyoyeok-ro 226beon-gil",
      "Natioal Road",
      "Daewangpangyo-ro 644beon-gil",
      "Turn riht",
      "Turn right",
      "Turn right",
      "Pangyo (Pangyo Techno Valley) station, Baekhyeon-dong"
    ],
    "RestRec": [],
    "RouteInfo": {
      "cross_name_cnt": 0,
      "dir_name_cnt": 1,
      "dist": 456,
      "dtl_cnt": 6,
      "max_x": 169113,
      "max_y": 517952,
      "min_x": 169034,
      "min_y": 517648,
      "rd_name_cnt": 5,
      "rest_cnt": 0,
      "sec_cnt": 5,
      "time": 3,
      "toll_cnt": 0,
      "vtx_cnt": 11
    },
    "SecInfoRec": [
      [
        8,
        0,
        0,
        1,
        0
      ],
      [
        126,
        14,
        1,
        2,
        1
      ],
      ...
    ],
    "VtxRec": [
      [
        169038,
        517943
      ],
      [
        169038,
        517952
      ],
      [
        169109,
        517952
      ],
      ...
    ]
  }
}

Field

Name	Type	Description
header	Object	Header area
header.isSuccessful	Boolean	Successful or not
header.resultCode	Integer	Failure code
header.resultMessage	String	Failure message
routeDetail	Object	Body area
RouteInfo	Object	Route information
RouteInfo.dist	Integer	Total length of a route (Unit: m)
RouteInfo.time	Integer	Total required time for a route (unit: minute)
RouteInfo.sec_cnt	Integer	Number of section information records
RouteInfo.dtl_cnt	Integer	Number of section detail records
RouteInfo.rd_name_cnt	Integer	Number of road name records
RouteInfo.guide_name_cnt	Integer	Number of guide name records
RouteInfo.cross_name_cnt	Integer	Number of intersection name records
RouteInfo.dir_name_cnt	Integer	Number of direction name records
RouteInfo.vtx_cnt	Integer	Number of interpolation points (route vector coordinates)
RouteInfo.rest_cnt	Integer	Number of rest areas
RouteInfo.toll_cnt	Integer	Number of toll gates
RouteInfo.max_x	Integer	Maximum x coordinates among interpolation point records
RouteInfo.max_y	Integer	Maximum y coordinates among interpolation point records
RouteInfo.min_x	Integer	Minimum x coordinates among interpolation point records
RouteInfo.min_y	Integer	Minimum y coordinates among interpolation point records
SecInfoRec	Array	Section information records
SecInfoRec[0].0	Integer	Distance of section (meter)
SecInfoRec[0].1	Integer	Speed of section
SecInfoRec[0].2	Integer	Road number or road name index
SecInfoRec[0].3	String	Number of detail section information records
SecInfoRec[0].4	String	Table index for section details
DtlInfoRec	Array	Record of section details
DtlInfoRec[0].0	Integer	Detail distance of section
DtlInfoRec[0].1	Integer	Detail speed of section
DtlInfoRec[0].2	String	Guide name index
DtlInfoRec[0].3	String	Intersection name index
DtlInfoRec[0].4	String	Direction name index
DtlInfoRec[0].5	String	By road type
DtlInfoRec[0].6	Integer	Interpolation point at guide point index
NameRec	Array	Name record
NameRec[0].0	String	Highway Name or Guide Name or Intersection Name or Direction Name
VtxRec	Array	Array of coordinates for interpolation record - route vector [[twX1, twY1], [twX2, twY2], … [twXn, twYn]]
VtxRec[0].0	Integer	twX
VtxRec[0].1	Integer	twY
RestRec	Array	Name record
RestRec[0].0	String	High-speed mode code
RestRec[0].1	String	Gas station code (0: N/A, 1: LG, 2: SK, 3: Ssang-yong, 4: Hanhwa, 5: Hyundai)
RestRec[0].2	String	Availability of LPG [0: N/A, 1: Available]
RestRec[0].3	String	Availability of repair shop [0: N/A, 1: Available]
RestRec[0].4	String	High-speed mode
RestRec[0].5	String	Reserved
RestRec[0].6	String	Name of rest area

3. Route Navigation Details (json Parsing)

Parsing for easy view of route navigation results

<script type="text/javascript" src="https://kr1-maps.api.nhncloudservice.com/maps/js/v1.0/route.js" > </script>
<script type="text/javascript">
function fnRouteParse(data){ // Detail result of route navigation 

  var routeParsing = route.jsonParsing(data);
  routeParsing.routeSummaryInfo;        // Summary of navigation results 
  routeParsing.routeDetailInfo;     // List of navigation routes 
  routeParsing.vtxInfo;             // List of coordinates for map drawing 
}
</script>

Field

Name	Type	Description
routeSummaryInfo	Object	Summary of navigation results
routeSummaryInfo.distance	Integer	Total length of route (unit: m)
routeSummaryInfo.time	Integer	Total time required for route (unit: minute)
routeSummaryInfo.max_x	String	Maximum x coordinates among interpolation point records
routeSummaryInfo.max_y	String	Maximum y coordinates among interpolation point records
routeSummaryInfo.min_x	String	Minimum x coordinates among interpolation point records
routeSummaryInfo.min_y	String	Minimum y coordinates among interpolation point records
routeDetailInfo	Array	List of navigation routes
routeDetailInfo.distance	Integer	Detail section distance (unit: m)
routeDetailInfo.speed	Integer	Detail section speed (unit: km/h)
routeDetailInfo.roadName	String	Road name
routeDetailInfo.direction	String	Direction information
routeDetailInfo.district	String	District information
routeDetailInfo.cross	String	Guide information
routeDetailInfo.directionDetail	String	Description of route details
vtxInfo	Array	List of coordinates for map drawing
vtxInfo[0].0	Integer	twX
vtxInfo[0].1	Integer	twY