아키텍처

1. 인증

BigValue Data API는 인증을 위해 JWT 토큰을 발급받아야 합니다. JWT 토큰 발급은 영업팀에 문의해 주세요.

2. 데이터 접근 방식

BigValue Data API는 자연어 주소를 기반으로 다양한 공간 데이터를 통합적으로 접근할 수 있도록 설계되었습니다. 핵심적인 접근 방식은 다음과 같습니다.

1. 주소 검색 API 호출 : 먼저, 사용자는 자연어 주소(예 : 서울특별시 중구 서소문로 138)를 이용하여 주소 검색 API를 호출합니다.
2. 키 조회 : API의 결과로 다음과 같은 키(Key)들을 조회할 수 있습니다.

• 빅밸류 단지키 : 빅밸류가 정의한 단지 단위의 키로 단지 전체에 대한 정보를 조회할 때 사용합니다.
• 빅밸류 동키 : 빅밸류가 정의한 동 단위의 키로 동 전체에 대한 정보를 조회할 때 사용합니다.
• 빅밸류 호키 : 빅밸류가 정의한 호 단위의 키로 호에 대한 정보를 조회할 때 사용합니다.
• 필지 고유번호 : 지번주소를 코드화한 값으로 해당 필지에 대한 정보를 조회할 때 사용합니다.
• 도로명주소 관리번호 : 도로명주소를 코드화한 값으로 해당 도로명주소에 대한 정보를 조회할 때 사용합니다.

3. 키를 이용한 데이터 API 호출 : 조회한 키(Key)를 이용하여 건축물, 토지, 실거래 등 다양한 데이터 API를 호출할 수 있습니다. 각 키(Key)에 따라 호출할 수 있는 API가 다를 수 있으니 API 문서 상세 설명을 참고해주세요.

3. 응답결과

BigValue Data API는 DATA_COUNT 와 DATA로 정의된 키를 갖습니다. DATA_COUNT에는 API의 응답 건수가 담기고, DATA에는 각 API 상품의 데이터가 담깁니다.

항목명	형식	필수	설명
DATA_COUNT	NUMBER	Y	API 응답 건수
DATA	OBJECT	Y	API 상품 데이터

API 상품마다 DATA의 형식과 값이 다르며, 요청 파라미터도 다릅니다. API 상품별 파라미터는 API 문서를 확인하세요.

다음은 주소검색 API의 결과 예시입니다.

{
  "DATA_COUNT": 1,
  "DATA": [
    {
      "complex_key": "c00024471",
      "dong_key": "d00041377",
      "ho_key": "none",
      "pnu": "1114011400103400006",
      "road_name_address_management_number": "11140114300501000013800000",
      "building_name": null,
      "dong_name": null,
      "ho_name": null,
      "land_number_address": "서울특별시 중구 태평로2가 340-6번지",
      "road_name_address": "서울특별시 중구 서소문로 138",
      "ppk": "11140-3168",
      "jpk": "none"
    }
  ]
}

4. 오류 응답결과

BigValue Data API는 네트워크, 서버, 인증, 클라이언트 등 다양한 원인에 따라 오류가 발생할 수 있습니다.

에러코드	에러메세지	내용
400	"detail": "{파라미터명} 파라미터 유효성 검증 실패"	파라미터 유효성 검증 실패
400	"detail": "{파라미터명} 필수 파라미터는 반드시 입력 해야 합니다."	필수 파라미터 미입력
401	"detail": "Not authenticated"	인증 실패
401	"detail": "변조된 토큰입니다."	변조된 인증 토큰 요청 시 발생
500		예외 처리가 안된 오류

5. 샘플코드

python

import requests

url = "https://api.bigvalue.co.kr/api/address_search"
headers = {"Authorization": "Bearer " + "발급받은 JWT토큰"}
params = {"address": "서울특별시 중구 서소문로 138"}

response = requests.get(url=url, params=params, headers=headers)

print(response.json())

"""
Output:
{'DATA_COUNT': 1,
 'DATA': [{'complex_key': 'c00024471',
   'dong_key': 'd00041377',
   'ho_key': 'none',
   'pnu': '1114011400103400006',
   'road_name_address_management_number': '11140114300501000013800000',
   'building_name': None,
   'dong_name': None,
   'ho_name': None,
   'land_number_address': '서울특별시 중구 태평로2가 340-6번지',
   'road_name_address': '서울특별시 중구 서소문로 138',
   'ppk': '11140-3168',
   'jpk': 'none'}]}
"""