Login
      Contents x
      gc
        • Print
        • PDF
        Contents

        gc

          • Print
          • PDF
          Article Summary

          Overview

          Reverse Geocoding is a service that converts geographic coordinates on a NAVER map into an address (coordsToAddr). The Reverse Geocoding API returns information including dong designated by law, dong assigned for administrative purposes, Land-Lot Based Address and Road Name Address, for specific coordinates.
          The Reverse Geocoding service supports some coordinate systems specified by European Petroleum Survey Group (EPSG) and those commonly used in Korea.

          Request 

          curl "https://naveropenapi.apigw.ntruss.com/map-reversegeocode/v2/gc?coords={input_coordinates}&sourcecrs={coordinate system}&orders={conversion_name}&output={output_format}" \
	-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

          Request Parameters

          Note
          • For sourcecrs, targetcrs, orders, and output, a default value is used when the parameter is omitted. Default values for each parameter are described in the table below.
          • You can explicitly call those parameters if you need to specify a value other than the default.
          • If you do not specify the orders parameter: legal and administrative results are returned.
          • If you need to get a detailed address: specify orders=legalcode,admcode,addr,roadaddr.
          • (The reason why you need to add legalcode or admcode to the orders parameter to request a detailed address: For areas that have no detailed addresses, such as areas near a coastline and new housing sites, at least you can get a legal code or administrative code rather than “no results.”)
          ParameterTypeRequiredDescription
          requeststringNRequest service name.
          Use “coordsToaddr” for Reverse Geocoding.
          The default is coordToaddr.
          Example) request=coordsToaddr
          coordsstringYSource coordinates.
          Example) coords=128.12345,37.98776
          sourcecrsstringNSource coordinate system code.
          The default is the latitude-longitude coordinate system (epsg:4326).
          Refer to Coordinate systems for available coordinate system codes.
          Example) sourcecrs=epsg:4326 (lat-lng coordinate system)
          sourcecrs=nhn:2048 (utm-k coordinate system)
          sourcecrs=nhn:128 (katech coordinate system)
          sourcecrs=epsg:3857 (Google coordinate system)
          targetcrsstringNTarget coordinate system code.
          The default is the lat-lng coordinate system (epsg:4326).
          Refer to Coordinate systems for available coordinate system codes.
          Example) targetcrs=epsg:4326 (lat-lng coordinate system)
          targetcrs=nhn:2048 (utm-k coordinate system)
          targetcrs=nhn:128 (katech coordinate system)
          targetcrs=epsg:3857 (Google coordinate system)
          ordersstringNConversion name.
          The default is legalcode,admcode.
          Available values are as follows:
          - legalcode: Coordinates to legal codes
          - admcode: Coordinates to administrative codes
          - addr: Coordinates to land-lot addresses
          - roadaddr: Coordinates to road name addresses (new addresses)
          Multiple values can be added, and the results are shown in the order of values added.
          Example) orders=legalcode
          orders=addr,admcode
          orders=addr,admcode,roadaddr
          orders=legalcode,addr,admcode,roadaddr
          outputstringNOutput format.
          Available values are json and xml.
          The default is xml.
          Example) output=json
          output=xml
          callbackstringNCallback name to pass when callback is required for jsonp communications.
          It is available only for output=json.
          The json data is wrapped by the specified callback name and returned.
          Example) callback=abc

          Coordinate systems

          NameCodeConnected serviceTypeGCS infoPCS infoNote
          Google MapsEPSG:3857PCSWGS_1984WGS_19846378137 (Semi_Minor)298.2572236GreenwichDegreeM0000Meter1
          WGS84 longitude and latitudeEPSG:4326GCSWGS_1984WGS_19846378137298.2572236GreenwichDegreeNot applicableNot applicableNot applicableNot applicableNot applicableNot applicableNot applicable
          UTM-KNHN:2048PCSD_ITRF_2000GRS_19806378137298.2572221GreenwichDegreeTM127.5382,000,0001,000,000Meter0.9996
          KATECH(TM128)NHN:128Mashup Map, Encyclopedia, Web OpenAPIPCSD_Korean_Datum_1985Bessel 18416377397.155299.1528128GreenwichDegreeTM12838600,000400,000Meter0.999910 ellipsoidal conversion factors: TRANSFORM"BADEKAS","-145.907,505.034,685.756,-1.162,2.347,1.592,6.342,-3159521.31,4068151.32,3748113.85"

          Request Header

          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

          PropertyTypeDescription
          namestringConversion name
          codenumberCode information
          code.idstringCode value
          code.typestringCode type
          Example) L: Legal dong, A: Administrative dong, S: Administrative dong where the legal dong with the same name exists.
          code.mappingIdstringID related mapping code.
          Example) NAVER dong code mapped with the legal code or NAVER dong code mapped with the administrative code
          regionRegion name information.
          region.area0
          region.area0.namestringTwo letters of the country code top level domain.
          Refer to Country code top-level domain for more information.
          region.area0.coords.centerCenter coordinates of the administrative district.
          region.area0.coords.center.crsstringCoordinate system code.
          Refer to Coordinate systems for available coordinate system codes.
          region.area0.coords.center.xfloatx-coordinate.
          Example) Longitude for the lat-lng coordinate system (epsg:4326).
          region.area0.coords.center.yfloaty-coordinate.
          Example) Latitude for the lat-lng coordinate system (epsg:4326).
          region.area1
          region.area1.namestringAdministrative district unit name 1.
          Example) City (Si) and Province (Do) names officially announced by the Ministry of Public Administration and Security in Korea
          region.area1.coordsCoordinates related to the administrative district
          region.area1.coords.centerCenter coordinates of the administrative district.
          region.area1.coords.center.crsstringCoordinate system code.
          Refer to Coordinate systems for available coordinate system codes.
          region.area0.coords.center.xfloatx-coordinate.
          Example) Longitude for the lat-lng coordinate system (epsg:4326).
          region.area1.coords.center.yfloaty-coordinate.
          Example) Latitude for the lat-lng coordinate system (epsg:4326).
          region.area2
          region.area2.namestringAdministrative district unit name 2.
          Example) Si, Gun, and Gu names officially announced by the Ministry of Public Administration and Security in Korea
          region.area2.coordsCoordinates related to the administrative district
          region.area2.coords.centerCenter coordinates of the administrative district.
          region.area2.coords.center.crsstringCoordinate system code.
          Refer to Coordinate systems for available coordinate system codes.
          region.area2.coords.center.xfloatx-coordinate.
          Example) Longitude for the lat-lng coordinate system (epsg:4326).
          region.area2.coords.center.yfloaty-coordinate.
          Example) Latitude for the lat-lng coordinate system (epsg:4326).
          region.area3
          region.area3.namestringAdministrative district unit name 3.
          Example) Eup, Myeon, and Dong names officially announced by the Ministry of Public Administration and Security in Korea
          region.area3.coordsCoordinates related to the administrative district
          region.area3.coords.centerCenter coordinates of the administrative district.
          region.area3.coords.center.crsstringCoordinate system code.
          Refer to Coordinate systems for available coordinate system codes.
          region.area3.coords.center.xfloatx-coordinate.
          Example) Longitude for the lat-lng coordinate system (epsg:4326).
          region.area3.coords.center.yfloaty-coordinate.
          Example) Latitude for the lat-lng coordinate system (epsg:4326).
          region.area4
          region.area4.namestringAdministrative district unit name 4.
          Example) Li names officially announced by the Ministry of Public Administration and Security in Korea
          region.area4.coordsCoordinates related to the administrative district
          region.area4.coords.centerCenter coordinates of the administrative district.
          region.area4.coords.center.crsstringCoordinate system code.
          Refer to Coordinate systems for available coordinate system codes.
          region.area4.coords.center.xfloatx-coordinate.
          Example) Longitude for the lat-lng coordinate system (epsg:4326).
          region.area4.coords.center.yfloaty-coordinate.
          Example) Latitude for the lat-lng coordinate system (epsg:4326).
          landDetailed address information
          land.typestringLand type for land-lot based addresses
          Example) For land-lot based addresses in Korea, 1: General land, 2: Mountain
          For road name addresses, it is reserved.
          land.namestringDetailed name.
          Example) For land-lot based addresses in Korea, it is reserved.
          For road name addresses in Korea, it is a road name.
          land.number1stringDetailed number 1.
          Example) For land-lot based addresses in Korea, it is a main number.
          For road name addresses in Korea, it is a detailed address.
          land.number2stringDetailed number 2.
          Example) For land-lot based addresses in Korea, it is a sub number.
          For road name addresses in Korea, it is reserved.
          land.coordsCoordinates related to cadastral areas (reserved)
          addition0Additional information.
          For land-lot based addresses, it is reserved.
          For road name addresses, it is building information.
          addition0.typestringFor road name addresses with building information, it is building.
          addition0.valuestringFor road name addresses with building information, it is a building name.
          addition1Additional information.
          For land-lot based addresses, it is reserved.
          For road name addresses, it is a zip code.
          addition1.typestringFor road name addresses with zip code information, it is zipcode.
          addition1.valuestringFor road name addresses with zip code information, it is a zip code.
          addition2Additional information.
          For land-lot based addresses, it is reserved.
          For road name addresses, it is a road code.
          addition2.typestringFor road name addresses, it is 'roadGroupCode'.
          addition2.valuestringFor road name addresses, it is a road code (12-digit road group code).
          addutuib3~4reserved
          Note

          The API request returns different response data depending on the source coordinates. See the following cases.

          • Eup/Myeon/Dong
            https://naveropenapi.apigw.ntruss.com/map-reversegeocode/v2/gc?request=coordsToaddr&coords=126.9913201,37.5666936&sourcecrs=epsg:4326&orders=admcode,legalcode,addr,roadaddr&output=xml
            https://naveropenapi.apigw.ntruss.com/map-reversegeocode/v2/gc?request=coordsToaddr&coords=129.1133567,35.2982640&sourcecrs=epsg:4326&orders=admcode,legalcode,addr,roadaddr&output=xml

          • Li: As “Li” is a unit under “Eup/Myeon” designated by law, the code type for admcode is also set to “L.”
            https://naveropenapi.apigw.ntruss.com/map-reversegeocode/v2/gc?request=coordsToaddr&coords=128.2439084,36.4938906&sourcecrs=epsg:4326&orders=admcode,legalcode,addr,roadaddr&output=xml

          • Bundang-gu Jeongja-dong: There are administrative dongs with the same name as the legal dong (in different areas).
            https://naveropenapi.apigw.ntruss.com/map-reversegeocode/v2/gc?request=coordsToaddr&coords=127.1114893,37.3614463&sourcecrs=epsg:4326&orders=admcode,legalcode,addr,roadaddr&output=xml

          • Coordinates of Sejong-si: No si/gun/gu area2 data exists, and all administrative dongs under Sejong-si have the same legal dong (in different areas).

            • Dodam-dong (the same name in legal/administrative dong): https://naveropenapi.apigw.ntruss.com/map-reversegeocode/v2/gc?request=coordsToaddr&coords=127.2654387,36.5008113&sourcecrs=epsg:4326&orders=admcode,legalcode,addr,roadaddr&output=xml

            • Jochiwon-eup (legal): https://naveropenapi.apigw.ntruss.com/map-reversegeocode/v2/gc?request=coordsToaddr&coords=127.2923750,36.5929071&sourcecrs=epsg:4326&orders=admcode,legalcode,addr,roadaddr&output=xml

          • On the sea (no data): https://naveropenapi.apigw.ntruss.com/map-reversegeocode/v2/gc?request=coordsToaddr&coords=125.9913201,37.5666936&sourcecrs=epsg:4326&orders=admcode,legalcode,addr,roadaddr&output=xml

          Examples

          Request Example 

          curl "https://naveropenapi.apigw.ntruss.com/map-reversegeocode/v2/gc?request=coordsToaddr&coords=129.1133567,35.2982640&sourcecrs=epsg:4326&output=json&orders=legalcode,admcode" \
	-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
          • Convert coordinates into a legal code
            https://naveropenapi.apigw.ntruss.com/map-reversegeocode/v2/gc?request=coordsToaddr&coords=129.1133567,35.2982640&sourcecrs=epsg:4326&output=json&orders=legalcode
          • Convert coordinates into a land-lot based address and administrative code
            https://naveropenapi.apigw.ntruss.com/map-reversegeocode/v2/gc?request=coordsToaddr&coords=129.1133567,35.2982640&sourcecrs=epsg:4326&output=json&orders=addr,admcode
          • Convert coordinates into a land-lot based address, administrative code and road name address
            https://naveropenapi.apigw.ntruss.com/map-reversegeocode/v2/gc?request=coordsToaddr&coords=129.1133567,35.2982640&sourcecrs=epsg:4326&output=json&orders=addr,admcode,roadaddr

          Request Example 

          {
    "status":{
            "code":0,
            "name":"ok",
            "message":"done"
        },
    "results":[
        {
            "name":"legalcode",
            "code":{
                "id":"2641010100",
                "type":"L",
                "mappingId":"08410101"
            },
            "region":{
                "area0":{
                    "name":"kr",
                    "coords":{
                        "center":{
                            "crs":"",
                            "x":0.0,
                            "y":0.0
                        }
                    }
                },
                "area1":{
                    "name":"Busan Metropolitan City",
                    "coords":{
                        "center":{
                            "crs":"EPSG:4326",
                            "x":129.0750222,
                            "y":35.1798159
                        }
                    }
                },
                "area2":{
                    "name":"Guemjeong-gu",
                    "coords":{
                        "center":{
                            "crs":"EPSG:4326",
                            "x":129.0921,
                            "y":35.243068
                        }
                    }
                },
                "area3":{
                    "name":"Dugu-dong",
                    "coords":{
                        "center":{
                            "crs":"EPSG:4326",
                            "x":129.1133567,
                            "y":35.2982641
                        }
                    }
                },
                "area4":{
                    "name":"",
                    "coords":{
                        "center":{
                            "crs":"",
                            "x":0.0,
                            "y":0.0
                        }
                    }
                }
            }
        }
    ]
}

          Error Codes

          The API returns HTTP status 200 if the request was successful, with the following codes.

          codenameDescription
          0okThe API request is successfully made and returns a result.
          3no resultsThe API request is successfully made but returns no result.

          If the API request was not successful, it returns the following.

          HTTP status codeError codeError messageDescription
          400100invalid requestInvalid request parameters
          500900unknown error / io errorUnknown error
          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