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를 이용하려면 네이버 클라우드 플랫폼 콘솔의 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 가지의 메서드가 정의되어 있습니다. 네이버 오픈 API를 호출하기 위해 서버로 요청을 보낼 때 반드시 API 명세이 지정된 메서드에 따라 API를 호출해야 합니다.

HTTP 헤더

HTTP 헤더는 웹서버로 보내는 요청과 요청 데이터를 설명하는 메타 정보 들어있습니다. 즉 메서드가 무엇인지, 요청 URL 이 무엇인지, http 프로토콜 버전 등이며, 여기에 추가적으로 지정된 이름과 값을 전송할 수 있습니다. 네이버 오픈 API는 기본적으로 클라이언트 아이디와 시크릿값을 헤더에 포함하여 전송해야 이용할 수 있도록 되어 있습니다.

HTTP 상태 코드

서버로 API 요청을 보내면 서버에서는 API 호출이 잘되었는지 HTTP 상태코드 값과 함께 응답을 보냅니다. 이를 테면 호출이 정상적으로 이뤄졌을 경우는 200, API 호출 방법이 잘못되어 에러가 났을 경우에는 400, 403, 404, 서버 오류가 있을 때는 500과 같은 상태코드를 리턴합니다. 네이버 오픈 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 두 요소로 구성됩니다. 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"
  }
}

""에 대한 건이 검색되었습니다.

    ""에 대한 검색 결과가 없습니다.

    처리중...