Benzinga Node.js SDK - Benzinga API Documentation

개요

Benzinga TypeScript/JavaScript SDK는 Benzinga API와 상호작용하기 위한 모듈식, 이벤트 기반 인터페이스를 제공합니다. TypeScript로 작성된 이 SDK는 브라우저와 Node.js 환경 모두에서 원활하게 동작하며, 캐싱, 깊은 비교(deep comparison) 및 기타 고급 기능을 포함한 향상된 구현을 제공합니다.

주요 기능

TypeScript 지원 - 완전한 TypeScript 타입과 인터페이스 제공
범용 - 브라우저와 Node.js 환경 모두에서 동작
모듈형 아키텍처 - 필요한 모듈만 설치 가능
이벤트 기반 - 실시간 데이터를 위한 반응형 프로그래밍 패턴
고급 기능 - 내장 캐싱, 깊은 비교, 각종 최적화 기능
최신 - async/await를 지원하는 ES6+ 문법

요구 사항

Node.js 14 이상

설치

SDK는 모듈형 아키텍처를 사용합니다. 먼저 핵심 세션 모듈을 설치하세요:

npm install @benzinga/session

그다음 필요에 따라 추가 모듈을 설치하세요:

# 예제: 특정 모듈 설치
npm install @benzinga/calendar-data
npm install @benzinga/quotes
npm install @benzinga/news-data

시작하기

세션 설정

@benzinga/session 모듈은 Benzinga API 인증을 위한 기반을 제공합니다. 다른 모든 모듈은 이 Session 객체에 의존합니다.

import { Session } from '@benzinga/session';

// API 키를 사용하여 세션 초기화
const session = new Session({
  apiKey: 'YOUR_API_KEY'
});

구성 옵션

Session 객체는 동작을 사용자 정의하기 위한 다양한 구성 옵션을 허용합니다:

const session = new Session({
  apiKey: 'YOUR_API_KEY',
  environment: 'production', // 또는 'sandbox'
  timeout: 30000,            // 요청 타임아웃(밀리초 단위)
  // 추가 구성 옵션
});

핵심 개념

모듈형 설계

각 Benzinga API 도메인은 별도의 npm 모듈로 패키징됩니다. 이를 통해 다음과 같은 일을 할 수 있습니다:

필요한 모듈만 설치
번들 크기 축소
관심사를 명확히 분리
모듈을 독립적으로 업데이트

이벤트 기반 아키텍처

SDK는 실시간 데이터 스트림 및 업데이트를 처리하기 위해 이벤트 기반 패턴을 사용합니다:

// 예시: 데이터 업데이트 구독
dataManager.subscribe((data) => {
  console.log('New data received:', data);
});

// Example: Handle events
dataManager.on('update', (event) => {
  console.log('Data updated:', event);
});

캐싱 및 성능

SDK에는 다음을 위한 내장 캐싱 메커니즘이 포함되어 있습니다:

불필요한 API 호출 감소
응답 시간 개선
대역폭 사용 최적화
오프라인 대체 기능 제공

심층 비교

고급 데이터 비교 기능을 통해 다음을 수행할 수 있습니다:

중첩 객체 변경 사항 감지
효율적인 상태 관리
스마트한 업데이트 트리거
UI 애플리케이션에서 불필요한 리렌더링 감소

사용 가능한 모듈

SDK는 각기 다른 API 도메인에 맞춰 특화된 모듈로 구성되어 있습니다.

코어 모듈

@benzinga/session - 인증 및 세션 관리 (필수)
@benzinga/calendar-data - 캘린더 이벤트 및 기업 행동
@benzinga/news-data - 뉴스 기사 및 시장 정보
@benzinga/quotes - 실시간 및 지연 시세
@benzinga/fundamentals - 기업 기초 재무 지표 및 재무 데이터

전용 모듈

@benzinga/ratings - 애널리스트 등급 및 목표가
@benzinga/options - 옵션 거래 동향 및 분석
@benzinga/transcripts - 실적 발표 콜 녹취록
@benzinga/logos - 기업 로고 및 브랜딩
@benzinga/signals - 거래 시그널 및 지표

TypeScript 지원

이 SDK는 TypeScript로 작성되었으며 완전한 타입 정의를 제공합니다:

import { Session } from '@benzinga/session';
import { CalendarData, DividendEvent } from '@benzinga/calendar-data';

// TypeScript는 자동 완성 및 타입 검사를 제공합니다
const session = new Session({ apiKey: 'YOUR_API_KEY' });
const calendar = new CalendarData(session);

// 타입 안전 API 호출
const dividends: DividendEvent[] = await calendar.getDividends({
  dateFrom: '2024-01-01',
  dateTo: '2024-12-31',
  ticker: 'AAPL'
});

사용 예제

기본 데이터 조회

import { Session } from '@benzinga/session';
import { NewsData } from '@benzinga/news-data';

const session = new Session({ apiKey: 'YOUR_API_KEY' });
const news = new NewsData(session);

// 최신 뉴스 가져오기
const articles = await news.getNews({
  pageSize: 10,
  displayOutput: 'full'
});

console.log(articles);

실시간 데이터 스트림

import { Session } from '@benzinga/session';
import { QuoteStream } from '@benzinga/quotes';

const session = new Session({ apiKey: 'YOUR_API_KEY' });
const quoteStream = new QuoteStream(session);

// 실시간 시세 구독
quoteStream.subscribe(['AAPL', 'MSFT', 'GOOGL'], (quote) => {
  console.log('Quote update:', quote);
});

// 완료되면 구독 해제
quoteStream.unsubscribe(['AAPL']);

calendar 이벤트

import { Session } from '@benzinga/session';
import { CalendarData } from '@benzinga/calendar-data';

const session = new Session({ apiKey: 'YOUR_API_KEY' });
const calendar = new CalendarData(session);

// 예정된 실적 조회
const earnings = await calendar.getEarnings({
  dateFrom: '2024-01-01',
  dateTo: '2024-01-31',
  importance: 3  // 높은 중요도만 해당
});

// 배당 정보 조회
const dividends = await calendar.getDividends({
  ticker: 'AAPL'
});

기업의 기초 재무 지표

import { Session } from '@benzinga/session';
import { Fundamentals } from '@benzinga/fundamentals';

const session = new Session({ apiKey: 'YOUR_API_KEY' });
const fundamentals = new Fundamentals(session);

// 회사 프로필 가져오기
const profile = await fundamentals.getCompanyProfile('AAPL');

// 밸류에이션 비율 가져오기
const valuationRatios = await fundamentals.getValuationRatios('AAPL');

// 재무제표 가져오기
const financials = await fundamentals.getFinancials('AAPL');

브라우저에서 사용

SDK는 Webpack, Rollup, Vite와 같은 번들러를 사용하는 브라우저 환경에서도 동작합니다.

// React, Vue 또는 Angular 애플리케이션에서
import { Session } from '@benzinga/session';
import { NewsData } from '@benzinga/news-data';

export function NewsComponent() {
  const session = new Session({ apiKey: process.env.BENZINGA_API_KEY });
  const news = new NewsData(session);

  // 컴포넌트 로직에서 사용
  useEffect(() => {
    news.getNews({ pageSize: 5 }).then(articles => {
      setNewsData(articles);
    });
  }, []);
}

오류 처리

try-catch 블록으로 오류를 적절히 처리하세요:

import { Session } from '@benzinga/session';
import { NewsData } from '@benzinga/news-data';

const session = new Session({ apiKey: 'YOUR_API_KEY' });
const news = new NewsData(session);

try {
  const articles = await news.getNews({ pageSize: 10 });
  console.log(articles);
} catch (error) {
  if (error.code === 'UNAUTHORIZED') {
    console.error('잘못된 API 키');
  } else if (error.code === 'RATE_LIMIT') {
    console.error('속도 제한 초과됨');
  } else {
    console.error('오류 발생:', error.message);
  }
}

페이지네이션

페이지네이션 결과를 효율적으로 처리하십시오:

import { Session } from '@benzinga/session';
import { NewsData } from '@benzinga/news-data';

const session = new Session({ apiKey: 'YOUR_API_KEY' });
const news = new NewsData(session);

// 여러 페이지 가져오기
let page = 0;
let allArticles = [];

while (page < 5) {
  const articles = await news.getNews({
    page: page,
    pageSize: 100
  });

  if (articles.length === 0) break;

  allArticles = allArticles.concat(articles);
  page++;
}

console.log(`Fetched ${allArticles.length} articles`);

캐싱 전략

성능 향상을 위해 내장된 캐싱 기능을 활용하세요:

import { Session } from '@benzinga/session';
import { CalendarData } from '@benzinga/calendar-data';

const session = new Session({
  apiKey: 'YOUR_API_KEY',
  cache: {
    enabled: true,
    ttl: 300000  // 5분간 캐시
  }
});

const calendar = new CalendarData(session);

// 첫 번째 호출은 API 요청
const earnings1 = await calendar.getEarnings({ ticker: 'AAPL' });

// 두 번째 호출은 캐시된 데이터 사용(TTL 내인 경우)
const earnings2 = await calendar.getEarnings({ ticker: 'AAPL' });

모범 사례

1. 세션 객체 재사용

애플리케이션 전역에서 재사용할 세션 인스턴스를 하나만 생성하세요:

// session.ts
export const globalSession = new Session({ apiKey: process.env.BENZINGA_API_KEY });

// 다른 파일들에서
import { globalSession } from './session';
const news = new NewsData(globalSession);

2. 환경 변수

API 키를 환경 변수에 안전하게 저장하세요.

// .env 파일
BENZINGA_API_KEY=your_api_key_here

// 코드 내
const session = new Session({
  apiKey: process.env.BENZINGA_API_KEY
});

3. 타입 안전성

타입 안전한 API 상호 작용을 위해 TypeScript를 활용하십시오:

import type { NewsArticle, NewsParams } from '@benzinga/news-data';

const params: NewsParams = {
  pageSize: 10,
  displayOutput: 'full',
  ticker: 'AAPL'
};

const articles: NewsArticle[] = await news.getNews(params);

4. 에러 바운더리

프로덕션 환경에서는 에러 바운더리를 구현하십시오.

const safeApiCall = async (fn: () => Promise<any>) => {
  try {
    return await fn();
  } catch (error) {
    console.error('API Error:', error);
    // 오류 추적 서비스에 로그 기록
    return null;
  }
};

const articles = await safeApiCall(() => news.getNews({ pageSize: 10 }));

리소스

저장소(Repository): github.com/Benzinga/benzinga-javascript-client
npm 패키지: @benzinga/session
API 키: cloud.benzinga.com
TypeScript: 버전 4.0 이상
Node.js: 버전 14 이상

모듈 문서

특정 모듈에 대한 자세한 내용은 각 패키지의 README를 참조하십시오:

@benzinga/session - 핵심 인증 및 구성
@benzinga/calendar-data - calendar 이벤트 API
@benzinga/news-data - 뉴스 및 기사 API
@benzinga/quotes - 실시간 시세 API
@benzinga/fundamentals - 기초 재무 지표 및 재무 정보 API

지원

기술 지원이나 API 키 발급이 필요하면 cloud.benzinga.com에서 Benzinga에 문의하세요.

기여하기

Benzinga JavaScript SDK는 오픈 소스입니다. 누구나 기여하실 수 있습니다. 자세한 내용은 GitHub 저장소를 방문하세요.

​개요

​주요 기능

​요구 사항

​설치

​시작하기

​세션 설정

​구성 옵션

​핵심 개념

​모듈형 설계

​이벤트 기반 아키텍처

​캐싱 및 성능

​심층 비교

​사용 가능한 모듈

​코어 모듈

​전용 모듈

​TypeScript 지원

​사용 예제

​기본 데이터 조회

​실시간 데이터 스트림

​calendar 이벤트

​기업의 기초 재무 지표

​브라우저에서 사용

​오류 처리

​페이지네이션

​캐싱 전략

​모범 사례

​1. 세션 객체 재사용

​2. 환경 변수

​3. 타입 안전성

​4. 에러 바운더리

​리소스

​모듈 문서

​지원

​기여하기

개요