{"openapi":"3.0.3","info":{"title":"APICK 주소록 중복·권역 정비","version":"1.0.0","description":"여러 표기로 흩어진 주소 목록을 같은 지점끼리 묶어 실제 지점 수·중복률·시군구·읍면동 분포를 계산하고, 찾지 못한 주소에는 대안을 붙입니다. 고객·매장 주소록을 지점 기준으로 정리할 때 씁니다."},"servers":[{"url":"https://apick.app"}],"paths":{"/rest/geo_address_cleanup":{"post":{"summary":"주소록 중복·권역 정비","description":"여러 표기로 흩어진 주소 목록을 같은 지점끼리 묶어 실제 지점 수·중복률·시군구·읍면동 분포를 계산하고, 찾지 못한 주소에는 대안을 붙입니다. 고객·매장 주소록을 지점 기준으로 정리할 때 씁니다.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"서비스별 성공·처리 상태 응답","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"summary":{"type":"object","properties":{"requested":{"type":"integer","description":"입력한 주소 수입니다."},"unique":{"type":"integer","description":"같은 문자열을 합친 뒤 확인한 주소 수입니다."},"matched":{"type":"integer","description":"찾은 고유 주소 수입니다."},"unmatched":{"type":"integer","description":"찾지 못한 고유 주소 수입니다."},"sites":{"type":"integer","description":"같은 지점끼리 묶은 실제 지점 수입니다."},"duplicateGroups":{"type":"integer","description":"입력이 2건 이상인 지점 수입니다."},"mergedInputs":{"type":"integer","description":"같은 지점으로 합쳐진 입력 수입니다."},"duplicateRatePct":{"type":"integer","description":"찾은 입력 중 합쳐진 비율(%)입니다."},"districts":{"type":"integer","description":"시군구·읍면동 묶음 수입니다."},"partial":{"type":"boolean","description":"시간 초과로 일부를 확인하지 못했으면 true입니다."},"elapsedMs":{"type":"integer"}}},"districts":{"type":"array","items":{"type":"object","properties":{"sigungu":{"type":"string","description":"시군구입니다."},"eupmyeondong":{"type":"string","description":"읍면동입니다."},"adminDong":{"type":"string"},"sites":{"type":"integer","description":"이 권역의 지점 수입니다."},"members":{"type":"integer","description":"이 권역의 입력 수입니다."}}}},"sites":{"type":"array","items":{"type":"object","properties":{"siteId":{"type":"integer","description":"1부터 붙인 지점 번호입니다. 입력이 많은 지점부터 정렬됩니다."},"address":{"type":"string","description":"대표 주소입니다. 도로명 주소가 있는 입력을 우선합니다."},"roadAddress":{"type":"string","description":"대표 도로명 주소입니다. 없으면 빈 문자열입니다."},"jibunAddress":{"type":"string","description":"대표 지번 주소입니다."},"sigungu":{"type":"string"},"eupmyeondong":{"type":"string"},"adminDong":{"type":"string"},"codes":{"type":"object","properties":{"pnu":{"type":"string"},"bjdongCode":{"type":"string"},"lawdCd":{"type":"string"},"adminDongCode":{"type":"string"},"sidoCode":{"type":"string"},"sigunguCode":{"type":"string"}},"description":"대표 주소의 코드입니다. 항목 구성은 주소 표준화 API의 codes와 같습니다."},"point":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"},"crs":{"type":"string"}},"description":"대표 주소의 좌표입니다."},"memberCount":{"type":"integer","description":"이 지점으로 묶인 입력 수입니다."},"variants":{"type":"array","items":{"type":"string"},"description":"이 지점을 가리킨 서로 다른 표기입니다."},"indexes":{"type":"array","items":{"type":"integer"},"description":"입력 목록에서의 위치(0부터)입니다."}}}},"unmatched":{"type":"array","items":{"type":"object","properties":{"input":{"type":"string","description":"찾지 못한 입력입니다."},"error":{"type":"string","description":"찾지 못한 이유입니다."},"suggestions":{"type":"array","items":{},"description":"대안 후보(최대 3건)입니다. 후보가 없으면 빈 배열입니다."}}}}}},"api":{"type":"object","properties":{"cost":{"type":"integer","description":"차감된 포인트입니다. 실패한 응답은 0입니다."},"success":{"type":"boolean"},"ms":{"type":"integer","description":"처리 시간(밀리초)입니다."}}}}}}}},"default":{"description":"HTTP 상태 및 서비스 오류코드 확인","content":{"application/json":{"schema":{"type":"object"}}}}},"requestBody":{"required":false,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"addrType":{"type":"string","description":"주소 유형. 기본 auto 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. 가능한 값은 3가지입니다. auto = 서버·모델이 상황에 맞춰 자동으로 정하는 값입니다. 별도 지정이 필요 없습니다. parcel = 지번 주소를 기준으로 조회하는 값입니다. road = 도로명 주소를 기준으로 조회하는 값입니다. (string)","enum":["auto","parcel","road"]},"includeSuggestions":{"type":"string","description":"찾지 못한 주소의 대안 후보 포함 여부 (기본 true, 최대 10건 조회) true = 이 필드가 나타내는 조건이 성립한 경우, false = 성립하지 않은 경우입니다. 두 값 모두 정상 응답에 올 수 있으며, 값이 없으면 필드가 생략되거나 null일 수 있습니다. (boolean)"}}}}}}}}},"x-code-tables":[{"title":"addrType 허용값","columns":["값","의미"],"rows":[["auto","지번·도로명을 알아서 판단합니다 (기본값)."],["parcel (또는 jibun·지번)","지번 주소로만 찾습니다."],["road (또는 도로명)","도로명 주소로만 찾습니다."]]},{"title":"오류와 복구","columns":["상황","HTTP","data.error","해결"],"rows":[["주소 목록 누락","400","주소 목록이 필요합니다.","addresses에 주소를 한 건 이상 넣습니다."],["주소 수 초과","400","한 요청에 주소를 50개까지 정리할 수 있습니다.","50건씩 나눠 요청합니다."],["addrType 값 오류","400","주소 유형이 잘못됐습니다.","auto·parcel·road 중 하나로 보내거나 생략합니다."],["모든 주소를 찾지 못함","404","입력한 위치를 찾지 못했습니다.","주소 표기를 확인합니다. 한 건이라도 찾으면 성공 응답의 unmatched로 옵니다."],["모든 주소가 시간 초과","424","처리 시간이 초과됐습니다. 범위를 줄여 다시 시도해 주세요.","건수를 줄여 다시 요청합니다."],["일시적 조회 실패","424","공간정보를 일시적으로 가져오지 못했습니다. 잠시 후 다시 시도해 주세요.","잠시 후 같은 요청을 다시 보냅니다."]]}],"x-service-errors":[],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}}}