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 필드는 어떤 소스가 응답했는지 보여줍니다.시세 목록
/api/quotes종목을 평면 배열로 한 페이지 반환하며, meta에 total, page, pageSize가 포함됩니다. 아래의 모든 스크리너 필터가 여기에서도 동작합니다. 해석할 수 없는 값은 무시됩니다.
매개변수
| 매개변수 | 위치 | 유형 | 필수 | 설명 |
|---|---|---|---|---|
| sector | query | string | 선택 | 정확한 섹터 이름: Technology, Healthcare, Financials, Consumer Discretionary, Consumer Staples, Industrials, Energy, Materials, Utilities, Real Estate. |
| sort | query | string | 선택 | 정렬 필드: marketCap(기본값), price, changePercent, volume 또는 symbol. |
| order | query | string | 선택 | 정렬 순서: desc(기본값) 또는 asc. |
| page | query | number | 선택 | 페이지 번호이며 1부터 시작합니다. |
| pageSize | query | number | 선택 | 페이지당 행 수: 기본값은 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
}
}예시는 한 행으로 축약했습니다.
시세 조회
/api/quotes/{symbol}하나의 종목 또는 지수에 대한 전체 시세를 반환합니다. 알 수 없는 symbol은 404 not_found를 반환합니다.
매개변수
| 매개변수 | 위치 | 유형 | 필수 | 설명 |
|---|---|---|---|---|
| symbol | path | string | 필수 | 종목 또는 지수 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."
}
}캔들 조회
/api/candles/{symbol}OHLCV 캔들을 오래된 순서로 반환합니다. 1D 범위는 30-minute 간격을 사용하고, 다른 모든 범위는 일봉을 사용합니다. 알 수 없는 범위는 400 bad_request를 반환합니다.
매개변수
| 매개변수 | 위치 | 유형 | 필수 | 설명 |
|---|---|---|---|---|
| symbol | path | string | 필수 | 종목 또는 지수 symbol이며, 예를 들어 NWRB 입니다. 대소문자를 구분하지 않습니다. |
| range | query | string | 선택 | 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개를 반환합니다.
종목 스크리닝
/api/screener스크리너 페이지와 동일한 매개변수로 종목을 필터링하고 정렬하고 페이지로 나눕니다. 결과에는 rows와 함께 total, page, pageSize가 포함됩니다. 해석할 수 없는 값은 무시됩니다.
매개변수
| 매개변수 | 위치 | 유형 | 필수 | 설명 |
|---|---|---|---|---|
| sector | query | string | 선택 | 정확한 섹터 이름: Technology, Healthcare, Financials, Consumer Discretionary, Consumer Staples, Industrials, Energy, Materials, Utilities, Real Estate. |
| minMarketCap, maxMarketCap | query | number | 선택 | USD 기준 시가총액 범위입니다. |
| minPrice, maxPrice | query | number | 선택 | USD 기준 가격 범위입니다. |
| minChangePercent, maxChangePercent | query | number | 선택 | 퍼센트 포인트 단위의 일간 변동 범위입니다. -3은 -3%를 의미합니다. |
| minVolume | query | number | 선택 | 주식 수 기준 최소 일간 거래량입니다. |
| profitableOnly | query | string | 선택 | 1로 설정하면 EPS가 0보다 큰 종목만 남깁니다. |
| sort | query | string | 선택 | 정렬 필드: marketCap(기본값), price, changePercent, volume 또는 symbol. |
| order | query | string | 선택 | 정렬 순서: desc(기본값) 또는 asc. |
| page | query | number | 선택 | 페이지 번호이며 1부터 시작합니다. |
| pageSize | query | number | 선택 | 페이지당 행 수: 기본값은 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"오류 코드
실패한 요청은 해당하는 HTTP 상태와 하나의 오류 객체를 반환합니다. 분기는 code 로 하고, message 는 사람을 위해 작성되었으며 변경될 수 있습니다.
{
"error": {
"code": "not_found",
"message": "A human-readable explanation."
}
}| HTTP 상태 | 코드 | 발생 시점 |
|---|---|---|
| 400 | bad_request | 매개변수 값이 허용되지 않습니다. 예를 들어 알 수 없는 캔들 범위입니다. |
| 401 | unauthorized | API_KEY 가 설정되어 있는데 요청에 일치하는 X-API-Key 헤더가 없습니다. |
| 404 | not_found | 해당 symbol이 데이터셋에 없습니다. |
| 405 | method_not_allowed | API는 읽기 전용입니다: /api/quotes 는 POST 요청에 이 코드로 응답합니다. |
| 429 | rate_limited | 하나의 IP 주소에서 하나의 엔드포인트로 60초 내에 60회를 초과한 경우입니다. 응답에는 Retry-After가 초 단위로 포함됩니다. |