1. 우리말어휘역사사전 오픈 API 서비스 소개
우리말어휘역사사전 오픈 API는 검색 플랫폼을 외부에 공개하여 다양하고 재미있는 서비스 및 애플리케이션을 개발할 수 있도록 외부 개발자와 사용자들이 공유하는 프로그램입니다. 우리말어휘역사사전에 구축된 양질의 사전 정보를 개인 또는 기관에서 오픈 API를 이용해 자유롭게 이용할 수 있도록 제공합니다.
- ※ 오픈 API란?
- 하나의 웹 사이트에서 자신이 가진 기능을 이용할 수 있도록 공개한 프로그래밍 인터페이스를 오픈 API라고 합니다.
2. 우리말어휘역사사전 오픈 API 서비스 인증 키 발급
오픈 API 서비스를 이용하기 위해서는 먼저 인증 키를 발급받아야 합니다. 인증 키가 올바르지 않은 경우에는 서비스 이용이 제한됩니다. 인증 키가 유효하지 않거나 인증 키를 분실한 경우에는 인증 키를 재발급받아야 합니다.
3. 우리말어휘역사사전 오픈 API 서비스 이용 안내
연계 표준 서비스를 이용하기 위한 XML, JSON 기반의 데이터 형식, 갱신 데이터 요청 변수, 반환되는 코드값을 제공합니다.
오픈 API 요청 URL
검색 요청 변수 (Request Parameters)
| 요청 변수 | 타입 | 허용값 | 필수/선택 | 설명 |
|---|---|---|---|---|
| key | string | 16진수 32자리 | 필수 | 인증키 |
| q | string | - | 필수 | 검색어(UTF-8 인코딩) |
| req_type | string | xml json |
선택 | 요청 타입(기본값 xml) |
| start | integer | 1~1000 | 선택 | 검색의 시작 번호(기본값 1) |
| num | integer | 10~100 | 선택 | 결과 출력 건수(기본값 10) |
| advanced | string | n y |
선택 | - 자세히 찾기 여부(기본값 n) y: 자세히 찾기 사용 n: 자세히 찾기 미사용 |
| ※ 하단의 요청 변수들을 사용하시려면 자세히 찾기 여부(기본값 n)인 "advanced" 요청 변수를 'y'로 하셔야 합니다. | ||||
| target | integer | 1 ~ 9 | 선택 | - 찾을 대상(기본값 1) 1: 어휘(표제어) 2: 한눈에 보는 어휘 역사 3: 기본 정보 4: 부가 정보 5: 기타 정보 6: 역사 속 표기 7: 관련어 8: 세기별 용례 9: 참고 자료 |
| method | string | exact include start end no |
선택 | - 검색 방식(기본값: exact) exact: 일치 검색 include: 포함 검색 start: 시작 end: 끝 no: 내용 없음 |
| type1 | array of string | all word phrase idiom proverb |
선택 | - 구분 1(기본값 all) all: 전체 - 아래 값을 다중 선택할 수 있도록 콤마(,)로 구분하여 나열한다. word: 단어 phrase: 구 |
| letter_s | integer | 1 ~ | 선택 | - 표제어 음절 수 시작(기본값 1) |
| letter_e | integer | 1 ~ | 선택 | - 표제어 음절 수 끝(기본값 1) |
| A_letter_s | integer | 1 ~ | 선택 | 역사 속 표기 음절 수 시작(기본값 1) |
| A_letter_e | integer | 1 ~ | 선택 | 역사 속 표기 음절 수 끝(기본값 1) |
검색 출력 결과 필드 (Response field)
| 필드 | 타입 | 필수/선택 | 설명 |
|---|---|---|---|
| channel | - | 필수 | 결과를 포함하는 컨테이너 |
| title | string | 필수 | 우리말어휘역사사전 오픈 API 제목 (고정값: 우리말어휘역사사전 오픈 API - 사전 검색) |
| link | string | 필수 | 우리말어휘역사사전 URL (고정값: https://kdict.korean.go.kr/history) |
| description | string | 필수 | 오픈 API 서비스 설명 (고정값: 우리말어휘역사사전 오픈 API – 사전 검색 결과) |
| lastBuildDate | datetime | 필수 | 검색 결과를 생성한 시간 |
| total | integer | 필수 | 검색된 전체 어휘 개수 |
| start | integer | 필수 | 검색 결과 시작 번호 |
| num | integer | 필수 | 검색 결과로 제공하는 어휘 개수 |
| item | - | 필수 | 개별 검색 결과를 포함하는 컨테이너. 'num'만큼 반복함 |
| form | string | 필수 | 표제어 |
| word_number | num | 필수 | 어깨 번호 |
| type | string | 필수 | 구성 단위 (단어, 구) |
| definition | string | 필수 | 뜻풀이 (우리말샘 연결 첫번째 의미) |
| link | string | 필수 | 사전 내용 보기 URL |
| origin_summary | - | 필수 | 어원 정보 요약 컨테이너 |
| forms_changed | - | 필수 | 한눈에 보는 어휘 역사 컨테이너 (1..N 반복) |
| form | string | 필수 | 형태 |
| centuries | array(string) | 필수 | 세기 목록 (15세기 이전~20세기) |
검색 에러 메시지 (error message)
| 에러 코드 | 에러 메시지 | 설명 |
|---|---|---|
| 000 | System error | 시스템 에러 |
| 020 | Unregistered key | 등록되지 않은 키 |
| 021 | Your key is temporary unavailable | 일시적으로 사용 중지된 인증 키 |
| 100 | Incorrect query request | 부적절한 쿼리 요청. query 필드 자체가 없는 경우에 발생하는 에러 메시지 |
| 101 | Invalid target value | 부적절한 검색 필드 |
| 102 | Invalid method value | 부적절한 검색 방식 |
| 103 | Invalid num value | 부적절한 검색 개수 |
| 104 | Invalid start value | 부적절한 start 값 |
| 105 | Invalid advanced value | 부적절한 자세히 찾기 여부 |
| 200 | Invalid type1 value | 부적절한 type1 값 |
| 201~209 | - | 예약 |
| 210 | Invalid pos value | 부적절한 품사 |
| 212 | Invalid letter_s value | 부적절한 표제어 음절 수 시작 |
| 213 | Invalid letter_e value | 부적절한 표제어 음절 수 종료 |
| 214 | Invalid A_letter_s value | 부적절한 역사 속 표기 음절 수 시작 |
| 215 | Invalid A_letter_e value | 부적절한 역사 속 표기 음절 수 끝 |
검색 출력 메시지 XML 예시
<?xml version="1.0" encoding="UTF-8" ?>
<channel>
<title>우리말어휘역사사전 오픈 API - 사전 검색</title>
<link>https://kdict.korean.go.kr/history</link>
<description>우리말어휘역사사전 오픈 API – 사전 검색 결과</description>
<lastBuildDate>20250101120000</lastBuildDate>
<total>1</total>
<start>1</start>
<num>10</num>
<item>
<form>나무</form>
<word_number>1</word_number>
<type>단어</type>
<definition>줄기나 가지가 목질로 된 여러해살이 식물.</definition>
<link>https://kdict.korean.go.kr/history/view?target_code=10001</link>
<origin_summary>
<forms_changed>
<form>나모</form>
<centuries>15세기 , 16세기 , 17세기 , 18세기 , 19세기</centuries>
<form>나ᇚ</form>
<centuries>15세기 , 16세기 , 17세기 , 18세기 , 19세기</centuries>
<form>나무</form>
<centuries>16세기 , 17세기 , 18세기 , 19세기 , 20세기</centuries>
</forms_changed>
</origin_summary>
</item>
</channel>
<?xml version="1.0" encoding="UTF-8" ?> <error> <error_code>에러 코드</error_code> <message>에러 메시지</message> </error>
<?xml version="1.0" encoding="UTF-8" ?> <error> <error_code>020</error_code> <message>Unregistered key</message> </error>
검색 출력 메시지 JSON 예시
{
"channel": {
"title": "우리말어휘역사사전 오픈 API - 사전 검색",
"link": "https://kdict.korean.go.kr/history",
"description": "우리말어휘역사사전 오픈 API – 사전 검색 결과",
"lastBuildDate": "20250101120000",
"total": 1,
"start": 1,
"num": 10,
"item": [
{
"form": "가다",
"word_number": 1,
"type": "단어",
"definition": "한 곳에서 다른 곳으로 장소를 이동하다.",
"link": "https://kdict.korean.go.kr/history/view?target_code=10001",
"origin_summary": {
"forms_changed": [
{
"form": "나모",
"centuries": "15세기 , 16세기 , 17세기 , 18세기 , 19세기"
},
{
"form": "나ᇚ",
"centuries": "15세기 , 16세기 , 17세기 , 18세기 , 19세기"
},
{
"form": "나무",
"centuries": "16세기 , 17세기 , 18세기 , 19세기 , 20세기"
}
]
}
}
]
}
}
{
"error": {
"error_code": "에러 코드",
"message": "에러 메시지"
}
}
{
"error": {
"error_code": 20,
"message": "Unregistered key"
}
}
오픈 API 요청 URL
검색 요청 변수 (Request Parameters)
| 요청 변수 | 타입 | 허용값 | 필수/선택 | 설명 |
|---|---|---|---|---|
| key | string | 16진수 32자리 | 필수 | 인증 키 |
| method | string | word_info target_code |
필수 | - 검색 방식(기본값 word_info) word_info: 표제어 정보(표제어 + 어깨 번호) target_code: 대상 코드(target_code) 직접 검색 |
| req_type | string | xml json |
선택 | 요청 타입(기본값 xml) |
| q | string | - | 필수 | 검색어(UTF-8 인코딩) |
검색 출력 결과 필드 (Response field)
| 상위 필드 | 필드 | 타입 | 필수/선택 | 설명 |
|---|---|---|---|---|
| - | channel | - | 필수 | 결과를 포함하는 컨테이너 |
| channel | title | String | 필수 | 우리말어휘역사사전 오픈 API 제목 (고정값: 우리말어휘역사사전 오픈 API - 사전 내용) |
| channel | link | String | 필수 | 우리말어휘역사사전 URL (고정값: https://kdict.korean.go.kr/history) |
| channel | description | String | 필수 | 오픈 API 서비스 설명 (고정값: 우리말어휘역사사전 오픈 API – 사전 내용 검색 결과) |
| channel | lastBuildDate | datetime | 필수 | 검색 결과를 생성한 시간 |
| channel | total | integer | 필수 | 검색 건수 ('1' 결과 있음, '0' 결과 없음) |
| channel | item | - | 필수 | 사전 전체 항목을 포함하는 컨테이너 |
| item | target_code | integer | 필수 | 대상 코드 |
| word_info | form | string | 필수 | 표제어 |
| word_info | word_number | num | 필수 | 어깨 번호 |
| word_info | type | string | 필수 | 구성 단위 (단어, 구) |
| sense_info | definition | string | 필수 | 뜻풀이 |
| sense_info | definition_original | string | 필수 | 뜻풀이(어휘 링크 포함) |
| origin | origin_info | - | 필수 | 어원 정보 항목을 포함하는 컨테이너 |
| origin_info | forms_changed | - | 필수 | 한눈에 보는 어휘 역사 항목을 포함하는 컨테이너 (1..N 반복) |
| forms_changed | form | string | 필수 | 형태 |
| forms_changed | centuries | string | 필수 | 세기 |
| origin_info | language_info | string | 선택 | 기본 정보 |
| origin_info | other_info | string | 선택 | 부가 정보 |
| origin_info | annotations | string | 선택 | 기타 정보 |
| origin_info | other_forms | string | 선택 | 역사 속 표기 |
| origin_info | realted_forms | string | 선택 | 관련어 |
| historical_info | historical_examples | - | 필수 | 세기별 용례 정보를 포함하는 컨테이너 |
| historical_examples | definitions | - | 필수 | 세기별 용례 의미 정보를 포함하는 컨테이너 |
| definitions | definition | string | 선택 | 용례 의미 |
| definitions | centuries | - | 필수 | 세기별 용례 항목을 포함하는 컨테이너 |
| centuries | century | string | 필수 | 세기 |
| centuries | form | string | 필수 | 세기별 표기 |
| centuries | examples | - | 필수 | 세기별 용례 정보를 포함하는 컨테이너 |
| examples | example | string | 필수 | 세기별 용례 |
| examples | source | string | 필수 | 세기별 용례 출전 |
| examples | original | string | 선택 | 세기별 용례 원문 |
| examples | translation | string | 선택 | 세기별 용례 현대어역 |
| references_info | references | - | 선택 | 참고 자료를 포함하는 컨테이너 |
| references | authors | string | 필수 | 참고 자료 저자명 |
| references | year | string | 필수 | 참고 자료 연도 |
| references | title | string | 필수 | 참고 자료 제목 |
| references | publisher | string | 필수 | 참고 자료 출판사 또는 학술지 |
검색 에러 메시지 (error message)
| 에러 코드 | 에러 메시지 | 설명 |
|---|---|---|
| 000 | System error | 시스템 에러 |
| 020 | Unregistered key | 등록되지 않은 키 |
| 021 | Your key is temporary unavailable | 일시적으로 사용 중지된 인증 키 |
| 100 | Incorrect query request | 부적절한 쿼리 요청. query 필드 자체가 없는 경우에 발생하는 에러 메시지 |
| 102 | Invalid method value | 부적절한 검색 방식 |
검색 출력 메시지 XML 예시
<?xml version="1.0" encoding="UTF-8" ?>
<channel>
<title>우리말어휘역사사전 오픈 API - 사전 내용</title>
<link>https://kdict.korean.go.kr/history</link>
<description>우리말어휘역사사전 오픈 API – 사전 내용 검색 결과</description>
<lastBuildDate>20250101120000</lastBuildDate>
<total>1</total>
<item>
<target_code>10001</target_code>
<word_info>
<form>갈등</form>
<word_number>1</word_number>
<type>단어</type>
</word_info>
<sense_info>
<definition>두 가지 이상의 상반되는 요구나 욕구, 기회 또는 목표에 직면하였을 때, 선택을 하지 못하고 괴로워함. 또는 그런 상태.</definition>
</sense_info>
<sense_info>
<definition>칡과 등나무가 서로 얽히는 것과 같이, 개인이나 집단 사이에 목표나 이해관계가 달라 서로 적대시하거나 충돌함. 또는 그런 상태.</definition>
</sense_info>
<origin>
<origin_info>
<forms_changed>
<form>葛藤</form>
<centuries>15세기, 16세기, 18세기, 20세기</centuries>
</forms_changed>
<forms_changed>
<form>갈등</form>
<centuries>18세기, 19세기, 20세기</centuries>
</forms_changed>
<language_info>'갈등'은 15세기에 한자로 표기된 '葛藤'으로 나타나고 18세기부터 한글로 표기된 '갈등'으로 나타난다. '갈등'은 본래 칡나무와 등나무 덩굴을 의미하는 것이나 "이해관계의 충돌"의 뜻도 나타낸다.</language_info>
<other_info>'葛藤'은 일본어와 중국어에서 한국어와 같은 의미로 쓰인다.</other_info>
<annotations>"칡과 등나무의 덩굴"의 뜻으로 쓰인 '갈등'은 불교 문헌에서 비유적으로 "번뇌, 번민"의 뜻을 나타내었다.</annotations>
<other_forms>葛藤, 갈등</other_forms>
</origin_info>
</origin>
<historical_info>
<historical_examples>
<definitions>
<definition>칡나무와 등나무 덩굴</definition>
<centuries>
<century>15세기</century>
<form>葛藤</form>
<examples>
<example>하ᄂᆞᆯ해 ᄀᆞᄃᆞᆨᄒᆞᆫ 葛藤ᄋᆞᆯ 버혀 긋ᄂᆞ니</example>
<source>1482 금강경삼가해언해 1:3ㄴ</source>
<original>截斷彌天葛藤ᄒᆞᄂᆞ니</original>
<translation>하늘에 가득한 나무덩굴을 베어 끊으니</translation>
</examples>
</centuries>
<centuries>
<century>19세기</century>
<form>갈등</form>
<examples>
<example>갈등츩 葛藤</example>
<source>1880 한불자전 135</source>
<translation>갈등칡</translation>
</examples>
</centuries>
</definitions>
<definitions>
<definition>개인이나 집단 사이에 목표나 이해관계가 달라 서로 적대시하거나 충돌함.</definition>
<centuries>
<century>16세기</century>
<form>葛藤</form>
<examples>
<example>一卷 {葛藤을} 一句에 都破ᄒᆞ샷다</example>
<source>1569 선가귀감 67ㄴ</source>
<translation>한 권의 갈등을 한 마디에 타파하시는구나.</translation>
</examples>
</centuries>
<centuries>
<century>18세기</century>
<form>갈등</form>
<examples>
<example>분연히 갈등ᄒᆞ야 사ᄅᆞᆷ을 ᄀᆡᆼ감의 ᄲᅡ디게 ᄒᆞ면</example>
<source>1756 천의소감언해 뉸음:2ㄴ</source>
<translation>분연히 갈등하여 사람을 굴에 빠지게 하면</translation>
<example>그 쟝ᄎᆞᆺ 엇더ᄒᆞᆫ 갈등이 나리오</example>
<source>1777 명의록언해 首下:56ㄱ</source>
<original>其將生出何許葛藤乎</original>
<translation>장차 어떠한 갈등이 나겠는가?</translation>
</examples>
</centuries>
</definitions>
</historical_examples>
</historical_info>
</item>
</channel>
<?xml version="1.0" encoding="UTF-8" ?> <error> <error_code>에러 코드</error_code> <message>에러 메시지</message> </error>
<?xml version="1.0" encoding="UTF-8" ?> <error> <error_code>020</error_code> <message>Unregistered key</message> </error>
검색 출력 메시지 JSON 예시
{
"channel": {
"title": "우리말어휘역사사전 오픈 API - 사전 내용",
"link": "https://kdict.korean.go.kr/history",
"description": "우리말어휘역사사전 오픈 API – 사전 내용 검색 결과",
"lastBuildDate": "20250101120000",
"total": 1,
"item": {
"target_code": 10001,
"word_info": {
"form": "갈등",
"word_number": 1,
"type": "단어"
},
"sense_info": [
{
"definition": "두 가지 이상의 상반되는 요구나 욕구, 기회 또는 목표에 직면하였을 때, 선택을 하지 못하고 괴로워함. 또는 그런 상태.",
"definition_original": "두 가지 이상의 상반되는 요구나 욕구, 기회 또는 목표에 직면하였을 때, 선택을 하지 못하고 괴로워함. 또는 그런 상태."
},
{
"definition": "칡과 등나무가 서로 얽히는 것과 같이, 개인이나 집단 사이에 목표나 이해관계가 달라 서로 적대시하거나 충돌함. 또는 그런 상태.",
"definition_original": "칡과 등나무가 서로 얽히는 것과 같이, 개인이나 집단 사이에 목표나 이해관계가 달라 서로 적대시하거나 충돌함. 또는 그런 상태."
}
],
"origin": {
"origin_info": {
"forms_changed": [
{
"form": "葛藤",
"centuries": "15세기, 16세기, 18세기, 20세기"
},
{
"form": "갈등",
"centuries": "18세기, 19세기, 20세기"
}
],
"language_info": "'갈등'은 15세기에 한자로 표기된 '葛藤'으로 나타나고 18세기부터 한글로 표기된 '갈등'으로 나타난다. '갈등'은 본래 칡나무와 등나무 덩굴을 의미하는 것이나 \"이해관계의 충돌\"의 뜻도 나타낸다.",
"other_info": "'葛藤'은 일본어와 중국어에서 한국어와 같은 의미로 쓰인다.",
"annotations": "\"칡과 등나무의 덩굴\"의 뜻으로 쓰인 '갈등'은 불교 문헌에서 비유적으로 \"번뇌, 번민\"의 뜻을 나타내었다.",
"other_forms": "葛藤, 갈등"
}
},
"historical_info": {
"historical_examples": {
"definitions": [
{
"definition": "칡나무와 등나무 덩굴",
"centuries": [
{
"century": "15세기",
"form": "葛藤",
"examples": {
"example": "하ᄂᆞᆯ해 ᄀᆞᄃᆞᆨᄒᆞᆫ 葛藤ᄋᆞᆯ 버혀 긋ᄂᆞ니",
"source": "1482 금강경삼가해언해 1:3ㄴ",
"original": "截斷彌天葛藤ᄒᆞᄂᆞ니",
"translation": "하늘에 가득한 나무덩굴을 베어 끊으니"
}
},
{
"century": "19세기",
"form": "갈등",
"examples": {
"example": "갈등츩 葛藤",
"source": "1880 한불자전 135",
"translation": "갈등칡"
}
}
]
},
{
"definition": "개인이나 집단 사이에 목표나 이해관계가 달라 서로 적대시하거나 충돌함.",
"centuries": [
{
"century": "16세기",
"form": "葛藤",
"examples": {
"example": "一卷 {葛藤을} 一句에 都破ᄒᆞ샷다",
"source": "1569 선가귀감 67ㄴ",
"translation": "한 권의 갈등을 한 마디에 타파하시는구나."
}
},
{
"century": "18세기",
"form": "갈등",
"examples": [
{
"example": "분연히 갈등ᄒᆞ야 사ᄅᆞᆷ을 ᄀᆡᆼ감의 ᄲᅡ디게 ᄒᆞ면",
"source": "1756 천의소감언해 뉸음:2ㄴ",
"translation": "분연히 갈등하여 사람을 굴에 빠지게 하면"
},
{
"example": "그 쟝ᄎᆞᆺ 엇더ᄒᆞᆫ 갈등이 나리오",
"source": "1777 명의록언해 首下:56ㄱ",
"original": "其將生出何許葛藤乎",
"translation": "장차 어떠한 갈등이 나겠는가?"
}
]
}
]
}
]
}
}
}
}
}
{
"error": {
"error_code": "에러 코드",
"message": "에러 메시지"
}
}
{
"error": {
"error_code": 20,
"message": "Unregistered key"
}
}