XBRL 파싱에 지쳐서, SEC EDGAR API를 만들었습니다

Source: Dev.to

소개

SEC의 EDGAR 시스템에서 재무 데이터를 끌어오려고 시도해 본 적이 있다면, 어디로 가는지 이미 짐작할 수 있을 겁니다.

저는 주식 스크리너를 만들고 싶었습니다. 간단한 아이디어 — 몇몇 기업의 매출 추세만 보여주면 됩니다. 오후만에 끝날 거라 생각했죠.

아니요. 먼저 기업의 CIK 번호가 필요합니다(Apple은 0000320193 — 10자리로 앞에 0을 채운 이유는 묻지 마세요). 그 다음에는 XBRL 파일을 다운로드해야 하는데, 이는 us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax 같은 네임스페이스를 가진 중첩 XML 형식입니다. 서로 다른 기업들은 같은 개념에 대해 약간씩 다른 태그를 사용하고, 이 전체 과정은 금세 토끼굴이 됩니다.

저는 이 작업에 너무 오래 시간을 잡았기 때문에, 전체를 REST API로 감쌌습니다. 티커를 전달하면 JSON을 반환합니다. 끝났습니다.

회사 정보

GET /v1/company/AAPL

{
  "cik": "320193",
  "ticker": "AAPL",
  "name": "Apple Inc.",
  "sic": "3571",
  "sic_description": "Electronic Computers",
  "fiscal_year_end": "0926",
  "state": "CA"
}

CIK 조회는 필요 없습니다—티커만 사용하세요.

재무제표

GET /v1/financials/AAPL?statement=income_statement&limit=3

{
  "ticker": "AAPL",
  "name": "Apple Inc.",
  "statements": {
    "income_statement": [
      {
        "concept": "revenue",
        "label": "Revenue from Contract with Customer",
        "unit": "USD",
        "data": [
          {
            "fiscal_year": 2025,
            "fiscal_period": "FY",
            "value": 383285000000.0,
            "filed": "2025-10-31",
            "form": "10-K"
          }
        ]
      }
    ]
  }
}

매출, 순이익, EPS, 영업비용 — XBRL에서 추출하는 데 몇 시간을 들였던 모든 내용이 이제 한 번의 호출로 제공됩니다.

파이썬으로 Apple 매출 가져오기

import requests

url = "https://sec-edgar-data-api.p.rapidapi.com/v1/financials/AAPL"
headers = {
    "x-rapidapi-key": "YOUR_API_KEY",
    "x-rapidapi-host": "sec-edgar-data-api.p.rapidapi.com"
}
params = {"statement": "income_statement", "limit": 5}

response = requests.get(url, headers=headers, params=params)
data = response.json()

for item in data["statements"]["income_statement"]:
    if item["concept"] == "revenue":
        for year in item["data"]:
            print(f"FY{year['fiscal_year']}: ${year['value']:,.0f}")

FY2025: $383,285,000,000
FY2024: $394,328,000,000
FY2023: $365,817,000,000

그 주식 스크리너 얘기했었죠? 드디어 만들었어요.

기타 엔드포인트

기업 검색 (퍼지 매칭)

GET /v1/company?q=tesla

제출 이력 (10‑K, 10‑Q, 8‑K 등)

GET /v1/filings/TSLA?form=10-K&limit=5

재무제표: 대차대조표 및 현금 흐름

GET /v1/financials/MSFT?statement=balance_sheet
GET /v1/financials/MSFT?statement=cash_flow

이 API는 10,000개 이상의 SEC 등록 공개 기업을 모두 다룹니다. 데이터는 SEC EDGAR(data.sec.gov)에서 직접 가져오므로 기업이 제출할 때마다 업데이트됩니다.

기존 API를 그냥 사용하지 않는 이유는?

대부분의 대안은 기본 접근에 월 $50 이상을 청구하거나, 몇 개만 필요할 때 수십 개의 엔드포인트를 노출합니다. 저는 주니어 개발자가 5분 안에 익힐 수 있는 무언가를 원했습니다. 문서가 README보다 길다면, 아마도 너무 복잡한 것입니다.

직접 사용해 보기

RapidAPI 무료 티어 — 월 100회 요청, 신용카드 필요 없음:

SEC EDGAR Data API on RapidAPI

저는 또한 @SECEdgarBot이라는 봇을 운영하고 있습니다. 이 봇은 중요한 서류가 공개될 때 트윗을 보내고 흥미로운 재무 신호를 표시합니다. 아직 초기 단계이지만, 만드는 것이 재미있었습니다.

모든 데이터는 SEC EDGAR(data.sec.gov)에서 가져온 것으로, 공개된 미국 정부 데이터입니다.