geocode
    • PDF

    geocode

    • PDF

    기사 요약

    개요

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

    요청

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

    요청 파라미터

    파라미터데이터 타입필수 여부설명
    querystringY주소
    coordinatestringN검색 중심 좌표 ('lon,lat' 형식으로 입력)
    filterstringN- 검색 결과 필터링 조건
    '필터 타입@코드1;코드2;... ' 형식으로 입력

    제공하는 필터 타입:
    HCODE: 행정동 코드
    BCODE: 법정동 코드

    예) HCODE@4113554500;4113555000
    languagestringN- language=eng 추가 시 영문 주소 검색 활성화
    기본값: kor
    pagenumberN페이지 번호
    기본값: 1
    countnumberN- 결과 목록 크기
    입력 범위: 1~100
    기본값: 10

    요청 헤더

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

    요청 바디

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

    응답

    응답 바디

    속성데이터 타입필수 여부설명
    statusstringY검색 결과 상태 코드
    errorMessagestringN예외 발생 시 메시지
    metaobjectN검색 메타 데이터
    meta.totalCountnumberN총 검색 건수
    meta.pagenumberN현재 페이지 번호
    meta.countnumberN페이지 내 결과 개수
    addressesarrayN주소 검색 결과 목록
    addresses[].roadAddressstringN도로명 주소
    addresses[].jibunAddressstringN지번 주소
    addresses[].englishAddressstringN영어 주소
    addresses[].xstringNx 좌표(경도)
    addresses[].ystringNy 좌표(위도)
    addresses[].distancedoubleN검색 중심 좌표로부터의 거리(단위: 미터)
    addresses[].addressElementsarrayN주소를 이루는 요소들

    예시

    요청 예시

    curl "https://naveropenapi.apigw.gov-ntruss.com/map-geocode/v2/geocode?query=분당구 불정로 6&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": ""
    }
    

    에러 코드

    HttpStatusCodeResultCodeErrorMessageDescription
    200OK-정상 응답
    400INVALID_REQUESTBad Request Exception요청 에러
    500SYSTEM_ERRORUnexpected Error예외처리가 안된 에러

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

    Changing your password will log you out immediately. Use the new password to log back in.
    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.