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ゲートウェイ

AI·NAVER API(v2)はほとんどhttps://naveropenapi.apigw.ntruss.com/サーバを経由して呼び出します。このサーバがつまりAPIゲートウェイサーバであり、オープンAPI呼び出しが入ると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"
  }
}

に対する検索結果は~件です。 ""

    に対する検索結果がありません。 ""

    処理中...