Geocoding

Prev Next

VPC 환경에서 이용 가능합니다.

입력한 주소와 연관된 주소 정보를 검색합니다.

요청

요청 형식을 설명합니다. 요청 형식은 다음과 같습니다.

메서드 URI
GET /geocode

요청 헤더

요청 헤더에 대한 설명은 다음과 같습니다.

필드 필수 여부 설명
Accept Required 응답 데이터의 형식
  • application/json

Maps API에서 공통으로 사용하는 헤더에 대한 정보는 Maps 공통 헤더를 참조해 주십시오.

요청 쿼리 파라미터

요청 쿼리 파라미터에 대한 설명은 다음과 같습니다.

필드 타입 필수 여부 설명
query String Required 검색할 주소
coordinate String Optional 검색 중심 좌표(경도,위도)
  • 입력한 좌표와 근접한 순으로 검색 결과 표시
filter Integer Optional 검색 결과 필터
  • HCODE | BCODE
    • hCODE: 행정동 코드
    • BCODE: 법정동 코드
  • 필터 타입@코드1;코드2;...... 형식으로 입력
  • <예시> HCODE@4113554500;4113555000
language String Optional 응답 결과 언어
  • kor (기본값) | eng
    • kor: 한국어
    • eng: 영어
page Number Optional 페이지 번호
  • 1 (기본값)
count Number Optional 결과 목록 크기
  • 1~100 (기본값: 10)

요청 예시

요청 예시는 다음과 같습니다.

curl --location --request GET 'https://naveropenapi.apigw.ntruss.com/map-geocode/v2/geocode?query=분당구 불정로 6' \
--header 'x-ncp-apigw-api-key-id: {API Key ID}' \
--header 'x-ncp-apigw-api-key: {API Key}' \
--header 'Accept: application/json'

응답

응답 형식을 설명합니다.

응답 바디

응답 바디에 대한 설명은 다음과 같습니다.

필드 타입 필수 여부 설명
status String - 응답 코드
meta Object - 메타 데이터
meta.totalCount Number - 응답 결과 개수
meta.page Number - 현재 페이지 번호
meta.count Number - 페이지 내 결과 개수
addresses Array - 주소 정보 목록
errorMessage String - 오류 메시지
  • 500 오류(알 수 없는 오류) 발생 시에만 표시

addresses

addresses에 대한 설명은 다음과 같습니다.

필드 타입 필수 여부 설명
roadAddress String - 도로명 주소
jibunAddress String - 지번 주소
englishAddress String - 영어 주소
addressElements Array - 주소 구성 요소 정보
x String - X 좌표(경도)
y String - Y 좌표(위도)
distance Double - 중심 좌표로부터의 거리(m)

addressElements

addressElements에 대한 설명은 다음과 같습니다.

필드 타입 필수 여부 설명
type Array - 주소 구성 요소 타입
  • SIDO | SIGUGUN | DONGMYUN | RI | ROAD_NAME | BUILDING_NUMBER | BUILDING_NAME | LAND_NUMBER | POSTAL_CODE
    • SIDO: 시/도
    • SIGUGUN: 시/구/군
    • DONGMYUN: 동/면
    • RI: 리
    • ROAD_NAME: 도로명
    • BUILDING_NUMBER: 건물 번호
    • BUILDING_NAME: 건물 이름
    • LAND_NUMBER: 번지
    • POSTAL_CODE: 우편번호
longName String - 주소 구성 요소 이름
shortName String - 주소 구성 요소 축약 이름
code String - -

응답 상태 코드

응답 상태 코드에 대한 설명은 다음과 같습니다.

HTTP 상태 코드 코드 메시지 설명
200 OK - 요청 처리 성공. 정상 응답
400 INVALID_REQUEST - 요청 오류
500 SYSTEM_ERROR Unexpected Error 알 수 없는 오류
참고

Maps API에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 Maps 공통 응답 상태 코드를 참조해 주십시오.

응답 예시

응답 예시는 다음과 같습니다.

{
    "status": "OK",
    "meta": {
        "totalCount": 1,
        "page": 1,
        "count": 1
    },
    "addresses": [
        {
            "roadAddress": "경기도 성남시 분당구 불정로 6 NAVER그린팩토리",
            "jibunAddress": "경기도 성남시 분당구 정자동 178-1 NAVER그린팩토리",
            "englishAddress": "6, Buljeong-ro, Bundang-gu, Seongnam-si, Gyeonggi-do, Republic of Korea",
            "addressElements": [
                {
                    "types": [
                        "SIDO"
                    ],
                    "longName": "경기도",
                    "shortName": "경기도",
                    "code": ""
                },
                {
                    "types": [
                        "SIGUGUN"
                    ],
                    "longName": "성남시 분당구",
                    "shortName": "성남시 분당구",
                    "code": ""
                },
                {
                    "types": [
                        "DONGMYUN"
                    ],
                    "longName": "정자동",
                    "shortName": "정자동",
                    "code": ""
                },
                {
                    "types": [
                        "RI"
                    ],
                    "longName": "",
                    "shortName": "",
                    "code": ""
                },
                {
                    "types": [
                        "ROAD_NAME"
                    ],
                    "longName": "불정로",
                    "shortName": "불정로",
                    "code": ""
                },
                {
                    "types": [
                        "BUILDING_NUMBER"
                    ],
                    "longName": "6",
                    "shortName": "6",
                    "code": ""
                },
                {
                    "types": [
                        "BUILDING_NAME"
                    ],
                    "longName": "NAVER그린팩토리",
                    "shortName": "NAVER그린팩토리",
                    "code": ""
                },
                {
                    "types": [
                        "LAND_NUMBER"
                    ],
                    "longName": "178-1",
                    "shortName": "178-1",
                    "code": ""
                },
                {
                    "types": [
                        "POSTAL_CODE"
                    ],
                    "longName": "13561",
                    "shortName": "13561",
                    "code": ""
                }
            ],
            "x": "127.1054328",
            "y": "37.3595963",
            "distance": 0.0
        }
    ],
    "errorMessage": ""
}