budongsan-api/dist/index.d.ts

국토교통부 아파트 실거래가, 전월세, 단지 정보, 용적률 등 공공데이터 API 래퍼

type T_ApartmentInfo = {
    kaptCode: string;
    kaptName: string;
    kaptAddr: string;
    codeSaleNm: string;
    codeHeatNm: string;
    kaptTarea: number;
    kaptDongCnt: string;
    kaptdaCnt: number;
    kaptBcompany: string;
    kaptAcompany: string;
    kaptTel: string;
    kaptUrl: string;
    codeAptNm: string;
    doroJuso: string;
    codeMgrNm: string;
    codeHallNm: string;
    kaptUsedate: string;
    kaptFax: string;
    hoCnt: number;
    kaptMarea: number;
    kaptMparea60: number;
    kaptMparea85: number;
    kaptMparea135: number;
    kaptMparea136: number;
    privArea: string;
    bjdCode: string;
    kaptTopFloor: number;
    ktownFlrNo: number;
    kaptBaseFloor: number;
    kaptdEcntp: number;
    zipcode: string;
};
type T_ApartmentDetailInfo = {
    kaptCode: string;
    kaptName: string;
    codeMgr: string;
    kaptMgrCnt: string;
    kaptCcompany: string;
    codeSec: string;
    kaptdScnt: string;
    kaptdSecCom: string;
    codeClean: string;
    kaptdClcnt: string;
    codeGarbage: string;
    codeDisinf: string;
    kaptdDcnt: string;
    disposalType: string;
    codeStr: string;
    kaptdEcapa: string | number;
    codeEcon: string;
    codeEmgr: string;
    codeFalarm: string;
    codeWsupply: string;
    codeElev: string;
    kaptdEcnt: number;
    kaptdPcnt: string;
    kaptdPcntu: string;
    codeNet: string;
    kaptdCccnt: string;
    welfareFacility: string;
    kaptdWtimebus: string;
    subwayLine: string;
    subwayStation: string;
    kaptdWtimesub: string;
    convenientFacility: string;
    educationFacility: string;
    groundElChargerCnt: number;
    undergroundElChargerCnt: number;
};
type T_ApartmentSimpleInfo = {
    kaptCode: string;
    kaptName: string;
    bjdCode: string;
    as1: string;
    as2: string;
    as3: string;
    as4: string | null;
};
type T_ApartmentTradeBasicInfo = {
    aptDong: number;
    aptNm: string;
    buildYear: number;
    buyerGbn: string;
    cdealDay: string;
    cdealType: string;
    dealAmount: string;
    dealDay: number;
    dealMonth: number;
    dealYear: number;
    dealingGbn: string;
    estateAgentSggNm: string;
    excluUseAr: number;
    floor: number;
    jibun: number;
    landLeaseholdGbn: string;
    rgstDate: string;
    sggCd: number;
    slerGbn: string;
    umdNm: string;
};
type T_ApartmentTradeDetailInfo = {
    aptDong: number;
    aptNm: string;
    aptSeq: string;
    bonbun: string;
    bubun: string;
    buildYear: number;
    buyerGbn: string;
    cdealDay: string;
    cdealType: string;
    dealAmount: string;
    dealDay: number;
    dealMonth: number;
    dealYear: number;
    dealingGbn: string;
    estateAgentSggNm: string;
    excluUseAr: number;
    floor: number;
    jibun: number;
    landCd: number;
    landLeaseholdGbn: string;
    rgstDate: string;
    roadNm: string;
    roadNmBonbun: string;
    roadNmBubun: string;
    roadNmCd: number;
    roadNmSeq: string;
    roadNmSggCd: number;
    roadNmbCd: number;
    sggCd: number;
    slerGbn: string;
    umdCd: number;
    umdNm: string;
};
type T_ApartmentRentInfo = {
    aptNm: string;
    buildYear: number;
    contractTerm: string;
    contractType: string;
    dealDay: number;
    dealMonth: number;
    dealYear: number;
    deposit: string;
    excluUseAr: number;
    floor: number;
    jibun: number;
    monthlyRent: number;
    preDeposit: string;
    preMonthlyRent: string;
    sggCd: number;
    umdNm: string;
    useRRRight: string;
};
type T_BrRecapTitleInfo = {
    rnum: number;
    platPlc: string;
    sigunguCd: string;
    bjdongCd: string;
    platGbCd: string;
    bun: string;
    ji: string;
    mgmBldrgstPk: number;
    regstrGbCd: string;
    regstrGbCdNm: string;
    regstrKindCd: string;
    regstrKindCdNm: string;
    newOldRegstrGbCd: string;
    newOldRegstrGbCdNm: string;
    newPlatPlc: string;
    bldNm: string;
    splotNm: string;
    block: string;
    lot: string;
    bylotCnt: number;
    naRoadCd: string;
    naBjdongCd: string;
    naUgrndCd: string;
    naMainBun: string;
    naSubBun: string;
    platArea: number;
    archArea: number;
    bcRat: number;
    totArea: number;
    vlRatEstmTotArea: number;
    vlRat: number;
    mainPurpsCd: string;
    mainPurpsCdNm: string;
    etcPurps: string;
    hhldCnt: number;
    fmlyCnt: number;
    mainBldCnt: number;
    atchBldCnt: number;
    atchBldArea: number;
    totPkngCnt: number;
    indrMechUtcnt: number;
    indrMechArea: number;
    oudrMechUtcnt: number;
    oudrMechArea: number;
    indrAutoUtcnt: number;
    indrAutoArea: number;
    oudrAutoUtcnt: number;
    oudrAutoArea: number;
    pmsDay: string;
    stcnsDay: string;
    useAprDay: string;
    pmsnoYear: string;
    pmsnoKikCd: string;
    pmsnoKikCdNm: string;
    pmsnoGbCd: string;
    pmsnoGbCdNm: string;
    hoCnt: number;
    engrGrade: string;
    engrRat: number;
    engrEpi: number;
    gnBldGrade: string;
    gnBldCert: number;
    itgBldGrade: string;
    itgBldCert: number;
    crtnDay: string;
};
/**
 * BudongsanAPI는 국토교통부 아파트 공공데이터를 조회하는 클라이언트입니다.
 */
declare class BudongsanAPIClass {
    private serviceKey;
    /**
    * BudongsanAPI 인스턴스를 생성합니다.
    * @param serviceKey 공공데이터 포털에서 발급받은 서비스 키
    */
    constructor(serviceKey: string);
    /**
     * 아파트 단지 기본 정보를 조회합니다.
     * @param kaptCode 아파트 단지 코드
     * @returns 단지 기본 정보 (object)
     * @throws API 호출 실패 시 예외가 발생합니다.
     */
    getApartmentBasicInfo(kaptCode: string): Promise<T_ApartmentInfo>;
    /**
     * 아파트 단지 상세 정보를 조회합니다.
     * @param kaptCode 아파트 단지 코드
     * @returns 단지 상세 정보 (object)
     * @throws API 호출 실패 시 예외가 발생합니다.
     */
    getApartmentDetailInfo(kaptCode: string): Promise<T_ApartmentDetailInfo>;
    /**
     * 시군구 코드에 따른 아파트 단지 목록을 조회합니다.
     * @param sigunguCode 시군구 코드
     * @param numOfRows 페이지당 결과 수
     * @param pageNo 페이지 번호
     * @returns 단지 목록 (배열)
     * @throws API 호출 실패 시 예외가 발생합니다.
     */
    getApartmentList(sigunguCode: string, numOfRows?: string, pageNo?: string): Promise<T_ApartmentSimpleInfo | Array<T_ApartmentSimpleInfo>>;
    /**
     * 특정 거래 년월의 아파트 실거래가(기본)를 조회합니다.
     * @param sigunguCode 시군구 코드 (5자리)
     * @param DEAL_YMD 거래 년월 (YYYYMM)
     * @param numOfRows 페이지당 결과 수
     * @param pageNo 페이지 번호
     * @returns 실거래 정보 목록 (배열)
     * @throws API 호출 실패 시 예외가 발생합니다.
     */
    getApartmentTradeBasicList(sigunguCode: string, DEAL_YMD: string, numOfRows?: string, pageNo?: string): Promise<T_ApartmentTradeBasicInfo | Array<T_ApartmentSimpleInfo>>;
    /**
     * 특정 거래 년월의 아파트 실거래가(상세)를 페이지 단위로 조회합니다.
     * @param sigunguCode 시군구 코드 (5자리)
     * @param DEAL_YMD 거래 년월 (YYYYMM)
     * @param numOfRows 페이지당 결과 수
     * @param pageNo 페이지 번호
     * @returns 실거래 상세 정보 목록 (배열)
     * @throws API 호출 실패 시 예외가 발생합니다.
     */
    getApartmentTradeDetailList(sigunguCode: string, DEAL_YMD: string, numOfRows?: string, pageNo?: string): Promise<T_ApartmentTradeDetailInfo | Array<T_ApartmentTradeDetailInfo>>;
    /**
     * 특정 거래 년월의 아파트 전월세 정보를 조회합니다.
     * @param sigunguCode 시군구 코드 (5자리)
     * @param DEAL_YMD 거래 년월 (YYYYMM)
     * @param numOfRows 페이지당 결과 수
     * @param pageNo 페이지 번호
     * @returns 전월세 정보 목록 (배열)
     * @throws API 호출 실패 시 예외가 발생합니다.
     */
    getApartmentRentList(sigunguCode: string, DEAL_YMD: string, numOfRows?: string, pageNo?: string): Promise<T_ApartmentRentInfo | Array<T_ApartmentRentInfo>>;
    /**
     * 건축물대장 총괄표제부 정보를 조회합니다.
     *
     * @param {string} sigunguCode - 시군구 코드 (예: '11710')
     * @param {string} bjdongCode - 법정동 코드 (예: '11200')
     * @param {string} bun - 번지 (예: '0138')
     * @param {string} ji - 지번 (예: '0000')
     * @param {string} [numOfRows="10"] - 페이지당 결과 수 (기본값: 10)
     * @param {string} [pageNo="1"] - 페이지 번호 (기본값: 1)
     * @returns {Promise<any>} 건축물대장 총괄표제부 API 응답 데이터
     */
    getBrRecapTitleList(sigunguCode: string, bjdongCode: string, bun: string, ji: string, numOfRows?: string, pageNo?: string): Promise<T_BrRecapTitleInfo | Array<T_BrRecapTitleInfo>>;
    /**
     * 공통 fetch 및 응답 처리 로직
     */
    private fetchAndExtract;
}

type T_Bjd = {
    bjd_code: string;
    bjd_name: string;
};
type T_SigunguFlat = {
    sido_name: string;
    sido_code: string;
    sigungu_name: string;
    sigungu_code: string;
    bjd_array?: T_Bjd[];
};
type T_SigunguKeyType = "code" | "name";
declare class SigunguServiceClass {
    private static _instance;
    private _dataCache;
    private _dataPath;
    private constructor();
    private _getLibraryDataPath;
    static getInstance(): SigunguServiceClass;
    private _loadDataSync;
    getSigunguList(): T_SigunguFlat[];
    getSigunguMap(keyType?: T_SigunguKeyType): Map<string, Omit<T_SigunguFlat, "bjd_array">>;
    getBjdList(): T_Bjd[];
    getBjdMapBySigungu(keyType?: T_SigunguKeyType): Map<string, T_Bjd[]>;
}
declare const SigunguService: SigunguServiceClass;

declare class BudongsanUtil {
    /**
     * 현재 한국 기준 연도와 월을 반환합니다.
     * @returns {{ year: string, month: string }}
     */
    static getKoreanYearMonth(): {
        year: string;
        month: string;
    };
    /**
     * 시작 연월부터 종료 연월까지의 YYYYMM 문자열 배열을 생성합니다.
     * @param {number} startYear 시작 연도
     * @param {number} startMonth 시작 월
     * @param {number} endYear 종료 연도
     * @param {number} endMonth 종료 월
     * @returns {string[]} YYYYMM 문자열 배열
     */
    static generateDealYMDRange(startYear: number, startMonth: number, endYear: number, endMonth: number): string[];
    /**
     * 숫자 문자열을 한글 화폐 단위로 포맷팅합니다. (예: "55,000" → "5억 5000만")
     * @param {string|number} amount 원 단위 기준 숫자 또는 문자열
     * @returns {string} 한글 화폐 단위 문자열
     */
    static formatKoreanCurrency(amount: string | number): string;
    static getGoogleMapLatitudeAndlongitude: (krjuso: string, googleApikey: string) => Promise<{
        latitude: string;
        longitude: string;
    } | {
        latitude: string;
        longitude: string;
    }>;
    static getKakaoMapPosition: (param_juso: string | number | boolean, kakaoApikey: string) => Promise<{
        addressName: string;
        roadAddressName: string;
        apartKakaoName: string;
        latitude: number;
        longitude: number;
    } | {
        addressName: string;
        roadAddressName: string;
        apartKakaoName: string;
        latitude: string;
        longitude: string;
    } | {
        addressName: string;
        roadAddressName: string;
        apartKakaoName: string;
        latitude: string;
        longitude: string;
    }>;
    static getKakaoCategory: (param_y: number, param_x: number, param_category_group_code: string, kakaoApikey: string) => Promise<any>;
}

export { BudongsanAPIClass, BudongsanUtil, SigunguService, SigunguServiceClass };