동음이의어 정보 API 란?
국립국어원의 표준국어대사전에 등재된 어휘의 동음이의어(소리는 같으나 뜻이 다른 단어) 사전 정보를 조회하는 API로 입력된 어휘의 동음이의어 정보를 제공합니다. 동음이의어 정보 API는 HTTP 기반의 REST API 인터페이스로 JSON 포맷 기반의 입력 및 출력을 지원하며 ETRI에서 제공하는 API Key 인증을 통해 사용할 수 있는 Open API 입니다.
국립국어원의 표준국어대사전에 등재된 어휘의 동음이의어(소리는 같으나 뜻이 다른 단어) 사전 정보를 조회하는 API로 입력된 어휘의 동음이의어 정보를 제공합니다. 동음이의어 정보 API는 HTTP 기반의 REST API 인터페이스로 JSON 포맷 기반의 입력 및 출력을 지원하며 ETRI에서 제공하는 API Key 인증을 통해 사용할 수 있는 Open API 입니다.
기술명 | API명 | 1일 허용량 |
---|---|---|
어휘관계 분석 기술 | 동음이의어 분석 API | 5,000건/일 |
동음이의어 정보 API는 REST API이며, 동음이의어 조회의 대상 어휘 데이터를 HTTP 통신으로 ETRI Open API 서버에 전달하면 됩니다. 서버가 제공하는 REST API의 URI는 다음과 같으며 POST 방식으로 호출해야 합니다.
http://aiopen.etri.re.kr:8000/WiseWWN/Homonym
HTTP 요청으로 동음이의어 정보 조회를 요청할 때 사전 준비 사항에서 발급받은 API Key 정보를 요청 본문에 포함시켜야 합니다. 다음은 HTTP 요청 메시지 예입니다.
[HTTP Request Header]
"Authorization" : "YOUR_ACCESS_KEY"
[HTTP Request Body]
{
"request_id": "reserved field",
"argument": {
"word": "YOUR_WORD"
}
}
위와 같은 HTTP 요청을 ETRI Open API 서버로 전달하면 서버는 JSON 형태의 Text 데이터를 HTTP 응답 메시지로 반환합니다.
다음은 HTTP 응답 예제
입니다.
[HTTP Response Header]
Access-Control-Allow-Origin:*
Connection:close
Content-Length:0
Content-Type:application/json; charset=UTF-8
[HTTP Response Body]
{
"request_id": "reserved field",
"result": 0,
"return_type": "kr.re.etri.aiopen.restapi.client.dto.OpenApiHomonymResult",
"return_object": {동음이의어 정보 결과 JSON}
}
JSON parsing을 위해 Gson 라이브러리를 사용하여 제공하고 있습니다. Gson 라이브러리에 대한 자세한 설명은 https://github.com/google/gson 에서 확인 하실 수 있습니다.
import java.io.DataOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.net.HttpURLConnection;
import java.net.MalformedURLException;
import java.net.URL;
import java.util.HashMap;
import java.util.Map;
import com.google.gson.Gson;
public class Example {
static public void main ( String[] args ) {
String openApiURL = "http://aiopen.etri.re.kr:8000/WiseWWN/Homonym";
String accessKey = "YOUR_ACCESS_KEY"; // 발급받은 API Key
String word = "YOUR_WORD"; // 조회할 어휘 데이터
Gson gson = new Gson();
Map<String, Object> request = new HashMap<>();
Map<String, String> argument = new HashMap<>();
argument.put("word", word);
request.put("argument", argument);
URL url;
Integer responseCode = null;
String responBody = null;
try {
url = new URL(openApiURL);
HttpURLConnection con = (HttpURLConnection)url.openConnection();
con.setRequestMethod("POST");
con.setDoOutput(true);
con.setRequestProperty("Content-Type", "application/json; charset=UTF-8");
con.setRequestProperty("Authorization", accessKey);
DataOutputStream wr = new DataOutputStream(con.getOutputStream());
wr.write(gson.toJson(request).getBytes("UTF-8"));
wr.flush();
wr.close();
responseCode = con.getResponseCode();
InputStream is = con.getInputStream();
byte[] buffer = new byte[is.available()];
int byteRead = is.read(buffer);
responBody = new String(buffer);
System.out.println("[responseCode] " + responseCode);
System.out.println("[responBody]");
System.out.println(responBody);
} catch (MalformedURLException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
}
}
}
<?php
$openApiURL = "http://aiopen.etri.re.kr:8000/WiseWWN/Homonym";
$accessKey = "YOUR_ACCESS_KEY";
$word = "YOUR_WORD";
$request = array(
"argument" => array (
"word" => $word
)
);
try {
$server_output = "";
$ch = curl_init();
$header = array(
"Content-Type:application/json; charset=UTF-8",
"Authorization":{$accessKey}
);
curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
curl_setopt($ch, CURLOPT_URL, $openApiURL);
curl_setopt($ch, CURLOPT_VERBOSE, true);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode ( $request) );
$server_output = curl_exec ($ch);
if($server_output === false) {
echo "Error Number:".curl_errno($ch)."\n";
echo "Error String:".curl_error($ch)."\n";
}
curl_close ($ch);
} catch ( Exception $e ) {
echo $e->getMessage ();
}
echo "result = " . var_dump($server_output);
?>
JSON parsing을 위해 jsoncpp 라이브러리를 사용하여 제공하고 있습니다. jsoncpp 라이브러리에 대한 자세한 설명은 https://github.com/open-source-parsers/jsoncpp 에서 확인 하실 수 있습니다.
HTTP 통신을 위해 curl 라이브러리를 사용하여 제공하고 있습니다. curl 라이브러리에 대한 자세한 설명은 https://curl.haxx.se/libcurl 에서 확인 하실 수 있습니다.
컴파일을 위해서는 아래와 같이 추가된 LIB에 대한 옵션을 추가해야 합니다.
g++ (c++파일명) (JSONCPP)/json/json.h (JSONCPP)/json/json-forwards.h (JSONCPP)/jsoncpp.cpp -I(CURL)/include -lcurl
#include <curl/curl.h>
#include <json/json.h>
#include <iostream>
#include <string>
using namespace std;
size_t writeDataFunc(void *ptr, size_t size, size_t nmemb, std::string stream);
int main() {
char* openApiURL = (char*)"http://aiopen.etri.re.kr:8000/WiseWWN/Homonym";
string accessKey = "YOUR_ACCESS_KEY";
string word = "YOUR_WORD";
Json::Value request;
Json::Value argument;
argument["word"] = word;
request["argument"] = argument;
CURL *curl;
curl_slist* responseHeaders = NULL;
curl = curl_easy_init();
if( curl == NULL ) {
cout << "Unable to initialize cURL interface" << endl ;
} else {
responseHeaders = curl_slist_append( responseHeaders , "Content-Type: application/json; charset=UTF-8" ) ;
responseHeaders = curl_slist_append( responseHeaders , ("Authorization: " + accessKey).c_str() ) ;
string requestJson = request.toStyledString();
long statusCode;
string response;
curl_easy_setopt(curl, CURLOPT_URL, openApiURL);
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, responseHeaders ) ;
curl_easy_setopt(curl, CURLOPT_TIMEOUT, 5);
curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, requestJson.c_str());
curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, writeDataFunc);
curl_easy_setopt(curl, CURLOPT_WRITEDATA, &response);
curl_easy_perform(curl);
curl_easy_getinfo(curl, CURLINFO_RESPONSE_CODE, &statusCode);
curl_easy_cleanup(curl);
cout << "[responseCode] " << statusCode << endl;
cout << "[responBody]" << endl;
cout << response << endl;
}
return 0;
}
size_t writeDataFunc(void *ptr, size_t size, size_t nmemb, std::string stream) {
size_t realsize = size * nmemb;
std::string temp(static_cast<const char*>(ptr), realsize);
stream.append(temp);
return realsize;
}
python 3.0을 기준으로 작성되었습니다.
HTTP 통신을 위해 urllib3 라이브러리를 사용하여 제공하고 있습니다. Python 3.0 이하의 버전에서 예제를 실행하기 위해서는 별도로 urllib3의 설치가 필요합니다. 설치에 대한 설명은 https://pypi.python.org/pypi/urllib3 를 참고하시기 바랍니다. urllib3 라이브러리에 대한 자세한 설명은 https://urllib3.readthedocs.io/en/latest/ 에서 확인 하실 수 있습니다.
#-*- coding:utf-8 -*-
import urllib3
import json
openApiURL = "http://aiopen.etri.re.kr:8000/WiseWWN/Homonym"
accessKey = "YOUR_ACCESS_KEY"
word = "YOUR_WORD"
requestJson = {
"argument": {
"word": word
}
}
http = urllib3.PoolManager()
response = http.request(
"POST",
openApiURL,
headers={"Content-Type": "application/json; charset=UTF-8","Authorization" : accessKey},
body=json.dumps(requestJson)
)
print("[responseCode]" + str(response.status))
print("[responBody]")
print(str(response.data,"utf-8"))
var openApiURL = 'http://aiopen.etri.re.kr:8000/WiseWWN/Homonym';
var access_key = 'YOUR_ACCESS_KEY';
var word = 'YOUR_WORD';
var requestJson = {
'argument': {
'word': word
}
};
var request = require('request');
var options = {
url: openApiURL,
body: JSON.stringify(requestJson),
headers: {'Content-Type':'application/json','Authorization':access_key}
};
request.post(options, function (error, response, body) {
console.log('responseCode = ' + response.statusCode);
console.log('responseBody = ' + body);
});
동음이의어 정보 API에 필요한 요청 본문에 다음과 같은 파라미터를 작성해야 합니다.
[HTTP Request Body]
{
"access_key": "YOUR_ACCESS_KEY",
"argument": {
"word": "YOUR_WORD"
}
}
다음은 파라미터에 대한 설명입니다.
Field 명 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
access_key | String | ○ | API 사용을 위해 ETRI에서 발급한 사용자 API Key |
argument | Object | ○ | API 사용 요청 시 분석을 위해 전달할 내용 |
word | String | ○ | 동음이의어를 조회할 어휘 Text 로서 UTF-8 인코딩된 텍스트만 지원 |
동음이의어 정보 API는 요청된 어휘의 동음이의어 정보 결과를 JSON 형태의 Text 데이터로 반환합니다.
다음은 정상적인 요청 처리에 대한 HTTP 응답 예입니다.
[HTTP Response Header]
Access-Control-Allow-Origin:*
Connection:close
Content-Length:50783
Content-Type:application/json; charset=UTF-8
[HTTP Response Body]
{
"request_id": "reserved field",
"result": 0,
"return_type": "kr.re.etri.aiopen.restapi.client.dto.OpenApiHomonymResult",
"return_object": {동음이의어 정보 JSON}
}
다음은 오류가 발생한 요청 처리에 대한 HTTP 응답 예입니다.
[HTTP Response Header]
Access-Control-Allow-Origin:*
Connection:close
Content-Length:0
Content-Type:application/json; charset=UTF-8
[HTTP Response Body]
{
"request_id": "reserved field",
"result": -1,
"reason": {오류 메시지}
}
분석된 결과는 다음과 같은 내용이 포함되어 있습니다.
구분 | JSON Key 이름 | 설명 |
---|---|---|
homonym | word | 어휘의 원문자열 |
homonym_code | 어휘의 동음이의어 코드 (표준국어대사전 어깨번호) | |
polysemy_code | 어휘의 다의어 코드 (표준국어대사전 어깨번호) | |
word_class | 어휘의
품사 "감탄사", "관형사", "대명사", "동사", "명사", "부사", "수사", "어미", "접사" |
|
description | 의미 정보 |
동음이의어 정보 API의 오류 코드 목록은 다음과 같습니다.
http status code | result | reason | 설명 |
---|---|---|---|
403 | -1 | Empty Auth Header | Authorization 헤더가 없는 경우 |
403 | -1 | Invalid Key | KEY
API 키가 없는 경우 |
403 |
-1 | Blocked KEY | API
키가 관리자에 의해서 차단된 경우 |
403 |
-1 | Daily Limit Exceeded | 일간 호출 제한에 걸린 경우 |
403 |
-1 | Monthly
Limit Exceeded |
월간 호출 제한에 걸린 경우 |
403 |
-1 | Yearly
Limit Exceeded |
연간 호출 제한에 걸린 경우 |
403 |
-1 | Too Many Keys | 같은 IP에서 여러 API 키가 사용된 경우 |
403 |
-1 | Too Many IPs | 하나의 API 키를 여러 IP 에서 사용한 경우 |
403 |
-1 | Not Allowed IP | API
호출 가능한 IP 가 아닌경우 (API 설정에서 허용된 IP가 아닌경우) |
403 |
-1 | Not Allowed Subpath | 하위경로 접근 제한이 되어 있는 경우 |
403 | -1 | Invalid
API |
등록되지
않은 API를 요청한 경우 |
408 | -1 |
Request
Timeout |
서버의
요청 대기가 시간을 초과한 경우 |
413 |
-1 | Body
Size Limit Exceeded |
요청
바디가 설정된 값보다 큰 경우 |
429 |
-1 | Concurrent
Limit Exceeded |
연속호출
허용 범위를 넘어서 호출한 경우 |
500 | -1 | Internal Server Error | 내부 오류 발생한 경우 |