Earning Samurai — 글로벌 실적발표 캘린더

미국 · 일본 · 홍콩 상장사의 실적발표 일정을 주(週) 단위로 보는 단일 HTML 페이지. 레이아웃은 EarningsHub 주간 캘린더를, 디자인은 taiwan-it-revenue를 따랐다.

https://cbturbomax.github.io/Earning-Samurai-Calendar/

구성

파일	역할
scrape.py	🇯🇵 닛케이 결산발표 스케줄 → data/earnings.json
scrape_us.py	🇺🇸 나스닥 실적발표 캘린더 → data/earnings_us.json
scrape_hk.py	🇭🇰 HKEXnews 실적 공시 → data/earnings_hk.json
markets.py	시장 레지스트리 — 라벨·색·휴장일·표기 대역표
companies.py / companies_us.py / companies_hk.py	시장별 주목종목 사전
translit.py	일본 회사명 → 한글 표기 변환기
build.py	data/*.json 셋을 합쳐 → index.html
index.html	산출물. 외부 의존 없는 단일 파일 (폰트 CDN만 사용)

표준 라이브러리만 쓴다. pip install 필요 없음.

쓰는 법

python scrape.py    2026-07-20 2026-09-30   # 일본
python scrape_us.py 2026-07-20 2026-09-30   # 미국
python scrape_hk.py 2026-07-20 2026-09-30   # 홍콩
python build.py

세 시장이 다 있어야 돌아가는 건 아니다. data/ 에 있는 것만 싣고, 없는 시장은 탭에 「미수집」으로 적는다. 한 시장만 받아서 돌려도 페이지는 나온다.

수집을 다시 할 필요가 없으면 build.py 만 돌리면 된다. 표기·레이아웃·기능 수정은 전부 이쪽이다.

시장별 데이터 출처

	출처	조회 단위	원본에 있는 것
🇯🇵 일본	日本経済新聞「決算発表スケジュール」(QUICK 제공)	하루 × 50건 페이징	업종·거래소·결산기
🇺🇸 미국	Nasdaq Earnings Calendar (api.nasdaq.com)	하루 1요청	발표 시각·시가총액·EPS 컨센서스
🇭🇰 홍콩	HKEXnews 상장사 공시 (실적 공시)	날짜 범위	공시 제목·분류

세 소스 다 성격이 조금씩 다르다.

• 일본은 회사가 신고한 결산발표 예정일이다.
• 미국은 실적발표일이고, 장전(BMO)/장후(AMC) 구분이 함께 온다. 세 시장 중 발표 시각을 주는 건 여기뿐이다.
• 홍콩만 성격이 다르다. 미국·일본은 회사가 미리 신고한 예정일이지만, 홍콩은 그 제도가 약하다. HKEX 가 내던 이사회 개최일 캘린더는 개편 때 통째로 없어졌고(경로가 전부 404), 흔히 쓰이는 AAStocks 는 표를 자바스크립트로 그려서 HTML 에 데이터가 없다. 그래서 홍콩은 이미 공시된 실적을 모은다. 출처는 거래소가 직접 내는 공식 공시라 가장 확실하지만, 앞으로의 예정이 아니라 지나간 발표다. 화면 탭 설명과 푸터에 그렇게 적어두었다. 하루 수백 건 올라오는 공시에서 실적만 골라낸다 — '주주총회 표결결과'(Poll Results)가 제일 흔한 함정이고, 연차보고서도 실적 공시가 아니라 뺀다.

레이트리밋 주의

세 스크래퍼 모두 "조용한 0건"을 만들지 않는 것을 제일 중요하게 다룬다. 발표가 없는 날과 못 받은 날이 구분되지 않으면 캘린더를 믿을 수 없기 때문이다.

• 일본 — 연속 30~40 요청쯤에서 본문 없는 껍데기 페이지를 돌려준다. fetch_valid() 가 건수 표시(N件目を表示)나 0件 문구 중 하나를 반드시 확인한다.
• 미국 — status.rCode 가 200 인 JSON 이면 나스닥이 대답한 것으로 보고, rows 가 비었으면 그 날은 진짜 0건이다. 막히면 403 이나 JSON 아닌 본문이 온다. 처음에는 message 필드가 채워져 있을 것까지 요구했는데, 나스닥은 발표가 없는 날 그 필드를 비워 보내기도 한다. 그 바람에 주말처럼 원래 0건인 날이 통째로 '수집 실패'로 기록됐다 — 발표가 없는 날을 못 받은 날로 적는 것도 거짓말이다.
• 홍콩 — result 가 JSON 문자열로 한 번 더 싸여 온다. 그 봉투가 깨지면 0건으로 넘기지 않고 원문 앞부분을 찍는다. python scrape_hk.py --probe 로 응답만 떠볼 수 있다.
• 세 스크래퍼 모두 연속 실패가 이어지면 그 시장을 접는다(GIVE_UP_AFTER). 백오프는 잠깐 막힌 것을 견디는 장치지 차단된 상대를 뚫는 장치가 아니다. 닛케이는 데이터센터 IP 를 막기 때문에 GitHub Actions 에서는 EARNINGS_GIVE_UP=1 로 더 빨리 접게 해두었다.

셋 다 물러섰다 재시도하고(15/45/120초, 일본만 300초까지), 받은 만큼 증분 저장한다. 이미 받은 날은 다시 안 긁으므로 중간에 죽어도 같은 명령을 다시 돌리면 못 받은 날만 이어서 받는다.

한글 표기

시장마다 원본 언어가 달라서 방식도 다르다.

	원본	한글 표기 방식
🇯🇵 일본	일본어	translit.py 로 기계 변환 (3등급) + 사전
🇺🇸 미국	영문	사전에 있으면 한글명, 없으면 영문명 그대로
🇭🇰 홍콩	영문	사전에 있으면 한글명, 없으면 영문명 그대로

미국·홍콩을 억지로 음차하지 않는 이유는 두 가지다. 엔비디아는 도움이 되지만 퍼스트 인더스트리얼 리얼티 트러스트는 도움이 안 되고, 한자 사명을 한국 한자음으로 읽으면 아예 틀린다 — 騰訊은 '등신'이 아니라 텐센트다. 중국어는 훈독이 아니라 음 자체가 다른 것이라 일본어식 접근이 통하지 않는다.

일본 회사명 변환은 세 등급으로 나뉜다.

등급	방식	비중
2	companies.py 수기 한글명, 또는 원래 로마자 사명	13%
1	단어 사전으로 전부 커버	13%
0	기계 변환 (가타카나 음운 + 한자 한국음)	75%

변환기가 하는 일:

1. 전각 영숫자를 반각으로. ｒｏｂｏｔ ｈｏｍｅ → robot home
2. 알파벳을 가나로 늘어놓은 사명을 로마자로 환원. ジーエヌアイ→GNI, アイ・アールジャパン→IR재팬.
3. 지명·기업명·업종어 사전(WORDS)을 긴 것부터 매칭.
4. 남은 구간은 가타카나 음운표와 한자 626자 한국음표로 옮긴다.

한계

일본 한자 지명·인명은 훈독이라 한국 한자음으로 읽으면 틀린다. 小田原은 오다와라인데 '소전원'이 되는 식이다. 그래서

• 기계 변환분(등급 0)은 점선을 그어 구분하고, 마우스를 올리면 원문이 뜬다.
• 표에 원문 열을 따로 두었고, 캘린더에는 원문 보기 토글이 있다.
• 검색은 한글·원문·영문·코드 어느 쪽으로도 걸린다.

이름이 틀렸으면 해당 시장의 companies*.py 또는 translit.py의 WORDS에 한 줄 넣고 build.py를 다시 돌리면 된다.

페이지 기능

• 시장 탭 — 전체 / 미국 / 일본 / 홍콩. 캘린더·그룹·차트·표가 함께 바뀐다. 전체 보기에서는 칩 왼쪽 띠 색과 국기로 시장을 구분한다.
• 관심종목 알림 — ☆ 를 눌러 담으면 localStorage에 저장. D-day로 표시. 시장이 섞이므로 시장:코드(us:NVDA)로 담는다. 예전에 담아둔 일본 코드는 페이지를 열 때 자동으로 jp: 를 붙여 옮긴다.
• .ics 내보내기 — 관심종목/이번 주 일정을 캘린더 파일로. 하루 전 알림(VALARM)이 들어 있다. 시차 문제를 피하려고 종일 일정으로 넣는다.
• 주간 캘린더 — 요일별 칸. 주목종목을 ★로 위에 올리고 나머지는 접어둔다. 미국은 시가총액 큰 순으로 정렬돼 접혀도 큰 게 먼저 보인다.
• 발표 시각 배지 — 미국 종목에 장전/장후 가 붙는다.
• 주목종목 발표일 — 시장별·테마별 다음 발표일.
• 전체 종목 표 — 검색·업종·거래소·분기·시총 필터, 정렬. 필터 후보는 보고 있는 시장의 데이터에서 뽑는다.

한계

• 회사명 한글 표기는 위의 「한계」를 참고. 원문을 늘 함께 볼 수 있게 해두었다.
• 발표 시각은 미국만 있다. 일본은 대부분 장 마감 후 15시 전후다.
• 홍콩은 지나간 발표다. 위의 「시장별 데이터 출처」 참고. 앞으로의 예정을 주는 소스를 찾으면 그때 바꾸면 된다.
• 날짜는 각 시장의 현지 날짜다. 미국 장후 발표는 한국 시각으로 다음 날 새벽이 된다. 전체 보기에서 세 시장을 같은 칸에 놓는 건 이 점에서 근사다.
• 실적 수치(매출·EPS 실제치)는 다루지 않는다. 일정만이다. 미국은 EPS 컨센서스가 원본에 오지만 화면에는 아직 쓰지 않는다.
• 발표일은 예정일이고 회사 사정으로 바뀐다. 갱신하려면 다시 긁어야 한다.
• 시가총액은 미국만 온다. 일본·홍콩의 「주목종목」은 companies*.py의 수기 목록에 의존한다.
• 휴장일 표는 2026년치만 들어 있다(markets.py). 홍콩의 음력 공휴일은 해가 바뀌면 HKEX 공식 휴장일표로 검산할 것.

시장을 하나 더 붙이려면

1. markets.py의 MARKETS에 항목을 하나 추가하고 MARKET_ORDER에 넣는다.
2. data/<파일>.json을 같은 모양으로 만드는 scrape_<코드>.py를 쓴다.
3. companies_<코드>.py에 GROUP_ORDER와 NOTABLE을 채운다.
4. build.py의 DICTS에 모듈을 등록하고, 원본이 영문이면 pack_en을 그대로 쓴다.