kstartup-search

name	kstartup-search
description	공공데이터포털 창업진흥원 K-Startup Open API(15125364)로 통합 공고 사업 정보·지원사업 공고·창업 콘텐츠·통계보고서를 k-skill-proxy 경유로 조회한다. 검색 전용.
license	MIT
metadata	{"category":"business","locale":"ko-KR","phase":"v1"}

창업진흥원 K-Startup 조회

What this skill does

공공데이터포털의 창업진흥원_K-Startup(사업소개,사업공고,콘텐츠 등)_조회서비스 (kisedKstartupService01, dataset 15125364)를 k-skill-proxy 경유로 호출해 다음 4개 endpoint를 조회한다.

• business-info → getBusinessInformation01 : 통합공고 지원사업 정보 (예산, 규모, 수행기관, 사업소개)
• announcements → getAnnouncementInformation01 : 지원사업 공고 정보 (공고명, 접수기간, 지역, 신청대상, 모집진행여부 등 — 가장 활용도 높음)
• contents → getContentInformation01 : 창업관련 콘텐츠 (공지·뉴스·우수사례 등)
• statistics → getStatisticalInformation01 : 창업관련 통계보고서

조회 전용 스킬이다. 사업 신청·지원금 청구·콘텐츠 게시 같은 쓰기 동작은 다루지 않는다.

When to use

• "이번 달 마감 예정인 청년 창업지원 공고 찾아줘"
• "서울 소재 모집 진행 중인 1인 창조기업 지원사업 알려줘"
• "K-Startup에서 사업화 단계 통합공고 사업 목록 뽑아줘"
• "창업진흥원 최신 통계보고서 5건 보여줘"

When not to use

• 사업 신청·결제·자동 지원·계좌 연계 같은 쓰기 동작 (지원 화면은 사용자가 K-Startup 웹에서 직접 진행한다)
• K-Startup 외부 사이트(중기부, 창조경제혁신센터, 지자체 단독 공고) 조회 — 통합공고에 등록된 일부만 K-Startup API로 노출된다
• 마감일·모집 상태를 분 단위로 추적해야 하는 작업 — 데이터 갱신은 공식 서비스설계서 기준 일 1회다 (공공데이터포털 dataset 메타데이터에는 "실시간"으로 표기되지만 두 표면이 일치하지 않는다)

Prerequisites

• 인터넷 연결
• python3 (stdlib only)
• 설치된 스킬 안의 scripts/run_kstartup.py
• hosted/self-host k-skill-proxy의 /v1/kstartup/* 라우트 접근 가능 (4개)

Credential requirements

• 사용자 측 필수 시크릿 없음.
• KSKILL_PROXY_BASE_URL — self-host·별도 프록시를 쓸 때만 설정. 비우면 기본 hosted https://k-skill-proxy.nomadamas.org.
• KSKILL_KSTARTUP_API_KEY — --direct로 K-Startup을 직접 호출할 때만 필요. 공공데이터포털에서 창업진흥원_K-Startup(사업소개,사업공고, 콘텐츠 등)_조회서비스 (15125364) 활용신청이 본인 계정으로 승인돼 있어야 한다(자동승인, 무료).
• 프록시 운영자는 DATA_GO_KR_API_KEY 환경변수에 같은 조건의 키를 두고 활용신청을 추가해 둔다.

Credential resolution order (--direct 전용)

1. 이미 환경변수에 있으면 그대로 사용한다.
2. 에이전트 vault(1Password CLI, Bitwarden CLI, macOS Keychain 등)에서 꺼내 환경변수로 주입.
3. ~/.config/k-skill/secrets.env (plain dotenv, 권한 0600).
4. 아무것도 없으면 사용자에게 묻고 2 또는 3에 저장.

일반 조회 helper는 proxy URL만 읽고, K-Startup 인증키는 프록시 서버에서만 주입한다. --direct 호출에서만 KSKILL_KSTARTUP_API_KEY를 읽는다.

Inputs

서브커맨드: business-info, announcements, contents, statistics.

공통 옵션:

• --page N (기본 1, ≥ 1)
• --per-page N (기본 10, 1–100)
• --text 사람용 요약 / --json 구조화 결과(기본)
• --dry-run 인증키 없이 요청 URL/파라미터만 출력
• --timeout N HTTP 타임아웃 초 (기본 30)
• --proxy-base-url URL 기본 hosted proxy 대신 self-host/alternate proxy
• --direct proxy 우회, KSKILL_KSTARTUP_API_KEY로 직접 호출

서브커맨드별 필터:

• business-info
  • --biz-yr 2024 (사업 연도, 4자리)
  • --biz-category-cd cmrczn_Tab3 (사업 구분 코드)
  • --supt-biz-titl-nm "1인 창조기업" (사업 명)
• announcements
  • --biz-pbanc-nm "키워드" (지원 사업 공고 명)
  • --supt-regin 서울특별시 (지역명. K-Startup upstream이 이 필터를 서버 측에서 적용하지 않는 사례가 있다 — 응답을 받은 뒤 client에서 supt_regin 으로 한 번 더 거른다)
  • --supt-biz-clsfc 사업화 (지원 분야)
  • --pbanc-rcpt-bgng-dt 20240101 / --pbanc-rcpt-end-dt 20241231 (공고 접수 시작/종료, YYYYMMDD)
  • --aply-trgt 일반인,예비창업자 (신청 대상)
  • --biz-enyy 예비창업자,1년미만 (창업 기간)
  • --biz-trgt-age "만 20세 이상 ~ 만 39세 이하" (대상 연령)
  • --rcrt-prgs-yn Y|N (모집진행여부)
  • --intg-pbanc-yn Y|N (통합 공고 여부)
• contents
  • --clss-cd notice_matr (콘텐츠 구분 코드: notice_matr 등)
  • --titl-nm "공모전" (제목 키워드)
• statistics
  • --titl-nm "창업기업 실태조사" (통계 자료 명)
  • --file-nm "PDF" (파일 명/내용 키워드)

Workflow

1. Ensure proxy access is available

일반 조회는 기본 hosted k-skill-proxy를 사용하므로 사용자 K-Startup 키가 필요 없다. self-host를 쓰면 KSKILL_PROXY_BASE_URL을 설정한다. --direct가 필요할 때만 KSKILL_KSTARTUP_API_KEY를 credential resolution order에 따라 확보한다.

2. Pick the right operation

• 마감 임박/지역 필터/대상별 공고 추천 → announcements
• 사업의 전반적 소개·예산 규모 → business-info
• 정책 공지·우수사례 → contents
• 보고서/통계 데이터 → statistics

3. Fetch a small bounded slice first

--per-page 10 정도로 먼저 한 페이지를 받아 응답 스키마를 확인한 뒤, 필터를 좁히거나 페이지를 넘긴다.

python3 scripts/run_kstartup.py announcements \
  --supt-regin 서울특별시 --rcrt-prgs-yn Y --per-page 5 --text

4. Filter on the client side for richer questions

API는 단순 필드 매칭만 지원하고, 그중 supt_regin 같은 일부 필터는 upstream이 서버 측에서 적용하지 않는 사례가 관측된다. --supt-regin 서울특별시로 호출해도 타 지역 공고가 섞여 돌아오는 경우가 있어서, supt_regin·aply_trgt·biz_enyy 필드는 helper가 받은 응답을 client에서 한 번 더 거른다.

• 응답 supt_regin은 upstream이 축약형(서울, 경기, 충북)으로 돌려준다. helper는 사용자가 --supt-regin 서울특별시 같은 표준 광역지자체명을 줘도 17개 광역시·도(+ 전국) 매핑 테이블로 자동 정규화해 매치한다.
• client filter가 적용되면 응답 JSON에 client_filter: {fields, upstream_returned, after_filter} 블록이 함께 붙는다. upstream_returned는 같지만 after_filter가 작으면 첫 페이지로는 부족하니 --page를 늘려 추가 페이지를 받는다.
• 쉼표로 여러 값을 주면 AND 매치다 (--aply-trgt 예비창업자,1년미만 → 두 토큰 모두 row에 있어야 통과).
• pbanc_rcpt_end_dt는 YYYYMMDD 문자열이라 KST 기준으로 직접 비교한다. "이번 주 마감", "30대 대상", "특정 키워드 포함" 같은 복합 조건은 helper가 안 거르므로 응답 JSON에서 agent가 직접 처리한다.

5. Cite the source

응답을 요약할 때는 endpoint 이름, 호출 page/perPage, 응답의 pbanc_sn 또는 detl_pg_url을 함께 적는다. 상세는 https://www.k-startup.go.kr 의 해당 URL로 안내한다.

CLI examples

# 서울 모집 중 공고 5건
python3 scripts/run_kstartup.py announcements \
  --supt-regin 서울특별시 --rcrt-prgs-yn Y --per-page 5 --text

# 2024년 사업화 분야 통합공고
python3 scripts/run_kstartup.py business-info \
  --biz-yr 2024 --biz-category-cd cmrczn_Tab3 --json

# 정책·공지 최신 콘텐츠
python3 scripts/run_kstartup.py contents \
  --clss-cd notice_matr --per-page 10 --text

# 창업기업 실태조사 통계보고서
python3 scripts/run_kstartup.py statistics \
  --titl-nm "창업기업 실태조사" --per-page 5 --json

# 인증키 없이 dry-run 으로 요청 점검
python3 scripts/run_kstartup.py announcements \
  --supt-regin 부산광역시 --dry-run

Direct proxy examples

curl -fsS "$KSKILL_PROXY_BASE_URL/v1/kstartup/announcements?supt_regin=$(python3 -c 'import urllib.parse;print(urllib.parse.quote(\"서울특별시\"))')&rcrt_prgs_yn=Y&perPage=5"

Failure modes

• 400 bad_request: 잘못된 날짜(YYYYMMDD 아님), 잘못된 Y/N, perPage 범위 초과, 시작일 > 종료일 → 메시지대로 입력 보정.
• 503 upstream_not_configured: 프록시 서버에 DATA_GO_KR_API_KEY가 없거나 해당 데이터셋 활용신청이 미승인.
• 502 upstream_error: data.go.kr 응답이 resultCode != "00" 또는 errMsg/SERVICE_KEY_IS_NOT_REGISTERED_ERROR 등 인증/한도 오류.
  • data.go.kr 에러 코드: 10(잘못된 파라미터), 20(접근거부), 22(요청제한 초과), 30(미등록 키), 31(만료), 32(미등록 IP).
• 502 upstream_invalid_response: data.go.kr이 JSON 대신 HTML/XML 본문을 보낸 경우(점검·차단 등). upstream_body 앞 500자가 함께 반환된다.
• 빈 data 배열: 필터에 일치하는 공고/콘텐츠 없음. 키워드/지역/대상 범위를 완화한다.
• 일 갱신 1회(서비스설계서 기준): 같은 날 같은 공고의 마감일·상태가 갱신되지 않을 수 있으므로, 마감/접수 상태는 응답의 detl_pg_url 페이지에서 최종 확인한다.

Done when

• 사용자가 찾는 endpoint (business-info / announcements / contents / statistics)를 골랐다.
• 작은 슬라이스로 첫 페이지를 받아 응답 스키마/필드를 확인했다.
• 필터를 좁히거나 클라이언트에서 후처리해 답변에 필요한 핵심 행만 남겼다.
• 결과에 출처(endpoint, page/perPage, detl_pg_url 또는 pbanc_sn)를 명시했다.

Maintainer review notes

K-Startup 인증키 없이도 다음 검증이 가능하다.

• ./scripts/validate-skills.sh
• python3 -m py_compile kstartup-search/scripts/run_kstartup.py kstartup-search/tests/test_run_kstartup.py
• python3 kstartup-search/scripts/run_kstartup.py --help
• python3 kstartup-search/scripts/run_kstartup.py announcements --supt-regin 서울특별시 --dry-run
• PYTHONPATH=kstartup-search/scripts python3 -m unittest discover -s kstartup-search/tests -p 'test_*.py' -v
• node --test packages/k-skill-proxy/test/server.test.js (K-Startup 라우트 5개 신규 케이스 포함)
• npm run ci

라이브 스모크는 hosted proxy 환경에 DATA_GO_KR_API_KEY 가 설정되고 15125364 활용신청이 승인된 뒤에 수행한다.

Safety notes

• 조회 전용 스킬. 사업 신청·계좌 연결·결제 자동화는 하지 않는다.
• 응답에 K-Startup 사이트 URL이 있으면 그대로 안내하고, 실제 신청은 사용자가 브라우저에서 직접 진행한다.
• 인증키는 프록시 서버에서만 다루며, --dry-run 시에도 helper는 <DRY-RUN>로 대체한다.