做技术这些年，我收藏夹里吃灰最多的就是各种“API 合集”链接，真要找某个免费接口时照样翻半天。但有一个开源项目，我从收藏改成 Star 之后，就再也没取关过——GitHub 上的 public-apis，474k Star，长期霸占热门仓库前排。如果你正在为“想要一个免费 API 但不知道去哪找”而发愁，这份清单基本能解决掉 90% 的需求。
这个项目本质上就是一个超大号的免费 API 索引，从动物、天气、股票行情到机器学习、新闻、游戏，几十个类别排得明明白白。更重要的是，它不只是列个名字，每个 API 都标注了是否需要鉴权、是否支持 HTTPS、是否支持跨域调用，选型时能省掉大量试错时间。无论你是要练手做毕设、搭个人项目、参加黑客松，还是给公司产品找数据源，都适合先从这份清单里翻一翻。今天就把我对这个项目的完整使用经验整理出来，从项目结构、挑选思路到真实接入案例，一次性讲透。
1. 这个项目到底是个什么来头
1.1 从 474k Star 说起：它为什么能长期霸榜
public-apis 不是代码框架，也不是工具库，它只有一个 README 文件，里面按类别堆满了免费公开 API 的链接和说明。这个仓库的 Star 数超过 47 万，意味着你认识的开发者里，大概率有人 Star 过它。为什么一个“列表页”能火成这样？
核心原因有两个。第一，它精准击中了开发者最普遍的需求——找数据源。无论你做什么项目，基本都逃不开“需要数据”这一步，而公开 API 是最快拿到真实数据的途径。第二，它的参与门槛极低，任何人发现一个好用的免费 API，都可以提交 PR 补充进去，项目因此保持着非常高的活跃度。我查过它的提交记录，维护者几乎每天都会合并新条目，这种持续更新的状态，让它的参考价值一直在线。
当然，也要说句实话：Star 高不等于每个条目都靠谱。这个项目胜在覆盖面广、筛选成本低，但具体到某个 API 是否还能用、免费额度还剩多少，需要你按自己需求二次验证。把它理解成一个“候选池”，而不是“保证书”，使用心态就对了。
1.2 目录结构：一份清单能拆成几十个细分方向
打开 README，你首先看到的就是一个按字母排序的目录导航。这个设计非常朴素，但极其好用。我数了数，现在大概有 50 多个类别，覆盖了日常开发能想到的大部分场景。
挑几个有代表性的类别感受一下：
- Animals：猫狗、鸟类、宠物相关的图片和资料接口
- Anime：动漫信息、角色、语录查询
- Cryptocurrency：加密货币实时行情、历史数据
- Currency Exchange：各国货币汇率换算
- Finance：股票、基金、债券等金融数据
- Food & Drink：食谱、酒水、营养成分查询
- Games & Comics：游戏资料、漫画信息
- Geocoding：地址解析、经纬度转换
- Machine Learning：模型推理、文本分析、AI 能力接口
- News：全球新闻聚合、RSS 解析
- Weather：实时天气、天气预报、空气质量
- Test Data：假数据生成、mock 接口
每个类别下，又会列出好几条到几十条不等的 API。每条记录包含四列核心信息：API 名称、简单描述、是否需要 Auth（鉴权）、是否支持 HTTPS 和 CORS。这种标准化字段，让你不用点进每个链接，光扫一眼表格就能排除掉一大批不合适的选项。
2. 拿到清单后，怎么挑出真正能用的 API
2.1 先看三个字段：Auth、HTTPS、CORS
很多人打开这份清单，第一反应是“这么多我该从哪看起”。我的经验是，先盯住每条记录后面的三个字段：Auth、HTTPS、CORS。
Auth 字段决定你接入的复杂度。它是分级的，No Auth 代表完全不需要密钥，拿来就能请求；apiKey 表示需要先注册获取 API Key，在请求时带上；OAuth 则要走完整的授权流程，适合需要操作用户数据的场景。如果你只是想快速验证一个想法，优先选 No Auth 的接口，可以省掉注册和配置的功夫。
HTTPS 字段不用多说，现代项目基本都要求加密传输，这个字段为 No 的接口，浏览器里也会被拦，直接跳过就行。
CORS 字段是我特别留意的。它代表这个接口允不允许浏览器跨域调用。如果你是小程序或者纯前端项目，CORS 为 Yes 的接口可以前端直连，开发效率高很多；CORS 为 No 的接口，就必须走后端代理转发，否则浏览器控制台会给你刷一屏跨域报错。
2.2 高频实用的几个类别和代表 API
清单里类别虽多，但实际开发中真正高频使用的，我体感就这么几类：
天气类，我首推 Open-Meteo。它无需 API Key，支持全球范围实时天气和 7 天预报，每分钟免费请求次数 600 次，个人项目完全够用。接入一个天气接口，只需要拼一个 URL，返回 JSON 里直接拿温度、风速、降水概率，非常丝滑。
金融股票类，Finnhub 和 Alpha Vantage 是清单里比较能打的。Finnhub 免费版每天 60 次请求，支持全球股票实时报价、公司基本面、新闻舆情，注册后拿一个 API Key 就能用。Alpha Vantage 免费版每分钟 5 次请求、每天 500 次，做个人量化分析或者学习项目足够。这类接口天生适合做“股票数据接口 api 免费”的场景，不需要自己在各大交易网站上爬数据。
机器学习和 AI 类，清单里收录了不少大厂和社区的免费推理接口，比如 Hugging Face Inference API，注册后可以调用大量开源模型做文本分类、图像识别、翻译等任务。如果你在寻找“免费大模型 api”相关的现成实现，这类入口比你自己部署模型要快得多。需要注意，这类接口通常有严格的频率限制，不适合生产环境高并发。
测试数据类，JSONPlaceholder 是经典中的经典。它提供一整套模拟的用户、帖子、评论、相册数据，Rest API 风格和真实接口完全一致，前端练手、做原型演示时，它就是我默认的数据源。
新闻类，Hacker News 官方 API 和 NewsAPI 都在这份清单里。前者无需鉴权，边做边学效率高；后者免费版有每日 100 次请求的额度，适合做新闻聚合小程序。
2.3 如何快速判断一个 API 值不值得接入
字段看完了，还要做一步判断：这个 API 到底稳不稳、能不用在项目里。我的判断方法很简单，三步走。
第一步，点进链接看文档。如果一个 API 的官方文档有清晰的接入示例、错误码说明和频率限制说明，说明这个项目正经在维护；如果文档只有一句简单介绍，没有示例，数据格式全靠猜，那大概率是个人临时作品，不建议投入精力。
第二步，看清单里标注的更新时间，再去对应官网或者 GitHub 仓库看最近一次 commit。一年以上没更新的服务，再免费也尽量不要选——你永远不知道服务器哪天就悄悄关掉了。
第三步，也是最重要的，别光看文档，直接拿 curl 请求一下真实接口，看返回结果是否和文档一致。这一步能过滤掉 80% 的“文档写得很美，实际请求全是坑”的接口。
3. 实操演示：把清单里的 API 真正跑起来
3.1 零成本热身：一个不需要 API Key 的天气接口
理论说再多，不如上手过一遍。我先用一个完全不需要 Key 的接口演示整个流程：Open-Meteo。
打开它的文档页，可以看到请求 URL 是：
https://api.open-meteo.com/v1/forecast?latitude=39.9042&longitude=116.4074¤t_weather=true这个接口通过 latitude 和 longitude 参数指定经纬度，current_weather=true 表示只返回当前天气。我在终端里直接 curl 一下：
curl "https://api.open-meteo.com/v1/forecast?latitude=39.9042&longitude=116.4074¤t_weather=true"返回的 JSON 长这样：
{ "latitude": 39.88, "longitude": 116.41, "generationtime_ms": 0.3810615539550781, "utc_offset_seconds": 0, "timezone": "GMT", "timezone_abbreviation": "GMT", "elevation": 144.0, "current_weather": { "temperature": 12.6, "windspeed": 11.2, "winddirection": 229.0, "weathercode": 2, "is_day": 0, "time": "2025-06-10T08:00" } }拿到这个 JSON，我自己动手写个 Python 脚本，把温度、风速、天气编码解析出来：
import requests def get_current_weather(lat: float, lon: float): url = "https://api.open-meteo.com/v1/forecast" params = { "latitude": lat, "longitude": lon, "current_weather": "true", } resp = requests.get(url, params=params, timeout=10) resp.raise_for_status() data = resp.json() current = data["current_weather"] return { "temperature_celsius": current["temperature"], "windspeed_kmh": current["windspeed"], "weathercode": current["weathercode"], } print(get_current_weather(39.9042, 116.4074))整个接入过程不到 5 分钟，没有注册、没有密钥，直接返回可用数据。这就是我推荐从 No Auth 接口入手的原因——你可以先把整套请求、解析、容错的代码框架跑通，再换更复杂的带 Key 接口，心理负担小很多。
3.2 带上 Key 的完整链路：以股票行情接口为例
接下来演示一个带 API Key 的完整链路，选 Finnhub 的股票实时报价接口。
先去 finnhub.io 注册账号，免费版就能拿到一个 API Key。拿到 Key 之后，我第一件事不是写代码，而是先把 Key 放到环境变量里，避免硬编码进脚本。Linux/macOS 下这样设置：
export FINNHUB_API_KEY="你的key"Windows 的 PowerShell 用：
$env:FINNHUB_API_KEY="你的key"然后在 Python 里通过 os.environ 读取：
import os import requests API_KEY = os.environ["FINNHUB_API_KEY"] url = "https://finnhub.io/api/v1/quote" params = { "symbol": "AAPL", "token": API_KEY, } resp = requests.get(url, params=params, timeout=10) print(resp.status_code) print(resp.json())请求成功的话，会返回类似这样的数据：
{ "c": 207.35, "h": 211.5, "l": 206.33, "o": 210.77, "pc": 210.56, "t": 1718000000 }这里的 c 是当前价格，h 是当日最高，l 是当日最低，o 是开盘价，pc 是前收盘价。把这几个字段接进自己的看板页面，一个实时股票监控小组件就完成了。
接入过程中有两点提醒。第一，请求参数里的 token 就是你的 API Key，务必通过环境变量注入，不要写死在代码里，更不要提交到 GitHub 仓库。第二，加上超时参数 timeout，我习惯设 10 秒。免费接口偶尔会出现响应慢，如果没有超时控制，程序可能卡死在那里，体验很差。
3.3 把 API 接进自己项目的两个建议
跑通一个接口只是第一步，真正把 API 稳定地接入项目，我建议做到两点。
第一，对返回数据做校验。免费 API 的返回结构不会像付费产品那么稳定，偶尔会多字段、少字段，或者类型不一致。在解析层做好防御，比如用 dict.get() 代替直接下标访问，给字段加默认值，防止一个接口异常把整个应用带崩。
第二，加好重试和降级逻辑。免费接口出现 5xx 或 429（请求过多）是常态，重试一两次是合理的。如果重试后还是失败，最好返回缓存数据或者一处降级说明，而不是让用户看到整页报错。我在个人项目里通常用 tenacity 库做重试，设置最大重试次数 3 次，退避策略用指数退避。
4. 免费 API 的坑，我替你们踩过一遍
4.1 最典型的五种翻车现场
用这份清单里的免費 API 用了两年多，我自己遇到过不少翻车时刻，总结成五类最典型的问题：
| 问题类型 | 表现 | 原因 | 应对建议 |
|---|---|---|---|
| 接口下线 | 请求返回 404 或 DNS 解析失败 | 服务方停止运营 | 选有稳定背书的 API，避免个人服务器接口 |
| 限流 429 | 频率稍高就被拒绝 | 免费额度极低 | 读文档了解频率限制，加请求间隔和重试 |
| 数据滞后 | 行情、新闻延迟严重 | 免费版数据源更新慢 | 根据业务场景判断是否需要付费数据 |
| 跨域被拦 | 浏览器控制台 CORS 报错 | 接口未开放跨域 | 后端代理转发，或选 CORS 为 Yes 的接口 |
| 文档过期 | 照着文档调用却报参数错误 | 接口升级后文档没更新 | 先用 curl 实测，以实际返回为准 |
这里重点说一下 429。很多免费的 API 不会明确告诉你限额是多少，你只有把请求发出去、收到 429 才知道踩线了。应对思路是：读响应头里的 Retry-After 字段，它通常会告诉你需要等多少秒才能继续请求。再不行，就在代码里做全局的请求节流，确保同一时刻只有一个请求在发出。
4.2 项目不维护了怎么办
这是免费 API 最大的隐患：清单还挂着它，但背后的服务可能早就不维护了。
判断一个 API 还在不在维护，我有两个土办法。第一个是看清单里它的链接和描述有没有被近期更新过。public-apis 维护者比较勤快，发现失效的条目一般会标注或移除。第二个是去项目官网看新闻、博客、更新日志，如果一个 API 近一年没有任何产品更新，基本可以判定已经进入“僵尸状态”。
一旦确认一个 API 已经不可用，或者频繁出错，我建议立即启动替代方案。我的常用做法是，承认“没有永远免费的 API”这个现实，在项目设计阶段就抽象出一层数据源接口，把具体的 API 实现隔离在独立模块里。这样换数据源时，只需要改一个工厂函数，业务代码完全不用动。
如果只是做 demo 或者教学项目，还有一条更轻的路：用 JSONPlaceholder 这类专门提供 mock 数据的接口，或者干脆本地起一个 json-server，把 API 返回的样例数据保存成 json 文件模拟返回。做法虽然“土”，但胜在完全可控，永不出故障。
4.3 版权、付费边界和发布注意
免费的 API 不代表可以毫无限制地商用，这个边界值得花一分钟弄清楚。
我在接入任何免费 API 之前，都会顺手看一眼它的 Terms of Service。有些 API 虽然免费，但明确禁止商业用途；有些则要求你在产品中标注数据来源；还有一部分 API 的免费版数据可能来自第三方，再分发有限制。特别是在金融、新闻领域，数据版权问题尤其容易被忽視。我见过有个人开发者接了一个免费股票接口做成了小程序，结果因为数据源不允许二次分发，收到侵权投诉后只能下架。
另一个边界是付费升级的触发点。大多数免费 API 的额度限制都是“够学习、不够生产”的水平。如果一个 API 在你的项目里变得不可或缺，而且请求量已经稳定超过免费额度的 80%，这时候不要死撑免费方案，该升级付费就升级。省下来的时间成本，远比那点订阅费值钱。
5. 常见问题速查与独门经验
5.1 拿到 API 后常见的报错与处理
接入过程中，总会有各种报错。我把高频问题整理成一张速查表，供大家直接对照：
| 状态码 | 错误信息示例 | 含义 | 处理方案 |
|---|---|---|---|
| 401 | Unauthorized | API Key 缺失或错误 | 检查 Key 是否拼写正确，是否通过环境变量传入 |
| 403 | Forbidden | 无权限访问该资源 | 确认账号是否完成邮箱验证，免费版是否有该接口权限 |
| 404 | Not Found | 接口路径或资源不存在 | 核对请求 URL 是否与文档一致，确认资源 ID 是否有效 |
| 429 | Too Many Requests | 请求频率超限 | 按 Retry-After 等待，或降低请求频率 |
| 500 | Internal Server Error | 服务端异常 | 稍后重试，连续出现则更换备用 API |
| CORS | No 'Access-Control-Allow-Origin' | 跨域被拦 | 改用后端代理请求，或换成支持 CORS 的接口 |
遇到 401、403，先检查 API Key 的配置和权限，这两个问题 90% 都是配置层面的粗心。遇到 429，别急着加并发，先看一下文档里的免费版频率限制，合理设置请求间隔。
5.2 我的几条选择经验
文章最后，分享几条我用 public-apis 的真实体会，供大家参考。
第一条，永远不要在生产环境对一个免费 API 做单点依赖。无论它现在多稳，都要做好随时被断供的准备。我习惯在主数据源之外，至少准备一个备用数据源，并在代码里实现热切换。
第二条，对“免费额度”的认知要理性。免费额度不是给你薅羊毛的，你的项目一旦跑起来，请求量增长是很快的。建议在项目初期就在日志里记录每个 API 的请求量和失败率，提前预判额度消耗速度。
第三条，定期扫描你的 API 清单。我会每隔一段时间，用一个脚本批量请求自己项目里依赖的接口，检查状态码和响应时长，一旦发现异常马上处理。这个方法帮我避免过至少三次线上事故。
第四条，善用 public-apis 的搜索功能。GitHub 仓库页面右上角的搜索框可以快速过滤类别，直接在仓库内搜 “weather”“stock”“news” 等关键词，比在 README 里手动滚动高效得多。
根据我个人的实际操作经验，public-apis 最正确的打开方式，不是收藏之后吃灰，而是把它当作一个活索引：今天要找天气接口，翻一下 Weather 分类，挑两个顺眼的试一遍；明天要做新闻聚合，再去 News 分类里逛一圈。配合自己沉淀的选型方法和容错机制，这份清单才能从“看起来很厉害”变成“真的很好用”。
最后再分享一个小技巧：如果你看中了清单里的某个接口，但担心它哪天失效，可以 fork 一份 public-apis 到自己仓库，按自己的使用频率把常用接口整理到一个小清单里，做一个私人定制的 API 导航。这样即使上游仓库变动，你的清单仍然稳定可复现。
