AI데이터 구축 일자리 참여 바로가기

어휘 간 유사도 분석 API

어휘 간 유사도 분석 API 란?

다양한 어휘지식을 통합한 WiseWordNet 어휘 지식베이스에 기반하여 어휘 간 거리 정보를 분석하는 기술로서 입력된 여휘간 유사도 결과를 제공합니다. 어휘 간 유사도 분석 API는 HTTP 기반의 REST API 인터페이스로 JSON 포맷 기반의 입력 및 출력을 지원하며 ETRI에서 제공하는 API Key 인증을 통해 사용할 수 있는 Open API입니다.

API 호출 1일 허용량
기술명 API명 1일 허용량
어휘 간 유사도 분석 API 사용하기

어휘 간 유사도 분석 API는 REST API이며, 어휘 간 유사도 분석을 수행할 2개의 어휘 데이터를 HTTP 통신으로 ETRI Open API 서버에 전달하면 됩니다. 서버가 제공하는 REST API의 URI는 다음과 같으며 POST 방식으로 호출해야 합니다.

http://aiopen.etri.re.kr:8000/WiseWWN/WordRel

HTTP 요청으로 어휘 간 유사도 분석을 요청할 때 사전 준비 사항에서 발급받은 API Key 정보를 요청하는 본문에 포함시켜야 합니다. 다음은 HTTP 요청 메시지 예입니다.

[HTTP Request Body]
{
	"request_id": "reserved field",
	"access_key": “YOUR_ACCESS_KEY”,
	"argument": {
		“first_word”: “FIRST_YOUR_WORD”,
		“first_sense_id”: “FIRST_WORD_SENSE_ID”,
		“second_word”: “SECOND_YOUR_WORD”,
		“second_sense_id”: “SECOND_WORD_SENSE_ID”
	}
}
							

위와 같은 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": "com.google.gson.internal.LinkedTreeMap",
	"return_object": {어휘 간 유사도 분석 결과 JSON}
}
							
구현 예제
Java

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/WordRel";
		String accessKey = "YOUR_ACCESS_KEY";           // 발급받은 API Key
		String firstWord = "FIRST_WORD";                // 첫번째 어휘 데이터
		String firstSenseId = " FIRST_WORD_SENSE_ID";  // 첫번째 어휘 의미코드
		String secondWord = "SECOND_WORD";              // 두번째 어휘 데이터
		String secondSenseId = "SECOND_WORD_SENSE_ID"; // 두번째 어휘 의미코드

		Gson gson = new Gson();

		Map<String, Object> request = new HashMap<>();
		Map<String, String> argument = new HashMap<>();

		argument.put("first_word", firstWord);
		argument.put("first_sense_id", firstSenseId);
		argument.put("second_word", secondWord);
		argument.put("second_sense_id", secondSenseId);

		request.put("access_key", accessKey);
		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);

			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
<?php
$openApiURL = "http://aiopen.etri.re.kr:8000/WiseWWN/WordRel";
$accessKey = "YOUR_ACCESS_KEY";
$firstWord = "FIRST_WORD";
$firstSenseId = "FIRST_SENSE_ID";
$secondWord = "SECOND_WORD";
$secondSenseId = "SECOND_SECSE_ID ";


$request = array(
	"access_key" => $accessKey,
	"argument" => array (
		"first_word" => $firstWord,
		"first_sense_id" => $firstSenseId,
		"second_word" => $secondWord,
		"second_sense_id" => $secondSenseId
	)
);

try {
	$server_output = "";
	$ch = curl_init();
	$header = array(
		"Content-Type:application/json; charset=UTF-8",
	);
	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);
?>
										
C++

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/WordRel";
	string accessKey = "YOUR_ACCESS_KEY";
	string firstWord = "FIRST_WORD";
	string firstSenseId = "FIRST_SENSE_ID";
	string secondWord = "SECOND_WORD";
	string secondSenseId = "SECOND_SENSE_ID";

	Json::Value request;
	Json::Value argument;

	argument["first_word"] = firstWord;
	argument["first_sense_id"] = firstSenseId;
	argument["second_word"] = secondWord;
	argument["second_sense_id"] = secondSenseId;

	request["access_key"] = accessKey;
	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" ) ;
		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

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/WordRel"
accessKey = "YOUR_ACCESS_KEY"
firstWord = FIRST_WORD'
firstSenseId = 'FIRST_SENSE_ID'
secondWord = 'SECOND_WORD'
secondSenseId = 'SECOND_SENSE_ID'

requestJson = {
	"access_key": accessKey,
	"argument": {
		'first_word': firstWord,
		'first_sense_id': firstSenseId,
		'second_word': secondWord,
		'second_sense_id': secondSenseId
	}
}

http = urllib3.PoolManager()
response = http.request(
	"POST",
	openApiURL,
	headers={"Content-Type": "application/json; charset=UTF-8"},
	body=json.dumps(requestJson)
)

print("[responseCode] " + str(response.status))
print("[responBody]")
print(str(response.data,"utf-8"))
										 
Node.js
var openApiURL = 'http://aiopen.etri.re.kr:8000/WiseWWN/WordRel';
var access_key = 'YOUR_ACCESS_KEY';
var firstWord = 'FIRST_WORD';
var firstSenseId = 'FIRSR_SENSE_ID';
var secondWord = 'SECOND_WORD';
var secondSenseId = 'SECOND_SENSE_ID';

var requestJson = {
	'access_key': access_key,
	'argument': {
		'first_word': firstWord,
		'first_sense_id': firstSenseId,
		'second_word': secondWord,
		'second_sense_id': secondSenseId
	}
};

var request = require('request');
var options = {
	url: openApiURL,
	body: JSON.stringify(requestJson),
	headers: {'Content-Type':'application/json; charset=UTF-8'}
};
request.post(options, function (error, response, body) {
	console.log('responseCode = ' + response.statusCode);
	console.log('responseBody = ' + body);
});
										
어휘 간 유사도 분석 API 레퍼런스
요청 파라미터

어휘 간 유사도 분석 API에 필요한 요청 본문에 다음과 같은 파라미터를 작성해야 합니다.

[HTTP Request Body]
{
	“access_key”: “YOUR_ACCESS_KEY”,
	“argument”: {
		“first_word”: “FIRST_YOUR_WORD”,
		“first_sense_id”: “FIRST_WORD_SENSE_ID”,
		“second_word”: “SECOND_YOUR_WORD”,
		“second_sense_id”: “SECOND_WORD_SENSE_ID”
	}
}
										

다음은 파라미터에 대한 설명입니다.

Field 명 타입 필수 여부 설명
access_key String API 사용을 위해 ETRI에서 발급한 사용자 API Key
argument Object API 사용 요청 시 분석을 위해 전달할 내용
first_word String 비교 분석할 어휘 Text 로서 UTF-8 인코딩된 텍스트만 지원
first_sense_id String   첫 번째 어휘의 의미 코드
2자리 숫자 : 동음이의어 의미코드
4자리 숫자 : 동음이의어 의미코드(2자리)+다의어 의미 코드(2자리)
second_word String 비교 분석 대상 어휘 Text 로서 UTF-8 인코딩된 텍스트만 지원
second_sense_id String   두 번째 어휘의 의미 코드
2자리 숫자 : 동음이의어 의미코드
4자리 숫자 : 동음이의어 의미코드(2자리)+다의어 의미 코드(2자리)
응답

어휘 간 유사도 분석 API는 요청된 어휘 간 유사도 분석 결과를 JSON 형태의 Text 데이터로 반환합니다.
다음은 정상적인 요청 처리에 대한 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": "com.google.gson.internal.LinkedTreeMap",
	"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 이름 설명
MetaInfo Title Open APIs의 타이틀 명
Link 해당 Open APIs를 사용하기 위한 URL 정보
WWN WordRelInfo FirstWordInfo 첫 번째 어휘 정보
Word 어휘의 원문자열
HomonymCode 어휘의 동음이의어 코드 (2자리 숫자)
PolysemyCode 어휘의 다의어 코드 (2자리 숫자)
Definition 의미 정보
POS 어휘의 품사
명사 : "n"
동사 : "v"
SecondWordInfo 두 번째 어휘 정보
Word 어휘의 원문자열
HomonymCode 어휘의 동음이의어 코드 (2자리 숫자)
PolysemyCode 어휘의 다의어 코드 (2자리 숫자)
Definition 의미 정보
POS 어휘의 품사
명사 : "n"
동사 : "v"
WordRelInfo 어휘 간 유사도 분석 정보
ShortedPath 가장 가까운 연결 어휘 경로 정보
Distance 어휘 경로 거리 정보 (숫자)
Similarity 어휘 간 거리 유사도
Algorithm 거리 유사도 알고리즘
SimScore 거리 유사도 신뢰도
오류 코드

언어 분석 API의 오류 코드 목록은 다음과 같습니다.

http status code result reason 설명
400 -1 Required arguments is empty 필수 파라미터의 값이 없는 경우
400 -1 One or more arguments are not valid 파라미터의 값이 유효하지 않는 경우
413 -1 Request Entity Too Large 요청 문장 또는 어휘의 크기가 서버가 처리 할 수 있는 것보다 큰 경우
429 -1 Too Many Requests 사용자가 주어진 시간 내에 서버에 너무 많은 요청을 하는 경우
404 -1 Unknown Handler 등록되지 않는 서비스를 요청한 경우
408 -1 Handler Timeout 서버의 요청 대기가 시간을 초과한 경우
500 -1 ETRI service server connection refused ETRI 분석 서버에서 요청을 받지 못하는 경우
500 -1 ETRI service server is not exists 수행 가능한 ETRI 분석 서버가 없는 경우
500 -1 Recipient Failure ETRI 분석 서버에서 요청을 처리하지 못하는 경우
500 -1 Unknown ReplyFailure API 요청에 알 수 없는 내부 오류가 발생한 경우
500 -1 Unknown Exception 알 수 없는 내부 오류가 발생한 경우