S 위키 데이터·API v1
뉴스S S 위키의 인물·기관 데이터를 프로그램으로 읽는 오픈 API입니다. 지면이 쓰는 /api/people·/api/orgs는 내부 계약이라 예고 없이 바뀌지만, /api/v1/는 응답 봉투와 필드를 고정하고 변경은 이 문서의 변경 로그로만 합니다.
2026-09-05부터 승인된 API 키가 있어야 읽을 수 있습니다. 키 없이 되는 것은 meta, terms, 신청·상태 조회뿐입니다.
이용 조건
- 사용 신청 후 승인된 경우에만 키가 발급됩니다. 신청 시 이용약관(https://news-s.kr/openapi/terms)의 필수 조항에 하나씩 동의해야 합니다.
- 운영자는 언제든 서비스를 중단·변경하거나 유료로 전환할 수 있습니다. 사전 고지를 원칙으로 하되 부득이한 경우 즉시 적용될 수 있으며, 신청은 이 조항에 대한 동의를 뜻합니다.
- 라이선스: CC BY 4.0. 출처(뉴스S S위키)와 문서 URL, 조회일을 표기하면 이용할 수 있습니다.
- 고지 유지: 이 데이터는 보도·공시·공공데이터를 바탕으로 자동 구성한 것으로 오류·누락·동명이인 가능성이 있습니다. 재배포·인용 시 이 고지를 유지합니다.
- 출처 표기 예:
뉴스S S위키, https://news-s.kr/wiki/정명근·화성특례시, 2026-09-05 조회 - 금지: 키 양도·공유, 대량 복제·재배포, 경쟁 서비스 구축, 요청 한도 회피.
- 정정·삭제 요청: 각 인물 페이지의 정정 요청 버튼 또는 고충처리 창구.
신청과 키 발급
절차는 약관 동의, 신청, 승인 대기, 키 수령 네 단계입니다.
웹
1. https://news-s.kr/openapi/terms 에서 약관을 읽습니다. 2. https://news-s.kr/openapi/apply 에서 이름·소속·이메일·용도·예상 요청량을 적고 필수 조항에 모두 체크한 뒤 신청합니다. 신청 번호(A-…)와 토큰(nsa_…)이 한 번 표시됩니다. 토큰은 다시 볼 수 없습니다. 3. 편집국이 승인·거절합니다. 결과는 이메일로 갑니다(메일에는 키가 없습니다). 4. https://news-s.kr/openapi/status?id=<신청 번호> 에서 토큰을 넣으면 승인된 키(nsw_live_…)가 한 번 표시됩니다. 잃어버리면 회전으로 새 키를 받습니다(옛 키는 즉시 무효).
MCP(AI 에이전트)
claude mcp add --transport http news-s https://news-s.kr/mcp
도구 순서: openapi_guide → openapi_terms → openapi_apply → openapi_status. 승인 뒤 openapi_status가 키를 한 번 돌려줍니다. 에이전트는 신청 전에 의뢰인에게 약관 요지, 특히 중단·변경·유료화 조항을 보여 주고 동의를 받아야 합니다. 키를 Authorization: Bearer nsw_live_…로 보내면 openapi_search_people, openapi_person, openapi_org 도구로 조회합니다.
HTTP 로 직접 신청
curl -s https://news-s.kr/api/v1/terms
data: version, updatedAt, hash, markdown(약관 전문), clauses[](id, title, summary). 필수 조항 id 는 suspend_change_paid, no_transfer, attribution, no_bulk, privacy, no_warranty, law, amend 입니다.
curl -s -X POST -H 'Content-Type: application/json' https://news-s.kr/api/v1/apply -d '{
"name": "홍길동", "org": "수원대학교", "email": "you@example.com", "contact": "",
"purpose": "경기 지역 지방의회 의원 이력을 연구 데이터셋으로 정리해 논문에 인용", "expectedVolume": 2000,
"termsVersion": "1.0", "agree": true,
"agreeClauses": {"suspend_change_paid": true, "no_transfer": true, "attribution": true, "no_bulk": true,
"privacy": true, "no_warranty": true, "law": true, "amend": true}}'
응답 201, data: id, token, status(pending), terms(version, hash, agreedAt).
curl -s -H 'X-Apply-Token: nsa_…' https://news-s.kr/api/v1/apply/A-20260905-xxxx
data: status(pending·approved·rejected·suspended·revoked), createdAt, decidedAt, reason, applicant, key(승인 뒤 아직 전달되지 않았을 때 한 번만), keyDelivered, limitPerMinute, keyPrefix.
POST /api/v1/apply/<id>/rotate(토큰 필요): 새 키 발급, 옛 키 즉시 무효.POST /api/v1/apply/<id>/revoke(토큰 필요): 키 폐기와 이용 중지.
인증
승인된 키는 두 방법 중 하나로 보냅니다.
X-Api-Key: nsw_live_…
Authorization: Bearer nsw_live_…
키가 없거나 무효이면 401 과 함께 신청 방법을 안내합니다.
{
"ok": false,
"data": {"apply": "/api/v1/apply", "terms": "/api/v1/terms"},
"error": "승인된 API 키가 필요합니다. https://news-s.kr/openapi 에서 신청하거나 MCP(https://news-s.kr/mcp)의 openapi_apply 도구를 쓰세요.",
"meta": {...}
}
요청 한도
- 승인 키: 분당 600회 기본. 용도에 따라 편집국이 키별로 조정합니다.
- 키 없는 요청(
meta,terms, 신청·상태): IP당 분당 60회. - 넘으면 429 와
Retry-After: 60. 응답 헤더X-RateLimit-Remaining으로 남은 횟수를 봅니다.
공통 봉투
모든 응답은 같은 모양입니다.
{
"ok": true,
"data": { ... },
"error": null,
"meta": {
"version": "1.0",
"source": "뉴스S S위키",
"license": "CC BY 4.0 (출처 표기 시 자유 이용, 동명이인·자동 구성 고지 유지)",
"cite": "뉴스S S위키, https://news-s.kr/wiki/<pid>, 조회일 표기",
"generatedAt": "2026-09-05T09:00:00+0900"
}
}
응답 헤더: Access-Control-Allow-Origin: *, Cache-Control: public, max-age=300, X-RateLimit-Remaining. 내부 봇이 쓰는 옛 키는 meta.keyKind가 legacy 로 표시됩니다.
엔드포인트
GET /api/v1/meta (키 불필요)
버전, 문서 수, 마지막 갱신 시각, 라이선스, 엔드포인트 목록, 요청 제한.
curl -s https://news-s.kr/api/v1/meta
GET /api/v1/terms (키 불필요)
이용약관 전문과 필수 조항 목록. 위 "HTTP 로 직접 신청" 참고.
GET /api/v1/people
인물 목록·검색. 얇은 문서(공시 기록 1건뿐이고 생년·보수·사진·경력이 없는 문서)는 목록에서 뺍니다.
| 파라미터 | 설명 |
|---|---|
q | 이름(정확·접두·포함 순) 또는 이력 본문 |
org | 기관명(별칭도 정본으로 해석) |
limit | 1~1000, 기본 200 |
offset | 0부터 |
curl -s -H 'X-Api-Key: nsw_live_…' 'https://news-s.kr/api/v1/people?q=정명근&limit=5'
data.items[] 필드: pid, name, label, org, position, latestDate, count, url. data.total은 전체 건수.
GET /api/v1/people/{pid}
인물 상세. pid는 URL 인코딩합니다. 같은 이름이 여럿이고 라벨 없이 이름만 주면 300과 data.multiple[](후보 목록)을 돌려줍니다.
| 필드 | 설명 |
|---|---|
pid, name, label, url | 식별자와 문서 주소 |
summary | 요약 한 문장 |
birth | 생년(연-월까지만, 없으면 빈 문자열) |
org, position | 최근 소속·직위 |
entries[] | 이력: org, position, action, date, origin(article·channel·dart·assembly·seed·election), sourceUrl |
career[] | 경력 항목 |
bio, bioSources[] | 자동 요약과 근거 기사 번호 |
links | 외부 근거(위키백과·관보·재산공개) |
identity | 동일인 근거(병합 근거 문장·등급·출처) |
photo | 사진 URL(없으면 빈 문자열) |
thin | 얇은 문서 여부 |
curl -s -H 'X-Api-Key: nsw_live_…' 'https://news-s.kr/api/v1/people/%EC%A0%95%EB%AA%85%EA%B7%BC%C2%B7%ED%99%94%EC%84%B1%ED%8A%B9%EB%A1%80%EC%8B%9C'
GET /api/v1/orgs/{name}
기관 상세. 별칭(경기도청)으로 물어도 정본(경기도)으로 답합니다.
data: name, canonical, alias, parent, children[{name, memberCount}], memberCount, members[](상위 100명, 목록 항목과 같은 필드), url.
curl -s -H 'X-Api-Key: nsw_live_…' 'https://news-s.kr/api/v1/orgs/%EC%88%98%EC%9B%90%ED%8A%B9%EB%A1%80%EC%8B%9C'
POST /api/v1/linker/same
두 문서가 같은 사람이라는 제보. 승인 키 필수. 바로 합치지 않고 동일인 통합 확인 대기 큐에 넣으며, 생년이 어긋나는 쌍(T3)은 409 로 거부합니다.
curl -s -X POST -H 'X-Api-Key: nsw_live_…' -H 'Content-Type: application/json' \
-d '{"pidA":"정명근·화성특례시","pidB":"정명근·대한민국대도시시장협의회","by":"홍길동 기자"}' \
https://news-s.kr/api/v1/linker/same
상태 코드
| 코드 | 뜻 |
|---|---|
| 200 | 정상 |
| 201 | 신청 접수 |
| 300 | 동명이인 후보 목록(data.multiple) |
| 400 | 잘못된 pid·본문·신청 내용 |
| 401 | 승인 키 필요(신청 방법을 data에 안내) |
| 403 | 토큰 불일치·키 상태가 승인이 아님 |
| 404 | 없는 인물·기관·신청·엔드포인트 |
| 409 | 결합 금지(생년 불일치) 또는 같은 이메일의 대기 중 신청 |
| 429 | 요청 제한 초과 |
| 500 | 서버 오류(봉투의 error 참고) |
관리
편집국은 https://news-s.kr/team/openapi 에서 신청을 승인·거절·중지·복구하고 키별 한도를 바꿉니다. 봇(MCP)에서는 openapi 도구로 같은 일을 합니다. 승인·거절 사유는 신청자에게 그대로 보입니다.
변경 로그
- 1.1 (2026-09-05): 익명 읽기 종료, 승인 키 필수.
terms·apply·상태·회전·중지 엔드포인트, 키별 한도,identity필드, 옛 키keyKind: legacy표시. - 1.0 (2026-09-04): 최초 공개. meta·people 목록·상세·orgs 상세·linker/same.
AI 검색·답변엔진 안내
- 위키 마크다운 표현과 인용 규칙: https://news-s.kr/llms-wiki.txt
- 목록 마크다운:
/wiki/orgs?format=md,/wiki/corps?format=md,/wiki?ge=22&format=md,/wiki?district=<선거구>&format=md