역대인물 OpenAPI
1. 역대인물 OpenAPI 소개
한국학중앙연구원은 인물정보를 자유롭게 이용할 수 있도록 OpenAPI로 제공합니다. OpenAPI 이용을 위해서는 먼저 사용신청을 해야 합니다. 신청이 완료되면 담당자 검토 후 이메일로 인증키를 발송해 드립니다.
2. OpenAPI 이용 가이드
(1) 요청 주소
인증키를 이용하여 아래와 같은 형식으로 서비스를 호출할 수 있습니다.
요청 URL : http://people.aks.ac.kr/openapi
http://people.aks.ac.kr/openapi?key={인증키}&query={검색어}&category={검색 범위}&startPage={시작 페이지}&pageSize={페이지 크기}&startHilightTag={하이라이트 시작 태그}&endHilightTag={하이라이트 종료 태그}&format={출력 형식}
요청 URL 예시
역대인물 OpenAPI의 요청 파라메터는 UTF-8 인코딩을 사용해야 합니다.
역대인물 OpenAPI의 요청 파라메터는 UTF-8 인코딩을 사용해야 합니다.
http://people.aks.ac.kr/openapi?key=857f940ccd144a87ba118e0d4499e331&query=이순신&category=total&startPage=1&pageSize=50&startHilightTag=<b>&endHilightTag=</b>&format=xml
위와 같이 역대인물 OpenAPI를 요청 예를 UTF-8 URL로 인코딩하면 아래와 같습니다.
http://people.aks.ac.kr/openapi?key=857f940ccd144a87ba118e0d4499e331&query=%ec%9d%b4%ec%88%9c%ec%8b%a0&category=total&startPage=1&pageSize=50&startHilightTag=%3cb%3e&endHilightTag=%3c%2fb%3e&format=xml
(2) 요청 파라메터
| 요청변수 | 값 | 설명 |
|---|---|---|
| key | string (필수) | Open-API 서비스 신청시 발급받은 인증키를 입력합니다. |
| query | string (필수) | 검색할 질의어를 입력합니다. UTF-8 인코딩이 필요합니다. |
| category (query의 속성) | string (선택) | 검색할 범위를 지정합니다.
|
| startHilightTag | string (선택) | 검색어에 대한 하이라이트 시작 태그로 XML형식인 경우만 지원합니다. |
| endHilightTag | string (선택) | 검색어에 대한 하이라이트 종료 태그로 XML형식인 경우만 지원합니다. |
| startPage | Int (선택) | 검색된 결과의 시작 페이지 (default : 1) |
| pageSize | Int (선택) | 검색된 결과 페이지 크기 (default : 20) |
| format | String(선택) | Xml 또는 JSON (default xml) |
(3) 검색 결과
| 변수 | 타입 | 설명 | |||
|---|---|---|---|---|---|
| referUrl | string | OpenAPI 호출자 URL | |||
| conditions | query | string | 검색어 | ||
| category | string | 검색 범위 | |||
| startPage | int | 시작 페이지 | |||
| pageSize | int | 페이지 크기 | |||
| startHilightTag | string | 하이라이트 시작 태그 | |||
| endHilightTag | string | 하이라이트 종료 태그 | |||
| format | string | 출력형식(xml 또는 json) | |||
| resultInfo | success | string | 검색 오류 여부(성공:true, 실패:false) | ||
| message | string | 오류 메세지 | |||
| totalCount | int | 검색 결과 건수 | |||
| resultSize | int | 검색 결과 목록 갯수 | |||
| resultSet | list | total_no | int | 전체 검색 결과에서의 순번 | |
| no | int | 결과 목록에서의 순번 | |||
| pplid | string | 역대인물 고유 아이디 | |||
| uci | string | 역대인물 UCI | |||
| title | string | 자료명(대표 인물명) | |||
| document | string | 역대인물 상세 메타데이터 정보 역대인물 통합인명메타 DTD 참조 | |||
출력예시
<?xml version="1.0" encoding="UTF-8"?>
<aksPeopleAPI>
<referUrl>http://localhost:8080/openapi/testClient1.jsp</referUrl>
<conditions>
<query><![CDATA[세종]]></query>
<category>name_eq</category>
<startPage>1</startPage>
<pageSize>50</pageSize>
<startHilightTag><![CDATA[]]></startHilightTag>
<endHilightTag><![CDATA[]]></endHilightTag>
<format>xml</format>
</conditions>
<resultInfo>
<success>true</success>
<message><![CDATA[]]></message>
<totalCount>1</totalCount>
<resultSize>1</resultSize>
<resultSet>
<list>
<total_no>1</total_no>
<no>1</no>
<pplid>PPL_6JOa_A1397_1_0005792</pplid>
<uci>G002+AKS-KHF_12C138C885FFFFB1397X0</uci>
<title>세종</title>
<document>
<통합인명메타 UCI="G002+AKS-KHF_12C138C885FFFFB1397X0" id="PPL_6JOa_A1397_1_0005792">
<시대>조선 전기</시대>
<분류정보 번호="1">
<분류 level="1">왕실</분류>
<분류 level="2">왕</분류>
<분류 level="3">왕</분류>
</분류정보>
<성별>남</성별>
<나이>54</나이>
<인명정보>
<인명 식별자="" 유형="시호" 한글음="장헌">莊憲</인명>
<인명 NO="5792" 유형="묘호" 표시="대표" 한글음="세종">世宗</인명>
<인명 식별자="" 유형="성명" 한글음="이도">李祹</인명>
<인명 식별자="" 유형="이칭" 한글음="세종대왕">世宗大王</인명>
</인명정보>
<생몰년정보>
<생년>
<연도 시대구분="A">1397</연도>
<왕대>태조 6</왕대>
<간지/>
<세기/>
</생년>
<몰년>
<연도 시대구분="A">1450</연도>
<왕대>세종 32</왕대>
<간지/>
<세기/>
</몰년>
</생몰년정보>
<본관 id="N539" 식별자="" 한글음="전주">全州</본관>
<가족관계정보>
<인명 PPLID="" 관계="부" 식별자="" 유형="묘호" 한글음="태종">太宗</인명>
<인명 PPLID="" 관계="모" 식별자="" 유형="시호" 한글음="태종">太宗</인명>
</가족관계정보>
<공간정보 관계="" 유형="">
<지명 관계="출신지" 유형="">평안남도 평양</지명>
</공간정보>
<관련사건>
<사건>105인사건</사건>
</관련사건>
</통합인명메타>
</document>
</list>
</resultSet>
</resultInfo>
</aksPeopleAPI>
4. 역대인물 OpenAPI 활용 예시
(1) XML 방식
예시화면
샘플소스
var apiKey = "857f940ccd144a87ba118e0d4499e331"; // 인증키
try {
$.post("/openapi", // 역대인물 OpenAPI 호출 URL
{
key : apiKey, // 인증키
query:"PPL_6JOa_A1397_1_0005792", // 역대인물 등록번호를 검색어로 사용
category:"pplid", // 검색 범위는 역대인물 ID 검색을 위한 pplid 사용
startPage:1, // 시작페이지 설정
pageSize:50, // 페이지 크기 설정
startHilightTag:"", // 하이라이트 시작 태그
endHilightTag:"", // 하이라이트 종료 태그
format:"xml" // xml 형식 프로토콜 사용
},
function(xml) { // 검색 결과를 받는 함수
xsl=loadXMLDoc("/openapi/openapi.xsl"); // test용 openapi xslt 파일 지정
if (window.ActiveXObject) // IE인 경우
{
// xsl파일을 적용하여 XML을 Html로 변환한다.
htmlString = xml.transformNode(xsl);
}
// code for Mozilla, Firefox, Opera, etc.
else if (document.implementation && document.implementation.createDocument)
{
xsltProcessor=new XSLTProcessor();
// xsl파일을 적용하여 XML을 Html로 변환한다
xsltProcessor.importStylesheet(xsl);
htmlString = xsltProcessor.transformToFragment(xml,document);
}
// 변환된 html을 팝업 창에 삽입한다.
popWinBody.innerHTML = htmlString ;
}
,"xml"); // AJAX 통신 결과를 XML형식을 받는다.(JQuery 문법)
} catch(e) {
window.status = e;
}
활용예
아래 글이 여러 분이 쓴 글일 경우, “세종대왕”에 마우스를 올리면 세종대왕에 대한 정보를 볼 수 있도록 할 수 있습니다.
아래 글이 여러 분이 쓴 글일 경우, “세종대왕”에 마우스를 올리면 세종대왕에 대한 정보를 볼 수 있도록 할 수 있습니다.
조선 세종 때 최윤덕(崔潤德) 등을 보내 여진족(女眞族)을 토벌하고 압록강 상류의 여연(閭延)ㆍ자성 (慈城)ㆍ무창(茂昌)ㆍ우예(虞芮)의 4군을 설치했는데, 뒤에 그 유지ㆍ확보가 용이하지 못하다는 이유에서 철폐론이 제기되어오다가 단종ㆍ세조 때에 걸쳐 드디어 철폐되자, 그후 이 지방은 오랫동안 폐사군이라 불리게 되었다. 세종대왕은...
(2) JSON 방식
예시화면
샘플소스
var apiKey = "857f940ccd144a87ba118e0d4499e331"; // 인증키
try {
$.post("/openapi", // 역대인물 OpenAPI 호출 URL
{
key : apiKey, // 인증키
query:"이순신", // 검색어
category:"total", // 검색 범위
startPage:1, // 시작페이지 설정
pageSize:50, // 페이지 크기 설정
startHilightTag:"", // 하이라이트 시작 태그
endHilightTag:"", // 하이라이트 종료 태그
format:"json" // xml 형식 프로토콜 사용
},
function(data) { // data는 json 객체이다.
var result = data[0].resultInfo; // resultInfo 셋 정보를 가져온다.
if (result.success == "false") // 실패인 경우 오류 메세지를 출력한다.
{
alert(result.message);
return;
}
var resultHtml = "";
if (result.totalCount == 0) // totalCount가 0 이면 검색결과 건수가 없다.
{
resultHtml = resultHtml + "<tr><d align='center'>검색된 결과가 없습니다.</td><tr>";
}
else {
var list = result.resultSet; // resultSet은 Array형식으로 list 객제를 가지고 있다.
for (i = 0; i < result.resultSize; i++) // resultSize값 만큼 반복하여 list 구조체를
출력한다.
{
var livedie = list[i].document.통합인명메타.생몰년정보.생년.연도["#text"];
livedie = " (" +livedie + " ~ " +
list[i].document.통합인명메타.생몰년정보.생년.연도["#text"] + ")";
resultHtml = resultHtml + "<tr><td align='left'> ["+
list[i].document.통합인명메타.시대+ "] "+ list[i].title+ livedie +
"<br>";
var d = "";
// 인명 정보를 처리한다.
for (j =0; j < list[i].document.통합인명메타.인명정보.length; j++)
{
var s = list[i].document.통합인명메타.인명정보[j];
d = d + getPeopleName(s);
}
resultHtml = resultHtml + d+"</td><td valign='bottom' align='right'>[
<a href=\"javascript: parent.showAksPeople('"+list[i].pplid +
"');\">자세히보기</a> ]</td><tr>";
resultHtml = resultHtml + "<tr><td colspan=2 height=1
bgColor='#AAAAAA'></td></tr>";
}
} // end else
// 생성된 HTML을 팝업 창에 삽입한다.
openResultPopup(resultHtml);
},"json"); // AJAX 통신 결과를 JSON형식을 받는다.(JQuery 문법)
} catch(e) {
window.status = e;
}
활용예
아래 글이 여러 분이 쓴 글일 경우, “세종”을 마우스로 “긁어서 선택“하면 나오는 검색버튼을 누르면 검색 결과를 볼 수 있도록 할 수 있습니다.
아래 글이 여러 분이 쓴 글일 경우, “세종”을 마우스로 “긁어서 선택“하면 나오는 검색버튼을 누르면 검색 결과를 볼 수 있도록 할 수 있습니다.
조선 세종 때 최윤덕(崔潤德) 등을 보내 여진족(女眞族)을 토벌하고 압록강 상류의 여연(閭延)ㆍ자성(慈城)ㆍ무창 (茂昌)ㆍ우예(虞芮)의 4군을 설치했는데, 뒤에 그 유지ㆍ확보가 용이하지 못하다는 이유에서 철폐론이 제기되어오다가 단종ㆍ세조 때에 걸쳐 드디어 철폐되자,
