geocode
  • PDF

geocode

  • PDF

개요

주소 검색 API는 지번, 도로명를 질의어로 사용해서 주소 정보를 검색합니다. 검색 결과로 주소 목록과 세부 정보를 JSON 형태로 반환합니다.

요청

curl -G "https://naveropenapi.apigw.ntruss.com/map-geocode/v2/geocode" \
    --data-urlencode "query={주소}" \
    --data-urlencode "coordinate={검색_중심_좌표}" \
    -H "X-NCP-APIGW-API-KEY-ID: {애플리케이션 등록 시 발급받은 client id값}" \
    -H "X-NCP-APIGW-API-KEY: {애플리케이션 등록 시 발급받은 client secret값}" -v

요청 파라미터

파라미터 데이터 타입 필수 여부 설명
query string Y 주소
coordinate string N - 검색 중심 좌표
'lon,lat' 형식으로 입력
filter string N - 검색 결과 필터링 조건
'필터 타입@코드1;코드2;... ' 형식으로 입력
제공하는 필터 타입은 다음과 같음:
HCODE: 행정동 코드
BCODE: 법정동 코드

예) HCODE@4113554500;4113555000
page number N - 페이지 번호
기본값은 1
count number N - 결과 목록 크기
입력 범위: 1~100
기본값: 10

요청 헤더

헤더명 필수 여부 설명
X-NCP-APIGW-API-KEY-ID Y 앱 등록 시 발급받은 Client ID
X-NCP-APIGW-API-KEY-ID:{Client ID}
X-NCP-APIGW-API-KEY Y 앱 등록 시 발급 받은 Client Secret
X-NCP-APIGW-API-KEY:{Client Secret}
Accept N - 응답 포맷
JSON(기본값), XML 지원
MIME 타입으로 원하는 포맷을 설정
Accept: application/json
Accept: application/xml

요청 바디

  • 해당 API 는 요청 바디를 필요로 하지 않습니다.

응답

응답 바디

속성 데이터 타입 필수 여부 설명
status string Y 검색 결과 상태 코드
errorMessage string N 예외 발생 시 메시지
meta object N 검색 메타 데이터
meta.totalCount number N 총 검색 건수
meta.page number N 현재 페이지 번호
meta.count number N 페이지 내 결과 개수
addresses array N 주소 검색 결과 목록
addresses[].roadAddress string N 도로명 주소
addresses[].jibunAddress string N 지번 주소
addresses[].englishAddress string N 영어 주소
addresses[].x string N x 좌표(경도)
addresses[].y string N y 좌표(위도)
addresses[].distance double N 검색 중심 좌표로부터의 거리(단위: 미터)
addresses[].addressElements array N 주소를 이루는 요소들

예시

요청 예시

curl -G "https://naveropenapi.apigw.ntruss.com/map-geocode/v2/geocode" \
    --data-urlencode "query=분당구 불정로 6" \
    --data-urlencode "coordinate=127.1054328,37.3595963" \
    -H "X-NCP-APIGW-API-KEY-ID: {애플리케이션 등록 시 발급받은 client id값}" \
    -H "X-NCP-APIGW-API-KEY: {애플리케이션 등록 시 발급받은 client secret값}" -v

응답 예시

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

오류 코드

HttpStatusCode ResultCode ErrorMessage Description
200 OK - 정상 응답
400 INVALID_REQUEST Bad Request Exception 요청 오류
500 SYSTEM_ERROR Unexpected Error 예외처리가 안된 오류

이 문서가 도움이 되었습니까?