Foresto Compass API
Compass Score, 재무/밸류에이션/기술적 분석, 종목 스크리너 등 한국 주식 시장 데이터를 프로그래밍 방식으로 활용할 수 있는 RESTful API입니다.
Base URLhttps://api.foresto.co.kr/b2b/api/v1
Quick Start
1
API 키 발급
B2B 계약 후 관리자로부터 fc_ 접두사의 API 키를 발급받습니다.
2
첫 요청 보내기
X-API-Key 헤더에 키를 포함하여 요청합니다.
3
응답 확인
JSON 응답의 data 필드에서 결과를 확인합니다.
bash
curl -X GET "https://api.foresto.co.kr/b2b/api/v1/compass/005930" \
-H "X-API-Key: fc_YOUR_API_KEY"인증 (Authentication)
모든 요청에 X-API-Key HTTP 헤더를 포함해야 합니다. API 키는 fc_ 접두사 + 32자리 hex 문자열 형식입니다.
http
X-API-Key: fc_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4API 키는 발급 시 1회만 표시됩니다. 분실 시 새 키를 발급받아야 합니다. 키를 소스 코드에 직접 포함하지 말고 환경 변수로 관리하세요.
인증 에러
| Status | Code | 설명 |
|---|---|---|
| 401 | INVALID_API_KEY | 키가 없거나 형식이 잘못된 경우 |
| 401 | API_KEY_EXPIRED | 키의 유효기간이 만료된 경우 |
| 403 | CLIENT_SUSPENDED | 클라이언트 계정이 정지된 경우 |
| 403 | INSUFFICIENT_SCOPE | 해당 엔드포인트에 필요한 스코프가 없는 경우 |
스코프 (Scopes)
각 API 키에는 접근 가능한 엔드포인트를 제어하는 스코프가 할당됩니다. 와일드카드 매칭(analysis:*)도 지원합니다.
| Scope | Endpoints |
|---|---|
| compass:read | /compass/*, /compass/batch |
| analysis:financial | /analysis/financial/* |
| analysis:valuation | /analysis/valuation/* |
| analysis:technical | /analysis/technical/* |
| analysis:* | 모든 analysis 엔드포인트 |
| screener:read | /screener |
| market:read | /market/overview |
엔드포인트 레퍼런스
총 8개의 엔드포인트를 제공합니다. 각 카드를 클릭하면 파라미터, 코드 예제, 응답 예제를 확인할 수 있습니다.
GET/compass/{ticker}단일 Compass Score 조회▼
POST/compass/batch배치 Compass Score 조회▼
GET/analysis/financial/{ticker}재무 분석▼
GET/analysis/valuation/{ticker}밸류에이션 분석▼
GET/analysis/technical/{ticker}기술적 분석▼
POST/screener종목 스크리너▼
GET/market/overview시장 개요▼
GET/usage사용량 조회▼
요금제
Basic
300,000 원/월
- 일 100건 / 월 3,000건
- 초당 5건 burst
- 배치 최대 10건
- Compass Score + 스크리너
Pro
1,000,000 원/월
- 일 1,000건 / 월 30,000건
- 초당 10건 burst
- 배치 최대 50건
- 전체 분석 + 시장 개요
Enterprise
3,000,000 원/월
- 일 10,000건 / 월 300,000건
- 초당 30건 burst
- 배치 최대 200건
- 전체 스코프 + 전담 지원
Rate Limiting
3단계 rate limit이 적용됩니다. 초과 시 429 Too Many Requests가 반환됩니다.
Burst (Token Bucket)
초당 요청 수 제한. Basic 5/sec, Pro 10/sec, Enterprise 30/sec. 토큰 자동 보충.
Daily
일일 요청 수 제한. KST 00:00 기준 리셋. Basic 100, Pro 1,000, Enterprise 10,000.
Monthly
월간 요청 수 제한. 매월 1일 KST 00:00 기준 리셋. Basic 3,000, Pro 30,000, Enterprise 300,000.
응답 헤더
매 응답에 현재 사용량 정보가 포함됩니다.
http
X-RateLimit-Limit-Daily: 1000
X-RateLimit-Remaining-Daily: 958
X-RateLimit-Limit-Monthly: 30000
X-RateLimit-Remaining-Monthly: 28750에러 코드
| Status | Code | 설명 | 대응 방법 |
|---|---|---|---|
| 400 | BATCH_SIZE_EXCEEDED | 배치 크기 초과 | 요금제별 최대 배치 크기 확인 |
| 401 | INVALID_API_KEY | 유효하지 않은 API 키 | 키 형식(fc_ + 32hex) 확인 |
| 401 | API_KEY_EXPIRED | API 키 만료 | 새 키 발급 요청 |
| 403 | CLIENT_SUSPENDED | 계정 정지됨 | 관리자에게 문의 |
| 403 | INSUFFICIENT_SCOPE | 스코프 부족 | 요금제 업그레이드 또는 키 스코프 확인 |
| 404 | - | 티커 미발견 | 종목 코드(6자리) 확인 |
| 429 | RATE_LIMIT_EXCEEDED | 요청 한도 초과 | Retry-After 헤더 확인 후 재시도 |
| 500 | - | 서버 내부 오류 | 잠시 후 재시도, 지속 시 문의 |
에러 응답 형식
json
{
"detail": "Rate limit exceeded (daily)"
}응답 형식
모든 성공 응답은 다음 표준 envelope 형식을 따릅니다.
json
{
"success": true,
"data": { ... },
"meta": {
"api_version": "v1",
"request_id": "req_a1b2c3d4e5f6",
"timestamp": "2026-03-02T12:34:56",
"rate_limit": {
"daily_limit": 1000,
"daily_remaining": 958,
"monthly_limit": 30000,
"monthly_remaining": 28750
}
},
"disclaimer": "교육 목적 참고 정보이며 투자 권유가 아닙니다"
}| Field | Type | Description |
|---|---|---|
| success | boolean | 요청 성공 여부 |
| data | object | array | 응답 데이터 (에러 시 null) |
| meta | object | API 버전, 요청 ID, 타임스탬프, rate limit 정보 |
| disclaimer | string | 법적 면책 고지 |