사이퍼즈 API 레퍼런스

NeopleCyphersClient는 네오플 오픈 API를 통해 사이퍼즈 게임 데이터에 접근을 제공합니다.

클라이언트 초기화

import { NeopleCyphersClient } from 'neople-sdk-js';

const cyphersClient = new NeopleCyphersClient(apiKey, options?);

매개변수

apiKey (string): 사이퍼즈 API 키
options (object, 선택사항): 설정 옵션
- httpAdapter: 사용자 지정 HTTP 클라이언트 어댑터
- baseURL: API 요청을 위한 사용자 지정 기본 URL

플레이어 메서드

searchPlayer(playerName, options?)

이름으로 플레이어를 검색합니다.

엔드포인트: GET /cy/players

// 기본 검색
const players = await cyphersClient.searchPlayer('플레이어명');

// 고급 검색 옵션
const advancedSearch = await cyphersClient.searchPlayer('플레이어명', {
  limit: 20,
  wordType: 'front',
});

매개변수:

playerName (string): 검색할 플레이어 이름
options (SearchPlayerOptions, 선택사항): 검색 옵션
- limit (number, 선택사항): 최대 결과 개수 (기본값: 10)
- wordType (string, 선택사항): 검색 방식
  - 'match': 정확히 일치 (기본값)
  - 'front': 앞 글자 일치
  - 'full': 전체 검색

반환값: PlayerSearchResult - 기본 정보가 포함된 플레이어 검색 결과

응답 구조:

{
  "rows": [
    {
      "playerId": "player123456",
      "nickname": "플레이어명",
      "represent": {
        "characterId": "character123",
        "characterName": "캐릭터명"
      },
      "grade": 1850,
      "tierName": "티어명",
      "clanName": "클랜명"
    }
  ],
  "next": "nextPageUrl",
  "prev": null
}

getPlayerInfo(playerId)

상세한 플레이어 정보를 가져옵니다.

엔드포인트: GET /cy/players/{playerId}

const player = await cyphersClient.getPlayerInfo('playerId');

매개변수:

playerId (string): 플레이어 식별자

반환값: PlayerDetail - 스탯과 랭킹이 포함된 상세 플레이어 정보

경기 메서드

getPlayerMatches(playerId, options?)

플레이어의 경기 기록을 가져옵니다.

엔드포인트: GET /cy/players/{playerId}/matches

// 기본 경기 기록 조회
const matches = await cyphersClient.getPlayerMatches('playerId');

// 고급 옵션으로 경기 기록 조회
const filteredMatches = await cyphersClient.getPlayerMatches('playerId', {
  gameTypeId: 'rating',
  startDate: '2024-01-01',
  endDate: '2024-01-31',
  limit: 50,
  next: 'nextPageToken',
});

매개변수:

playerId (string): 플레이어 식별자
options (GetMatchesOptions, 선택사항): 조회 옵션
- gameTypeId (string, 선택사항): 게임 타입 필터
  - 'normal': 일반 경기
  - 'rating': 랭킹 경기
  - 'tutorial': 튜토리얼 경기
  - 'custom': 커스텀 경기
- startDate (string, 선택사항): 시작 날짜 필터 (YYYY-MM-DD)
- endDate (string, 선택사항): 끝 날짜 필터 (YYYY-MM-DD)
- limit (number, 선택사항): 최대 결과 개수 (기본값: 10)
- next (string, 선택사항): 페이지네이션을 위한 다음 페이지 토큰

반환값: MatchesResult - 상세 정보가 포함된 경기 목록

응답 구조:

{
  "rows": [
    {
      "date": "2024-01-15T14:30:00+09:00",
      "gameTypeId": "rating",
      "matchId": "match123456789",
      "playInfo": {
        "result": "win",
        "random": false,
        "partyInfo": [
          {
            "playerId": "player123456",
            "nickname": "플레이어명",
            "characterId": "character123",
            "characterName": "캐릭터명",
            "level": 20,
            "killCount": 5,
            "deathCount": 2,
            "assistCount": 8
          }
        ]
      },
      "position": {
        "name": "원거리딜러",
        "attribute": [
          {
            "level": 1,
            "id": "fire",
            "name": "화염"
          }
        ]
      }
    }
  ],
  "next": "nextPageToken",
  "prev": null
}

getMatchDetail(matchId)

상세한 경기 정보를 가져옵니다.

엔드포인트: GET /cy/matches/{matchId}

const match = await cyphersClient.getMatchDetail('matchId');

매개변수:

matchId (string): 경기 식별자

반환값: MatchDetail - 모든 플레이어와 결과를 포함한 상세 경기 정보

랭킹 메서드

getOverallRanking(rankingType, offset?, limit?)

전체 랭킹을 가져옵니다.

엔드포인트: GET /cy/ranking/ratingpoint

const ranking = await cyphersClient.getOverallRanking('mmr', 0, 100);

매개변수:

rankingType (string): 랭킹 타입 ('mmr', 'bp' 등)
offset (number, 선택사항): 페이지네이션을 위한 결과 오프셋
limit (number, 선택사항): 최대 결과 개수

반환값: RankingResult - 전체 랭킹 목록

getCharacterRanking(characterId, offset?, limit?)

특정 캐릭터의 랭킹을 가져옵니다.

엔드포인트: GET /cy/ranking/characters/{characterId}

const characterRanking = await cyphersClient.getCharacterRanking('characterId', 0, 50);

매개변수:

characterId (string): 캐릭터 식별자
offset (number, 선택사항): 페이지네이션을 위한 결과 오프셋
limit (number, 선택사항): 최대 결과 개수

반환값: CharacterRankingResult - 캐릭터별 랭킹 목록

getTsjRanking(rankingType, offset?, limit?)

TSJ(Team vs Team) 랭킹을 가져옵니다.

엔드포인트: GET /cy/ranking/tsj

const tsjRanking = await cyphersClient.getTsjRanking('melee', 0, 50);

매개변수:

rankingType (string): TSJ 랭킹 타입 ('melee', 'ranged')
offset (number, 선택사항): 페이지네이션을 위한 결과 오프셋
limit (number, 선택사항): 최대 결과 개수

반환값: TsjRankingResult - TSJ 랭킹 목록

아이템 메서드

searchCyphersItems()

사용 가능한 모든 아이템 목록을 검색합니다.

엔드포인트: GET /cy/battleitems/items

const items = await cyphersClient.searchCyphersItems();

반환값: Item[] - 기본 정보가 포함된 모든 아이템 목록

getCyphersInfo()

사이퍼즈 게임 정보를 가져옵니다.

엔드포인트: GET /cy/cyphers

const cyphersInfo = await cyphersClient.getCyphersInfo();

반환값: CyphersInfo - 사이퍼즈 게임 관련 정보

아이템 상세 메서드

getCyphersItemDetail(itemId)

아이템의 상세 정보를 가져옵니다.

엔드포인트: GET /cy/battleitems/items/{itemId}

const itemDetail = await cyphersClient.getCyphersItemDetail('itemId');

매개변수:

itemId (string): 아이템 식별자

반환값: ItemDetail - 상세 아이템 정보 및 스탯

getCyphersMultiItems(itemIds)

여러 아이템 정보를 한 번에 가져옵니다.

엔드포인트: GET /cy/multi/items

const items = await cyphersClient.getCyphersMultiItems([
  'itemId1',
  'itemId2',
  'itemId3',
]);

매개변수:

itemIds (string[]): 아이템 식별자 배열

반환값: ItemDetail[] - 여러 아이템의 상세 정보

오류 처리

모든 메서드는 다양한 이유로 오류를 발생시킬 수 있습니다:

try {
  const player = await cyphersClient.getPlayerInfo('invalidId');
} catch (error) {
  if (error.status === 404) {
    console.log('플레이어를 찾을 수 없습니다');
  } else if (error.status === 401) {
    console.log('잘못된 API 키입니다');
  } else {
    console.error('API 오류:', error.message);
  }
}

사용 예시

import { NeopleCyphersClient } from 'neople-sdk-js';

async function getPlayerStats(playerName: string) {
  const cyphersClient = new NeopleCyphersClient(
    process.env.NEOPLE_CYPHERS_API_KEY
  );

  try {
    // 플레이어 검색
    const searchResults = await cyphersClient.searchPlayer(playerName);

    if (searchResults.rows.length === 0) {
      console.log('플레이어를 찾을 수 없습니다');
      return;
    }

    const playerId = searchResults.rows[0].playerId;

    // 플레이어 세부 정보와 최근 경기 조회
    const [player, matches] = await Promise.all([
      cyphersClient.getPlayerInfo(playerId),
      cyphersClient.getPlayerMatches(playerId, { gameTypeId: 'rating', limit: 10 }),
    ]);

    console.log('플레이어:', player);
    console.log('최근 경기:', matches);
  } catch (error) {
    console.error('오류:', error.message);
  }
}

async function analyzeMatch(matchId: string) {
  const cyphersClient = new NeopleCyphersClient(
    process.env.NEOPLE_CYPHERS_API_KEY
  );

  try {
    const match = await cyphersClient.getMatchDetail(matchId);

    console.log('경기 시간:', match.playTime);
    console.log(
      '승자:',
      match.teams.find(team => team.result === 'win')
    );

    // 게임 정보 조회
    const cyphersInfo = await cyphersClient.getCyphersInfo();
    console.log('사이퍼즈 게임 정보:', cyphersInfo);
  } catch (error) {
    console.error('오류:', error.message);
  }
}

게임 타입

일반적인 게임 타입 식별자:

normal: 일반 경기
rating: 랭킹 경기
tutorial: 튜토리얼 경기
custom: 커스텀 경기

경기 결과 구조

경기 결과에 포함되는 정보:

플레이어 정보 및 통계
캐릭터 선택 및 빌드
팀 구성
경기 시간 및 결과
개별 플레이어 성능 지표

사이퍼즈 API

On this page