sec-edgar-downloader 使用避坑清单SEC EDGAR 文件下载中 CIK 补零、日期格式、Ticker 大小写等 8 个常见错误一次说清【免费下载链接】sec-edgar-downloader Download filings from the SEC EDGAR database using Python项目地址: https://gitcode.com/gh_mirrors/se/sec-edgar-downloadersec-edgar-downloader是一个用 Python 从美国 SEC EDGAR 数据库下载公司文件10-K 年报、8-K 公告、13F 持仓等的开源工具包。本文面向新手把CIK 补零、日期格式、Ticker 大小写等 8 个最常见的踩坑点一次说清帮你快速、合规地批量下载 SEC 文件少走弯路。一、30 秒上手安装 sec-edgar-downloader 并下载第一份文件 先通过 pip 安装要求 Python 3.10 及以上pip install -U sec-edgar-downloader最小可用示例from sec_edgar_downloader import Downloader # 公司名 邮箱是 SEC 合规要求不能省略 dl Downloader(MyCompanyName, my.emaildomain.com) # 下载苹果最近 5 份 8-K 文件 dl.get(8-K, AAPL, limit5)如需从源码安装先克隆仓库git clone https://gitcode.com/gh_mirrors/se/sec-edgar-downloader二、8 个常见错误清单附正确写法⚠️1️⃣ CIK 没有补零到 10 位SEC 的 API 要求 CIK 必须是10 位、前导补零的字符串。好消息是包内部会自动补零zfill(10)传789019和0000789019微软的 CIK结果完全一样。常见错误❌ CIK 超过 10 位 → 直接抛ValueError: Invalid CIK. CIKs must be at most 10 digits long.❌ 把 CIK 当整数传后丢失前导零又手动截断补零逻辑在sec_edgar_downloader/_utils.py的validate_and_convert_ticker_or_cik中实现。记住CIK 只要 ≤10 位纯数字即可剩下的交给库。2️⃣ Ticker 大小写、空格以及查无此股库会先对输入做strip().upper()所以 aapl 也能正确识别为AAPL大小写本身不用纠结。真正的坑有两个❌ 传入的 Ticker必须存在于 SEC 官方的 Ticker-CIK 映射表即上市交易的股票代码。私募、未上市公司没有 Ticker必须直接传 CIK否则会报Ticker XXX is invalid and cannot be mapped to a CIK。❌ 同一公司在映射表里的 Ticker 以 SEC 数据为准例如富达、先锋这类只有 CIK 的机构0000102909。3️⃣ 日期格式不是 YYYY-MM-DDafter/before参数如果是字符串只接受YYYY-MM-DD如2017-01-01解析格式定义在sec_edgar_downloader/_constants.py的DATE_FORMAT_TOKENS %Y-%m-%d。❌2017/01/01、01-01-2017、20170101→ 抛Incorrect date format✅ 也可以直接传 Python 的date/datetime对象会自动转换4️⃣ 日期范围1994 年红线和 after beforeSEC EDGAR 只支持 1994-01-01 之后的数据。after早于这一天会被静默抬升到 1994-01-01不会报错但你要知道数据下限。❌after before→ 抛ValueError: After date cannot be greater than the before date.before不传时默认是今天。# 2017 年 1 月 1 日之后、3 月 25 日之前且包含修正案 dl.get(8-K, AAPL, after2017-01-01, before2017-03-25, include_amendsTrue)5️⃣ 文件类型form写错大小写和空格都敏感form必须精确命中内置支持列表多一个空格、少一个连字符都会失败❌10K、SC13G、def 14a✅10-K、SC 13G中间有空格、DEF 14A中间有空格写错时包会抛出ValueError并列出全部支持的类型。完整清单约 360 种含 13F-HR、SC 13D、424B5 等见sec_edgar_downloader/_constants.py中的SUPPORTED_FORMS运行时也可用dl.supported_forms查看。6️⃣ 漏下修正案include_amends 默认是 False8-K/A、10-K/A这类以/A结尾的是修正案文件。默认只下载原始文件想要全量必须显式打开dl.get(8-K, AAPL, include_amendsTrue) # 同时包含 8-K 与 8-K/A7️⃣ 没填公司名和邮箱 → 403 ForbiddenSEC 的公平访问政策要求所有程序化请求携带User-Agent: 公司名 邮箱。Downloader的前两个参数就是干这个的不要传占位假邮箱否则批量下载时容易被封历史上最常见的 403 报错元凶。另外包已内置每秒 10 个请求的限流pyrate-limiter实现见sec_edgar_downloader/_sec_gateway.py超限时会自动阻塞等待而不是直接发请求无需自己加sleep。8️⃣ get() 参数位置传错 Python 版本过低get()的第二个参数之后limit、after、before、include_amends、download_details全部只能以关键字方式传❌dl.get(10-K, MSFT, 5)✅dl.get(10-K, MSFT, limit5)❌limit0或负数 → 抛ValueError最少传limit1❌ Python 3.8 / 3.9 无法安装自 5.1.0 起要求Python ≥ 3.10见pyproject.toml的requires-python三、下载的文件存在哪里所有文件统一保存在下载目录/sec-edgar-filings/Ticker或CIK/文件类型/档案号/下full-submission.txt完整提交文件默认必下primary-document.*人类可读的主文档如 8-K 的 HTML仅当download_detailsTrue时下载download_folder默认是当前工作目录构造Downloader时传第三个参数即可改位置支持Path对象。四、报错速查表 报错信息原因解决办法Invalid CIK. CIKs must be at most 10 digitsCIK 超过 10 位检查 CIK 位数去掉多余字符Ticker XXX is invalid and cannot be mapped to a CIK未上市或 Ticker 不在 SEC 映射表改用 10 位 CIKIncorrect date format日期不是YYYY-MM-DD改用标准格式或date对象After date cannot be greater than the before date区间写反交换after与beforeforms are not supportedform 名称不精确对照dl.supported_forms复制准确写法403 ForbiddenUser-Agent 不合规或频率异常填真实公司名邮箱依赖内置限流五、总结使用 sec-edgar-downloader 的核心就三件事传对身份Ticker 或 10 位 CIK、写对日期YYYY-MM-DD、选对 form 名称。掌握这份 CIK 补零、Ticker 大小写、日期格式等 8 个常见错误的避坑清单后再配合include_amends、limit等关键字参数就能稳定、合规地批量下载 SEC EDGAR 文件。更多示例可参考README.rst与tests/目录下的测试用例。【免费下载链接】sec-edgar-downloader Download filings from the SEC EDGAR database using Python项目地址: https://gitcode.com/gh_mirrors/se/sec-edgar-downloader创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 sec-edgar-downloader 使用避坑清单：SEC EDGAR 文件下载中 CIK 补零、日期格式、Ticker 大小写等 8 个常见错误一次说清
sec-edgar-downloader 使用避坑清单SEC EDGAR 文件下载中 CIK 补零、日期格式、Ticker 大小写等 8 个常见错误一次说清【免费下载链接】sec-edgar-downloader Download filings from the SEC EDGAR database using Python项目地址: https://gitcode.com/gh_mirrors/se/sec-edgar-downloadersec-edgar-downloader是一个用 Python 从美国 SEC EDGAR 数据库下载公司文件10-K 年报、8-K 公告、13F 持仓等的开源工具包。本文面向新手把CIK 补零、日期格式、Ticker 大小写等 8 个最常见的踩坑点一次说清帮你快速、合规地批量下载 SEC 文件少走弯路。一、30 秒上手安装 sec-edgar-downloader 并下载第一份文件 先通过 pip 安装要求 Python 3.10 及以上pip install -U sec-edgar-downloader最小可用示例from sec_edgar_downloader import Downloader # 公司名 邮箱是 SEC 合规要求不能省略 dl Downloader(MyCompanyName, my.emaildomain.com) # 下载苹果最近 5 份 8-K 文件 dl.get(8-K, AAPL, limit5)如需从源码安装先克隆仓库git clone https://gitcode.com/gh_mirrors/se/sec-edgar-downloader二、8 个常见错误清单附正确写法⚠️1️⃣ CIK 没有补零到 10 位SEC 的 API 要求 CIK 必须是10 位、前导补零的字符串。好消息是包内部会自动补零zfill(10)传789019和0000789019微软的 CIK结果完全一样。常见错误❌ CIK 超过 10 位 → 直接抛ValueError: Invalid CIK. CIKs must be at most 10 digits long.❌ 把 CIK 当整数传后丢失前导零又手动截断补零逻辑在sec_edgar_downloader/_utils.py的validate_and_convert_ticker_or_cik中实现。记住CIK 只要 ≤10 位纯数字即可剩下的交给库。2️⃣ Ticker 大小写、空格以及查无此股库会先对输入做strip().upper()所以 aapl 也能正确识别为AAPL大小写本身不用纠结。真正的坑有两个❌ 传入的 Ticker必须存在于 SEC 官方的 Ticker-CIK 映射表即上市交易的股票代码。私募、未上市公司没有 Ticker必须直接传 CIK否则会报Ticker XXX is invalid and cannot be mapped to a CIK。❌ 同一公司在映射表里的 Ticker 以 SEC 数据为准例如富达、先锋这类只有 CIK 的机构0000102909。3️⃣ 日期格式不是 YYYY-MM-DDafter/before参数如果是字符串只接受YYYY-MM-DD如2017-01-01解析格式定义在sec_edgar_downloader/_constants.py的DATE_FORMAT_TOKENS %Y-%m-%d。❌2017/01/01、01-01-2017、20170101→ 抛Incorrect date format✅ 也可以直接传 Python 的date/datetime对象会自动转换4️⃣ 日期范围1994 年红线和 after beforeSEC EDGAR 只支持 1994-01-01 之后的数据。after早于这一天会被静默抬升到 1994-01-01不会报错但你要知道数据下限。❌after before→ 抛ValueError: After date cannot be greater than the before date.before不传时默认是今天。# 2017 年 1 月 1 日之后、3 月 25 日之前且包含修正案 dl.get(8-K, AAPL, after2017-01-01, before2017-03-25, include_amendsTrue)5️⃣ 文件类型form写错大小写和空格都敏感form必须精确命中内置支持列表多一个空格、少一个连字符都会失败❌10K、SC13G、def 14a✅10-K、SC 13G中间有空格、DEF 14A中间有空格写错时包会抛出ValueError并列出全部支持的类型。完整清单约 360 种含 13F-HR、SC 13D、424B5 等见sec_edgar_downloader/_constants.py中的SUPPORTED_FORMS运行时也可用dl.supported_forms查看。6️⃣ 漏下修正案include_amends 默认是 False8-K/A、10-K/A这类以/A结尾的是修正案文件。默认只下载原始文件想要全量必须显式打开dl.get(8-K, AAPL, include_amendsTrue) # 同时包含 8-K 与 8-K/A7️⃣ 没填公司名和邮箱 → 403 ForbiddenSEC 的公平访问政策要求所有程序化请求携带User-Agent: 公司名 邮箱。Downloader的前两个参数就是干这个的不要传占位假邮箱否则批量下载时容易被封历史上最常见的 403 报错元凶。另外包已内置每秒 10 个请求的限流pyrate-limiter实现见sec_edgar_downloader/_sec_gateway.py超限时会自动阻塞等待而不是直接发请求无需自己加sleep。8️⃣ get() 参数位置传错 Python 版本过低get()的第二个参数之后limit、after、before、include_amends、download_details全部只能以关键字方式传❌dl.get(10-K, MSFT, 5)✅dl.get(10-K, MSFT, limit5)❌limit0或负数 → 抛ValueError最少传limit1❌ Python 3.8 / 3.9 无法安装自 5.1.0 起要求Python ≥ 3.10见pyproject.toml的requires-python三、下载的文件存在哪里所有文件统一保存在下载目录/sec-edgar-filings/Ticker或CIK/文件类型/档案号/下full-submission.txt完整提交文件默认必下primary-document.*人类可读的主文档如 8-K 的 HTML仅当download_detailsTrue时下载download_folder默认是当前工作目录构造Downloader时传第三个参数即可改位置支持Path对象。四、报错速查表 报错信息原因解决办法Invalid CIK. CIKs must be at most 10 digitsCIK 超过 10 位检查 CIK 位数去掉多余字符Ticker XXX is invalid and cannot be mapped to a CIK未上市或 Ticker 不在 SEC 映射表改用 10 位 CIKIncorrect date format日期不是YYYY-MM-DD改用标准格式或date对象After date cannot be greater than the before date区间写反交换after与beforeforms are not supportedform 名称不精确对照dl.supported_forms复制准确写法403 ForbiddenUser-Agent 不合规或频率异常填真实公司名邮箱依赖内置限流五、总结使用 sec-edgar-downloader 的核心就三件事传对身份Ticker 或 10 位 CIK、写对日期YYYY-MM-DD、选对 form 名称。掌握这份 CIK 补零、Ticker 大小写、日期格式等 8 个常见错误的避坑清单后再配合include_amends、limit等关键字参数就能稳定、合规地批量下载 SEC EDGAR 文件。更多示例可参考README.rst与tests/目录下的测试用例。【免费下载链接】sec-edgar-downloader Download filings from the SEC EDGAR database using Python项目地址: https://gitcode.com/gh_mirrors/se/sec-edgar-downloader创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考