본문으로 건너뛰기
QuantanSite

API 레퍼런스

API 문서

이 사이트가 표시하는 것과 동일한 시장 데이터를 제공하는 읽기 전용 JSON API입니다. 성공 응답은 { data, meta } 봉투를 사용하고, 실패 응답은 { error: { code, message } } 를 사용합니다.

기본 URL
http://localhost:3000
메서드
GET 전용
형식
JSON, UTF-8
요청 제한
IP 주소와 엔드포인트당 60초마다 60회 요청

These are API examples. This site is served as static files.

데모
서버가 MARKET_DATA_PROVIDER=fmp 와 FMP_API_KEY 를 함께 설정하지 않는 한, 응답은 가상의 종목을 사용하는 결정론적 데모 데이터셋에서 반환됩니다. 모든 응답의 meta.provider 필드는 어떤 소스가 응답했는지 보여줍니다.

시세 목록

GET/api/quotes

종목을 평면 배열로 한 페이지 반환하며, meta에 total, page, pageSize가 포함됩니다. 아래의 모든 스크리너 필터가 여기에서도 동작합니다. 해석할 수 없는 값은 무시됩니다.

매개변수

매개변수위치유형필수설명
sectorquerystring선택정확한 섹터 이름: Technology, Healthcare, Financials, Consumer Discretionary, Consumer Staples, Industrials, Energy, Materials, Utilities, Real Estate.
sortquerystring선택정렬 필드: marketCap(기본값), price, changePercent, volume 또는 symbol.
orderquerystring선택정렬 순서: desc(기본값) 또는 asc.
pagequerynumber선택페이지 번호이며 1부터 시작합니다.
pageSizequerynumber선택페이지당 행 수: 기본값은 20, 최대 100.

요청

curl -s "http://localhost:3000/api/quotes?pageSize=3"

응답 예시

200application/json

{
  "data": [
    {
      "symbol": "NWRB",
      "name": "Northwind Robotics",
      "exchange": "NASDAQ",
      "sector": "Technology",
      "industry": "Industrial Automation",
      "price": 733.8,
      "change": -16.52,
      "changePercent": -2.2,
      "previousClose": 750.32,
      "open": 750.03,
      "dayHigh": 751.29,
      "dayLow": 731.5,
      "volume": 3471317,
      "avgVolume": 2962633,
      "marketCap": 982258754565,
      "peRatio": 60.35,
      "eps": 12.16,
      "dividendYield": null,
      "week52High": 963.99,
      "week52Low": 583.89,
      "afterHoursPrice": 731,
      "afterHoursChangePercent": -0.38,
      "updatedAt": "2026-11-12T21:00:00.000Z"
    }
  ],
  "meta": {
    "provider": "demo",
    "generatedAt": "2026-11-12T21:00:04.512Z",
    "disclaimer": "Demo dataset: fictional issuers and simulated prices. Not investment advice.",
    "total": 20,
    "page": 1,
    "pageSize": 3
  }
}

예시는 한 행으로 축약했습니다.

시세 조회

GET/api/quotes/{symbol}

하나의 종목 또는 지수에 대한 전체 시세를 반환합니다. 알 수 없는 symbol은 404 not_found를 반환합니다.

매개변수

매개변수위치유형필수설명
symbolpathstring필수종목 또는 지수 symbol이며, 예를 들어 NWRB 입니다. 대소문자를 구분하지 않습니다.

요청

curl -s "http://localhost:3000/api/quotes/NWRB"

응답 예시

200application/json

{
  "data": {
    "symbol": "NWRB",
    "name": "Northwind Robotics",
    "exchange": "NASDAQ",
    "sector": "Technology",
    "industry": "Industrial Automation",
    "price": 733.8,
    "change": -16.52,
    "changePercent": -2.2,
    "previousClose": 750.32,
    "open": 750.03,
    "dayHigh": 751.29,
    "dayLow": 731.5,
    "volume": 3471317,
    "avgVolume": 2962633,
    "marketCap": 982258754565,
    "peRatio": 60.35,
    "eps": 12.16,
    "dividendYield": null,
    "week52High": 963.99,
    "week52Low": 583.89,
    "afterHoursPrice": 731,
    "afterHoursChangePercent": -0.38,
    "updatedAt": "2026-11-12T21:00:00.000Z"
  },
  "meta": {
    "provider": "demo",
    "generatedAt": "2026-11-12T21:00:04.512Z",
    "disclaimer": "Demo dataset: fictional issuers and simulated prices. Not investment advice."
  }
}

캔들 조회

GET/api/candles/{symbol}

OHLCV 캔들을 오래된 순서로 반환합니다. 1D 범위는 30-minute 간격을 사용하고, 다른 모든 범위는 일봉을 사용합니다. 알 수 없는 범위는 400 bad_request를 반환합니다.

매개변수

매개변수위치유형필수설명
symbolpathstring필수종목 또는 지수 symbol이며, 예를 들어 NWRB 입니다. 대소문자를 구분하지 않습니다.
rangequerystring선택1D, 5D, 1M, 6M, 1Y, 5Y 중 하나입니다. 기본값은 1M입니다.

요청

curl -s "http://localhost:3000/api/candles/NWRB?range=1M"

응답 예시

200application/json

{
  "data": [
    {
      "time": "2026-11-11",
      "open": 757.4,
      "high": 761.18,
      "low": 743.92,
      "close": 750.32,
      "volume": 3531710
    },
    {
      "time": "2026-11-12",
      "open": 750.03,
      "high": 751.29,
      "low": 731.5,
      "close": 733.8,
      "volume": 3471317
    }
  ],
  "meta": {
    "provider": "demo",
    "generatedAt": "2026-11-12T21:00:04.512Z",
    "disclaimer": "Demo dataset: fictional issuers and simulated prices. Not investment advice.",
    "symbol": "NWRB",
    "range": "1M"
  }
}

예시는 두 개의 캔들로 축약했습니다. 1M은 22개를 반환합니다.

종목 스크리닝

GET/api/screener

스크리너 페이지와 동일한 매개변수로 종목을 필터링하고 정렬하고 페이지로 나눕니다. 결과에는 rows와 함께 total, page, pageSize가 포함됩니다. 해석할 수 없는 값은 무시됩니다.

매개변수

매개변수위치유형필수설명
sectorquerystring선택정확한 섹터 이름: Technology, Healthcare, Financials, Consumer Discretionary, Consumer Staples, Industrials, Energy, Materials, Utilities, Real Estate.
minMarketCap, maxMarketCapquerynumber선택USD 기준 시가총액 범위입니다.
minPrice, maxPricequerynumber선택USD 기준 가격 범위입니다.
minChangePercent, maxChangePercentquerynumber선택퍼센트 포인트 단위의 일간 변동 범위입니다. -3은 -3%를 의미합니다.
minVolumequerynumber선택주식 수 기준 최소 일간 거래량입니다.
profitableOnlyquerystring선택1로 설정하면 EPS가 0보다 큰 종목만 남깁니다.
sortquerystring선택정렬 필드: marketCap(기본값), price, changePercent, volume 또는 symbol.
orderquerystring선택정렬 순서: desc(기본값) 또는 asc.
pagequerynumber선택페이지 번호이며 1부터 시작합니다.
pageSizequerynumber선택페이지당 행 수: 기본값은 20, 최대 100.

요청

curl -s "http://localhost:3000/api/screener?profitableOnly=1&pageSize=5"

응답 예시

200application/json

{
  "data": {
    "rows": [
      {
        "symbol": "NWRB",
        "name": "Northwind Robotics",
        "exchange": "NASDAQ",
        "sector": "Technology",
        "industry": "Industrial Automation",
        "price": 733.8,
        "change": -16.52,
        "changePercent": -2.2,
        "previousClose": 750.32,
        "open": 750.03,
        "dayHigh": 751.29,
        "dayLow": 731.5,
        "volume": 3471317,
        "avgVolume": 2962633,
        "marketCap": 982258754565,
        "peRatio": 60.35,
        "eps": 12.16,
        "dividendYield": null,
        "week52High": 963.99,
        "week52Low": 583.89,
        "afterHoursPrice": 731,
        "afterHoursChangePercent": -0.38,
        "updatedAt": "2026-11-12T21:00:00.000Z"
      }
    ],
    "total": 17,
    "page": 1,
    "pageSize": 5
  },
  "meta": {
    "provider": "demo",
    "generatedAt": "2026-11-12T21:00:04.512Z",
    "disclaimer": "Demo dataset: fictional issuers and simulated prices. Not investment advice.",
    "total": 17,
    "page": 1,
    "pageSize": 5
  }
}

예시는 한 행으로 축약했습니다.

인증

데모 모드에서는 키가 필요하지 않습니다. 서버가 API_KEY 환경 변수를 설정하면 모든 요청은 X-API-Key 헤더에 동일한 값을 보내야 합니다. 그 외의 경우에는 401 unauthorized 를 받습니다.

curl -s "http://localhost:3000/api/quotes/NWRB" \
  -H "X-API-Key: your-key-here"
참고
키는 서버에서만 읽힙니다. 이 페이지의 요청 보내기 버튼은 브라우저에서 키 없이 API를 호출하므로, 키 인증이 활성화된 동안에는 401을 반환합니다.

오류 코드

실패한 요청은 해당하는 HTTP 상태와 하나의 오류 객체를 반환합니다. 분기는 code 로 하고, message 는 사람을 위해 작성되었으며 변경될 수 있습니다.

{
  "error": {
    "code": "not_found",
    "message": "A human-readable explanation."
  }
}
HTTP 상태코드발생 시점
400bad_request매개변수 값이 허용되지 않습니다. 예를 들어 알 수 없는 캔들 범위입니다.
401unauthorizedAPI_KEY 가 설정되어 있는데 요청에 일치하는 X-API-Key 헤더가 없습니다.
404not_found해당 symbol이 데이터셋에 없습니다.
405method_not_allowedAPI는 읽기 전용입니다: /api/quotes 는 POST 요청에 이 코드로 응답합니다.
429rate_limited하나의 IP 주소에서 하나의 엔드포인트로 60초 내에 60회를 초과한 경우입니다. 응답에는 Retry-After가 초 단위로 포함됩니다.

제품에서 같은 데이터 확인하기

시장 개요, 시세 페이지, 스크리너는 이 엔드포인트들과 동일한 공급자에서 데이터를 읽습니다.