Company Lens API

GET/api/v1/compare

2~3개 사업장 비교

각 사업장 최신 기준월을 그대로 반환합니다. sameSnapshotMonth=false이면 같은 시점의 비교가 아닙니다. ID 하나라도 존재하지 않으면 전체 요청이 404입니다.

GET/api/v1/companies/{id}/insights

고용 요약, 업종 중간값과 명칭 관측

1년/3년 전 같은 달 대비 증감, 최근 12개월 취득·상실 합계, 최신 13개월 안의 연속 변화와 업종·규모 중간값을 반환합니다. 유사 이름은 동일 법인이나 계열사로 확인된 관계가 아닙니다. 명칭은 기능 도입 이후 관측값이며 과거 명칭을 복원하지 않습니다. 업종/규모 표본 30 미만 또는 과거월 사업장은 industry/sizeCohort=null입니다. 규모는 최신 가입자 기준 고정 구간이며 기업 규모 법적 분류가 아닙니다.

GET/api/v1/companies

회사 검색

명시적 일용 표기 사업장은 인원수와 관계없이 적재에서 제외합니다. 기존 일용 사업장과 이력을 정리하면 해당 ID의 상세·이력은 404입니다. 일용상사 등 일반 회사명은 유지합니다. 유효한 관측 월이 한 달뿐이고 0명이면 검색에서 기준월과 관계없이 제외합니다. 대체된 원본 버전은 별도 관측으로 세지 않습니다. 필터 적용 전 이름/번호 후보가 20,000개를 넘으면 400 INVALID_REQUEST를 반환합니다. 회사명이나 번호를 더 구체적으로 입력하세요. 회사명 또는 공개된 사업자등록번호 부분 검색. 최신 적재 기준월보다 12개월 이상 오래됐고 마지막 가입자가 0명인 기록은 제외합니다. 직접 상세·이력은 유지하며 폐업 판정은 아닙니다. q는 trim 후 2~100자이며 글자/숫자를 포함해야 합니다. %, _, 제어문자는 금지합니다. 번호 검색은 공백/하이픈 제거 후에도 2자리 이상이어야 합니다. 두 글자는 보조 bigram FTS와 부분 일치 검증을, 세 글자 이상은 trigram FTS를 사용합니다. 보조 인덱스가 없으면 부분 검색으로 대체합니다. 전체 사업자번호를 공개된 앞자리로 자동 축약하지 않습니다. 지역·가입자 규모 필터 후 전체 건수(totalCount)와 전체 페이지 수(totalPages)를 집계하고 정렬·페이지 이동을 적용합니다. 동일 조건과 limit을 유지하세요. 결과가 없으면 totalPages=0이며 유효하지만 범위를 벗어난 page는 빈 목록을 반환합니다. 최대 요청 페이지는 1000이며 totalPages가 이를 넘어도 이 상한은 유지됩니다. 지역은 대표 주소 기준이며 강원도·전라북도 표기도 포함합니다.

GET/api/v1/companies/{id}

최신 회사 지표

전월 비교는 바로 이전 달 데이터가 있을 때만 제공합니다. 연봉 변화율은 이전 값이 0이면 null. 상위 백분율은 최신 통계월의 가입 중인 유효 사업장에만 있으며 과거월 회사는 benchmark=null입니다. 비교 표본은 법인이 아닌 사업장입니다.

GET/api/v1/companies/{id}/history

월별 회사 이력

기준월 오름차순, 범위 양끝 포함. 누락된 달은 생성하지 않습니다. 기본/최대 240개. hasMore=true이면 마지막 반환 기준월의 다음 달을 from으로 지정하여 이어서 조회하세요. 범위 내 이력이 없어도 존재하는 회사면 빈 배열과 200입니다.

GET/api/v1/status

최신 적재 정보

호출 예제

curl -G "$COMPANY_LENS_URL/api/v1/companies" \
  --data-urlencode "q=삼성전자" --data "limit=5"

curl "$COMPANY_LENS_URL/api/v1/companies/177744"

curl "$COMPANY_LENS_URL/api/v1/companies/177744/history?from=2025-01&to=2026-08"

COMPANY_LENS_URL은 접속 중인 서비스의 주소입니다. 검색은 2~100자, 최대 20개(기본 5개), 이력은 최대 240개입니다.

기본 검색은 최신 적재월의 사업장만 반환합니다. 과거 기록은 includeHistory=true로 포함하며, 최신 자료에 없다는 것이 폐업을 뜻하지는 않습니다.

지역·최소 가입자 수·정렬·과거 포함 조건을 유지한 채 page를 증가시켜 조회합니다. totalCount와 totalPages는 필터 적용 후 전체 건수와 페이지 수이며, hasMore는 다음 결과 여부입니다. 조건 변경 시 첫 페이지로 돌아가세요.

오류와 연동

400: 입력 오류 · 404: 회사 없음 · 500: 조회 실패. 중복되거나 지원하지 않는 쿼리 매개변수도 400입니다.

서버 간 호출용이며 별도 CORS 허용은 없습니다. 성공 데이터는 60초 캐시 가능하고 오류는 캐시하지 않습니다. 카카오톡 응답에도 기준월·추정치 안내를 함께 표시하세요.