Nexon Open Api

API 사용하기

애플리케이션 등록 후, API Key 발급이 완료되었다면 문서를 살펴봅니다. (API Key는 내 애플리케이션 > 애플리케이션 상세 페이지에서 확인할 수 있습니다.) API 요청은 간단하지만 요청할 때 알아야 할 몇 가지 세부 사항이 있습니다.

API 조회

상단 메뉴 > 게임 메뉴에서 NEXON Open API를 통해 제공되는 게임별 API 목록을 확인하실 수 있습니다. API마다 다음과 같은 정보를 제공하고 있습니다.

API 정보

API에 대한 설명과 실제 사용될 요청 URL을 제공합니다. API 호출 시 함께 전송이 필요한 요청 파라미터는 Parameters에 표기되어 있으며, 파라미터에 대한 설명은 Description에 제공됩니다.

요청 파라미터 (Parameters)

Open API를 호출할 때 함께 서버로 전송해야 하는 파라미터의 정보를 나타냅니다. 필수값(*required)으로 표시된 파라미터들은 API 호출 시 누락되지 않도록 주의하셔야 합니다.

응답 정보 (Responses)

Open API를 호출한 후 받는 응답 정보들을 제공합니다. Response Description은 API를 정상적으로 호출할 경우 받는 데이터에 대한 설명이나 구조에 대한 설명을 제공합니다. Response Headers와 Response Body는 API를 테스트할 때 사용되며, 자세한 설명은 아래의 API 테스트 항목을 참조하세요.

API 사용

게임 메뉴에서 조회한 요청 URL을 호출하면 Open API를 사용하실 수 있으며, API에 따라 필요한 요청 파라미터를 함께 전송하셔야 합니다. NEXON Open API에서 제공되는 Open API를 호출할 때는, API Key 값을 Header에 포함하셔야 정상적으로 사용할 수 있습니다.

TypeKeyNameContent Type
Headerx-nxopen-api-keyString

API 사용 중 에러가 발생할 경우, 응답코드 값을 보고 에러사유를 판단할 수 있습니다. 아래의 응답코드 표를 참고하세요.

에러 코드응답 코드응답명설명
OPENAPI00001500Internal Server Error서버 내부 오류
OPENAPI00002403Forbidden권한이 없는 경우
OPENAPI00003400Bad Request유효하지 않은 식별자
OPENAPI00004400Bad Request파라미터 누락 또는 유효하지 않음
OPENAPI00005400Bad Request유효하지 않은 API KEY
OPENAPI00006400Bad Request유효하지 않은 게임 또는 API PATH
OPENAPI00007429Too Many RequestsAPI 호출량 초과
OPENAPI00009400Bad Request데이터 준비 중
OPENAPI00010400Bad Request게임 점검 중
OPENAPI00011503Service UnavailableAPI 점검 중

API 테스트

NEXON Open API에서 제공되는 Open API들은 모두 게임 메뉴 내에서 직접 테스트해 보고 그에 대한 응답 값을 조회해 볼 수 있습니다. (테스트 기능은 넥슨 ID로 로그인하고, 테스트를 희망하는 API의 API Key를 발급 받은 상태에서만 사용할 수 있습니다.)


  1. 게임 > 게임선택 > API 목록에서 테스트하고자 하는 API를 선택합니다.
  2. Try it out 버튼을 클릭합니다.
  3. Parameters(요청 파라미터) 입력란에 요청 파라미터를 입력합니다.
  4. Execute 버튼을 클릭하여 API를 호출합니다.
  5. 다음과 같은 정보를 확인합니다.
    1. Curl / Request URL : 입력한 요청 파라미터 값을 포함하여 실제로 호출된 URL
    2. 응답 정보(Server response)
      1. Code : Http 상태 코드로 요청 결과의 상태
      2. Response Headers : 응답받은 정보의 헤더 값
      3. Response Body : 응답받은 정보의 데이터

API 샘플코드

Java 샘플코드

  import java.io.BufferedReader;
  import java.io.InputStreamReader;
  import java.net.HttpURLConnection;
  import java.net.URL;
  import java.net.URLEncoder;
  import java.nio.charset.StandardCharsets;
  
  public class  ApiExample {
    /**
     * 마비노기영웅전 캐릭터명으로 캐릭터 식별자(ocid)를 조회합니다.
     * API 호출에 필요한 API Key 를 발급 받은 후 요청 헤더에 넣어 RESTful API 방식으로 호출합니다.
     * 해당 코드의 경우 응답코드가 200인경우 응답을, 이외의 경우 에러를 출력합니다.
     * */
    public static void main(String[] args) {
      try {
        String API_KEY = "발급 받은 API KEY";
        String characterName = URLEncoder.encode("캐릭터명", StandardCharsets.UTF_8);
  
        String urlString = "https://open.api.nexon.com/heroes/v1/id?character_name=" + characterName;
        URL url = new URL(urlString);
  
        // HTTP connection 설정
        HttpURLConnection connection = (HttpURLConnection)url.openConnection();
        connection.setRequestMethod("GET");
        connection.setRequestProperty("x-nxopen-api-key", API_KEY);
  
        int responseCode = connection.getResponseCode();
  
        BufferedReader in;
        if(responseCode == 200) {
          // responseCode 200 정상응답
          in = new BufferedReader(new InputStreamReader(connection.getInputStream()));
        } else {
          // responseCode 200 이외의 코드가 반환되었을 경우
          in = new BufferedReader(new InputStreamReader(connection.getErrorStream()));
        }
  
        String inputLine;
        StringBuffer response = new StringBuffer();
        while ((inputLine = in.readLine()) != null) {
          response.append(inputLine);
        }
        in.close();
  
        System.out.println(response.toString());
      } catch (Exception exception) {
        System.out.println(exception);
      }
    }
  }

JavaScript 샘플코드

  const API_KEY = "발급 받은 API Key";
  const characterName = "캐릭터명";
  const urlString = "https://open.api.nexon.com/heroes/v1/id?character_name=" + characterName;
  
  const answer = fetch(urlString, {
      headers:{
        "x-nxopen-api-key": API_KEY
      }
  })
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error(error))
  
  console.log(answer)

Python 샘플코드

  headers = {
    "x-nxopen-api-key": "발급 받은 API Key"
  }
  
  characterName = "캐릭터명"
  urlString = "https://open.api.nexon.com/heroes/v1/id?character_name=" + characterName
  response = requests.get(urlString, headers = headers)
  
  print(response.json())

애플리케이션 제작하기

Open API를 이용하여 이용약관에 명시되어 있는 사항 내에서 자유롭게 애플리케이션을 제작하실 수 있습니다만, 제작 시 데이터를 NEXON Open API에서 제공 받았음을 애플리케이션 내에 명시해주셔야 합니다.

NEXON Open API 표기

서비스 및 애플리케이션에 'Data based on NEXON Open API'라는 문구를 명시해주시길 바랍니다.