AI·NAVER APIリスト
現在提供しているAI·NAVER APIのリストです。AI·NAVER APIを使用する前に次の内容を確認してください。
- アプリケーションの登録およびクライアントアイディとシークレットの値を確認: アプリケーション登録ガイド
API設定を確認: API設定
HTTPヘッダにクライアントアイディとシークレットの値さえ転送すれば直ちに呼び出して使用できるオープンAPIで、地図、座標変換、短縮URLを始め、音声認識、機械翻訳、音声合成などのオープンAPIが該当します。
API名 | メソッド | リクエストURL | フォーマット | 説明 |
---|---|---|---|---|
Clova Speech Synthesis | POST | https://naveropenapi.apigw.ntruss.com/voice/v1/tts |
MP3 | 入力されたテキストを声優の朗読音声で合成 |
Clova Speech Recognition | POST | https://naveropenapi.apigw.ntruss.com/recog/v1/stt |
JSON | 入力された音声を認識してテキストにリターン |
Papago SMT | POST | https://naveropenapi.apigw.ntruss.com/smt/v1/translation |
JSON | 入力されたテキストを翻訳 |
Papago NMT | POST | https://naveropenapi.apigw.ntruss.com/nmt/v1/translation |
JSON | 入力されたテキストを他の国の言語に翻訳 |
Static Map | GET | https://naveropenapi.apigw.ntruss.com/map-static/v2/raster |
IMAGE | 静的地図 |
Tile Map | GET | https://naveropenapi.apigw.ntruss.com/map-tile/v1/raster/styles/{MapType}/{Z}/{X}/{Y}@{Scale}x.{Format}?mt={SubType} |
IMAGE | タイル地図 |
Directions | GET | https://naveropenapi.apigw.ntruss.com/map-direction/v1/driving |
JSON | 道案内 |
Search Places | GET | https://naveropenapi.apigw.ntruss.com/map-place/v1/search |
JSON | 場所検索 |
Geocoding | GET | https://naveropenapi.apigw.ntruss.com/map-geocode/v2/geocode |
JSON | 住所->座標変換 |
Reverse Geocoding | GET | https://naveropenapi.apigw.ntruss.com/map-reversegeocode/v2/gc |
XML,JSON | 座標->住所変換 |
CAPTCHA(Image) | GET | https://naveropenapi.apigw.ntruss.com/captcha/v1/nkey |
JSON | キャプチャキー発行/入力値比較 |
CAPTCHA(Image) | GET | https://naveropenapi.apigw.ntruss.com/captcha-bin/v1/ncaptcha |
JPG | キャプチャイメージリクエスト |
CAPTCHA(Audio) | GET | https://naveropenapi.apigw.ntruss.com/scaptcha/v1/nkey |
JSON | キャプチャキー発行/入力値比較 |
CAPTCHA(Audio) | GET | https://naveropenapi.apigw.ntruss.com/scaptcha-bin/v1/scaptcha |
WAV | キャプチャイメージリクエスト |
nShortURL | GET / POST | https://naveropenapi.apigw.ntruss.com/util/v1/shorturl |
JSON, XML | 入力されたURLをme2.doの形の短いURLに変換 |
Search Trend | POST | https://naveropenapi.apigw.ntruss.com/datalab/v1/search |
JSON | 期間別のトレンドデータ出力 |
APIの基本
API (Application Programming Interface)
開発者がプログラミング作業の際にオペレーティングシステム、システム、アプリケーション、ライブラリなどを利用して応用プログラムを作成できるようにする様々なインターフェースを合わせていう名称です。(例: Window API, Java API, HTML5 API, Android APIなど)
アプリケーション
アプリケーションはAPIを活用して作られる様々なプログラム結果物です。ここでは、デベロッパーがAI·NAVER APIを活用して作るウェブ、モバイルウェブ、モバイルアプリを指します。AI·Service APIを利用するためにはNAVERクラウドプラットフォームコンソールのAI·Application Service > AI·NAVER API > Applicationメニューでアプリケーション情報を登録しなければなりません。
API認証
APIゲートウェイ
Application認証Key
AI·NAVER APIを利用するために、各アプリケーションごとに'Application認証Key'というClient ID, Client Secretというペアの文字列のキーの発行を受け、これをAPI呼び出しの際に一緒にAPIゲートウェイサーバに転送することによって、認証されたユーザーであることを立証します。
API呼び出し
リクエストURL (Request URL)
AI·NAVER APIを呼び出すためのAPIのウェブアドレス(URL)を意味します。https://naveropenapi.apigw.ntruss.com/サービスタイプ/バージョン/APIタイプの形で構成されています。
リクエスト変数(Request Parameter)
AI·NAVER APIを呼び出す際に一緒にサーバに転送しなければならない値で、各APIの明細を参照し、リクエスト変数名が間違っていたり必須のリクエスト変数が抜けないように注意しなければなりません。
URLエンコーディング
ハングルや特殊文字がリクエスト変数の値に含まれている場合、サーバへ転送する際に値が文字化けするので、指定されたルールに従って文字の値をコードの値に変換して転送しなければなりませんが、それをURLエンコーディングといいます。URLエンコーディングされた値を再び元の値に変換することをURLデコーディングといいます。
HTTP関連用語
メソッド(Method)
HTTPプロトコルでウェブサーバがリクエストとレスポンスデータを転送するにおいて、事前に約束した動作方式であり、W3CではGET, POSTを始め、8種類のメソッドが定義されています。NAVERオープンAPIを呼び出すためにサーバにリクエストを送る際、必ずAPI明細が指定されたメソッドを使ってAPIを呼び出さなければなりません。
HTTPヘッダ
HTTPヘッダにはウェブサーバに送るリクエストとリクエストデータを説明するメタ情報が入っています。つまり、メソッド、リクエストURL、httpプロトコルのバージョンなどの情報であり、これに追加的に指定された名前や値などを転送できます。NAVERオープンAPIは基本的にクライアントアイディとシークレットの値をヘッダに含ませて転送すれば利用できるようになっています。
HTTPステータスコード
サーバにAPIリクエストを送ると、サーバからはAPI呼び出しが正常に行われたのかについてHTTPステータスコードの値とともにレスポンスを送ります。例えば、呼び出しが正常に行われた場合は200, API呼び出しの方法が間違っていてエラーが発生した場合は400, 403, 404, サーバにエラーが発生した場合は500のようなステータスコードを返します。NAVERオープンAPIのエラーコードをご参考ください。
API呼び出しの例題
Java
// Papago SMT API例題
import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLEncoder;
public class APIExamTranslate {
public static void main(String[] args) {
String clientId = "YOUR_CLIENT_ID";//アプリケーションクライアントアイディの値";
String clientSecret = "YOUR_CLIENT_SECRET";//アプリケーションクライアントシークレットの値";
try {
String text = URLEncoder.encode("お会いできて嬉しいです。", "UTF-8");
String apiURL = "https://naveropenapi.apigw.ntruss.com/nmt/v1/translation";
URL url = new URL(apiURL);
HttpURLConnection con = (HttpURLConnection)url.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("X-NCP-APIGW-API-KEY-ID", clientId);
con.setRequestProperty("X-NCP-APIGW-API-KEY", clientSecret);
// post request
String postParams = "source=ko&target=en&text=" + text;
con.setDoOutput(true);
DataOutputStream wr = new DataOutputStream(con.getOutputStream());
wr.writeBytes(postParams);
wr.flush();
wr.close();
int responseCode = con.getResponseCode();
BufferedReader br;
if(responseCode==200) { // 正常な呼び出し
br = new BufferedReader(new InputStreamReader(con.getInputStream()));
} else { // エラー発生
br = new BufferedReader(new InputStreamReader(con.getErrorStream()));
}
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = br.readLine()) != null) {
response.append(inputLine);
}
br.close();
System.out.println(response.toString());
} catch (Exception e) {
System.out.println(e);
}
}
}
エラーコードのリスト
APIを呼び出すと、HTTP Status CodeでAPI処理結果を受信し、HTTP Response Bodyでレスポンスの値を受信します。レスポンスの値はOpenAPIによってXMLまたはJSONの形式になります。従って、APIレスポンス処理の際、まずHTTP Status Codeから正常に処理されたのかを確認し、レスポンスの形式に合わせて結果を構文解析してサービスに利用できます。
- 正常な呼び出し: HTTPステータスコードは200であり、各APIごとに指定されたフォーマットの結果値を受信します。
- 正常でない呼び出し: HTTPステータスコードは400, 500番帯であり、各APIサーバ別のエラーコードとエラーメッセージの値を受信します。
エラー発生の主な原因
HttpStatusCode | ErrorCode | ErrorMessage | Description |
---|---|---|---|
400 | 100 | Bad Request Exception | protocol(https), endocing(UTF-8)などrequestエラー |
401 | 200 | Authentication Failed | 認証失敗 |
401 | 210 | Permission Denied | 権限なし |
404 | 300 | Not Found Exception | 権限なし |
429 | 400 | Quota Exceeded | Quota超過 |
429 | 410 | Throttle Limited | Rate超過 |
429 | 420 | Rate Limited | Rate超過 |
413 | 430 | Request Entity Too Large | conent-length超過(10MB) |
503 | 500 | Endpoint Error | エンドポイント接続エラー |
504 | 510 | Endpoint Timeout | エンドポイント接続時間超過 |
500 | 900 | Unexpected Error | 例外処理していないエラー |
エラーメッセージのフォーマット
エラーメッセージのフォーマットはエラーが発生する位置と関係なく同一です。
HTTPレスポンスコード
エラーの性格によってHTTPレスポンスコードは400番帯あるいは500番帯のエラーコードで返されます。
エラーメッセージ
エラーメッセージはXMLまたはJSONのフォーマットで提供され、エラーの内容を含めているerrorMessageとエラーのコードを含めているerrorCodeの2つの要素で構成されます。Accept: text/xmlのような情報が入った場合、XMLの形のエラーメッセージを送り、その他の場合はJSONの形のエラーメッセージを送ります。次はXMLとJSONの形のエラーメッセージの例です。
<?xml version="1.0" encoding="UTF-8"?>
<result>
<error>
<message><![CDATA[Authentication failed (認証に失敗しました。)]]></message>
<errorCode><![CDATA[024]]></errorCode>
</error>
</result>
{
"error": {
"errorCode": "300",
"message": "Not Found Exception"
}
}