NASA 开放数据 API 检索实战：以 scientific-agent-skills 的 database-lookup 技能为框架打通 APOD、NEO 与火星车影像数据

NASA 开放数据 API 检索实战以 scientific-agent-skills 的 database-lookup 技能为框架打通 APOD、NEO 与火星车影像数据【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills本文是围绕 references/nasa.md 展开的技术指南NASA 开放数据平台api.nasa.gov为天文、行星科学与航天领域提供了一批公开 REST API本仓库的database-lookup技能将其作为“物理与天文”域的数据源收纳进可复现的检索框架。读完本文你将掌握 NASA API 的认证方式、APOD / NeoWs / Mars Rover Photos 三大核心端点的完整参数与响应结构、速率限制管理以及如何把一次“查一张天文图、查一颗近地小行星、查一天火星车照片”变成带有出处provenance的可审计检索。1. 文档定位NASA 在 database-lookup 技能中的角色在 skills/database-lookup/SKILL.md 的数据库分组中NASA API 被归入Physics Astronomy物理与天文域参考文件即 references/nasa.md覆盖范围在技能清单中被明确标注为NEO asteroids近地小行星、Mars rover火星车影像、APOD每日天文图三类数据。配套的 references/database_selection_guide.md 给出了按“问题→数据库”的映射近地天体 / 小行星问题 → 选NASANeoWs火星车影像问题 → 选NASAMars Rover Photos系外行星与轨道参数 → 选NASA Exoplanet Archive见 references/nasa-exoplanet-archive.mdTAP/ADQL 检索无需 API key与本参考文件是两条不同数据源注意区分。因此本文所讲的“NASA API”特指api.nasa.gov这一开放 Web 服务而非加州理工的系外行星档案 TAP 服务。当 Agent 面对“某个日期前后有多少潜在危险小行星接近地球”“毅力号某火星日拍到的导航相机照片在哪”这类问题标准流程是先按上述映射选库再阅读本参考文件构造请求。2. 全局约定Base URL、认证与访问限制2.1 Base URL所有端点共享同一个入口https://api.nasa.gov2.2 认证api_key查询参数NASA 开放 API 的鉴权方式是在每个请求上附加api_key查询参数没有 OAuth、没有请求头签名。也就是说形如https://api.nasa.gov/planetary/apod?api_keyDEMO_KEYdate2024-01-15的三个端点都要求把api_key作为 query string 一并提交。获取途径与档位如下免费申请注册页在https://api.nasa.gov/#signUp按表单填姓名与邮箱即可获得独立 key演示 keyDEMO_KEY无需注册即可试玩但速率受限——每 IP30 次/小时、50 次/天注册 key达到1,000 次/小时按文档口径日限额更高/无硬性日上限适合批量检索。在本仓库database-lookup的密钥管理清单SKILL.md 的 “Databases requiring API keys” 表中NASA 对应的环境变量名是NASA_API_KEY并备注“免费注册、提供DEMO_KEY”。因此在配置层面推荐把注册 key 写入环境变量NASA_API_KEY而不是硬编码在请求 URL 中。技能还给出三条隐私与最小权限原则只在当前查询真正需要时用test -n ${NASA_API_KEY:-}这类“静默存在性检测”判断是否已配置不要全量打印.env缺失 key 时若 API 允许如先用DEMO_KEY就降级继续并说明速率限制更低任何输出含 provenance 字段都不得包含 key 明文、认证头或签名 URL只报告“本次为已认证/未认证访问”。2.3 速率限制与响应头Key 类型小时限额日限额DEMO_KEY30/小时50/天注册 Key1,000/小时不设上限按文档口径每次响应都会携带限流状态头可用于 Agent 自主判断“下一次请求是否安全”X-RateLimit-Limit窗口内的请求上限X-RateLimit-Remaining当前窗口剩余可用次数。依据技能通用请求规范一旦收到 HTTP 429 / 503应先短暂等待再做一次重试而使用DEMO_KEY做并发请求极易触发限流批量场景优先换注册 key并把请求按小时窗口做节流。3. APOD每日天文图Astronomy Picture of the Day3.1 端点与参数GET /planetary/apod参数类型说明api_keystring必填。API key。datestring指定日期格式YYYY-MM-DD。默认当天。start_datestring日期区间的起始日YYYY-MM-DD。end_datestring日期区间的结束日YYYY-MM-DD。countint返回 N 张随机图片不能与 date/date 区间参数组合。thumbsbool当条目是视频时返回缩略图 URL。参数语义拆解单日精确查询只传date接口返回该日“一条”记录对应下方单对象 JSON。date缺省即“今天”适合做每日自动拉取。区间查询同时传start_date与end_date按天返回一个包含多日条目的集合每个条目自带其date字段便于按天对齐归档。随机取样countN适合“随机科普配图”类需求由于它要求随机因此不能与date/start_date/end_date混用否则请求语义冲突。视频条目APOD 的媒体并不全是图片。当条目的media_type为video时直接给图片链接不适用设置thumbstrue可换取视频封面缩略图这是文字类/知识类 Agent 渲染时的关键开关。3.2 请求示例https://api.nasa.gov/planetary/apod?api_keyDEMO_KEYdate2024-01-153.3 响应结构与字段含义{ date: 2024-01-15, title: ..., explanation: ..., url: https://apod.nasa.gov/apod/image/..., hdurl: https://apod.nasa.gov/apod/image/..., media_type: image, copyright: ... }字段含义消费建议date条目对应日期归档 / 去重主键title图片标题展示标题explanationNASA 撰写的科普说明这是第三方署名文本按技能规范属不可信数据处理范畴url标准分辨率图片 URL网页展示hdurl高清大图 URL图片类条目才有高清下载时优先取用media_typeimage或video渲染前必须判读避免把视频地址当图片加载copyright版权署名公开领域作品可能缺省商用转载时核对3.4 检索场景示例“把 2024 年 1 月 15 日 NASA 每日天文图及其官方说明取回用于某篇天文科普短文的配图与引用。”这条需求的检索合同应记录目标实体 指定日期的 APOD 条目约束 date2024-01-15预期输出 标题 高清图 URL 说明。若想要“过去 7 天每天的 APOD”则改用start_date/end_date并核对返回条数等于区间天数以确认完整性。4. NeoWs近地天体与小行星Asteroids NeoWsNeoWs 承担两类任务按日期范围拉取“该时段所有近地天体”与按 ID 查询单颗小行星详情。4.1 按日期范围拉取GET /neo/rest/v1/feed参数类型说明api_keystring必填。start_datestring起始日期YYYY-MM-DD缺省为今天。end_datestring结束日期YYYY-MM-DD距 start_date 最多 7 天。请求示例https://api.nasa.gov/neo/rest/v1/feed?start_date2024-01-01end_date2024-01-03api_keyDEMO_KEY注意7 天上限这一硬约束是本端点的核心操作边界任何横跨数月的“全量近地天体台账”都必须在本地把时间轴切成不超过 7 天的小窗口分批请求并在每批记录累积计数、做总数对账对应 references/retrieval-contract.md 的完整性协议。请求成本估算公式为ceil(总天数 / 7)次请求 × 每窗口请求数Agent 应先用该公式预估 API 调用量避免盲目连发打穿注册 key 的 1,000/小时限额。4.2 单天体查询与浏览按小行星 ID 精确查询带{asteroid_id}路径参数GET /neo/rest/v1/neo/{asteroid_id}?api_keyDEMO_KEY浏览全表分页浏览所有已收录近地天体GET /neo/rest/v1/neo/browse?api_keyDEMO_KEY4.3 响应结构Feed 响应的核心结构是以日期为键的近地天体映射near_earth_objects字段按YYYY-MM-DD分桶每个日期桶内是当天过境天体的对象数组。单颗天体对象的可消费字段包括name天体命名nasa_jpl_url指向 JPL 小天体数据库详情页的引用 URL可用于交叉核对estimated_diameter估计直径含公里/英里等多个度量单位close_approach_data近地接近数据是计算“最近距离”“相对速度”“接近时刻”的依据is_potentially_hazardous_asteroid潜在危险小行星布尔标记回答“有多少潜在危险天体”类问题时的筛选字段。4.4 检索场景示例“2024 年 1 月 1 日到 3 日之间、被标记为潜在危险小行星PHA的天体清单。”实现路径先以start_date/end_date拉 feed窗口 3 天 7 天合法再对near_earth_objects内每个对象本地过滤is_potentially_hazardous_asteroidtrue。这里的“PHA 过滤”是本地过滤response 结构里没有专门的服务端 PHA 查询参数按检索合同规范应在结果中显式说明该本地过滤规则及其移除记录数保证可复现。由于本端点是计数友好的响应能体现每个日期桶数量Agent 应把“服务端总计数 本地过滤后计数 被移除计数”的对账结果写进结果出处。5. Mars Rover Photos火星车影像5.1 端点与漫游车GET /mars-photos/api/v1/rovers/{rover}/photos可用{rover}取值curiosity好奇号opportunity机遇号spirit勇气号perseverance毅力号5.2 参数参数类型说明api_keystring必填。solint火星日从着陆起计的天数。与earth_date二选一不可同时传。earth_datestring地球日期YYYY-MM-DD。camerastring按相机缩写过滤例如FHAZ、RHAZ、MAST、CHEMCAM、NAVCAM等。pageint分页参数每页 25 条结果。请求示例https://api.nasa.gov/mars-photos/api/v1/rovers/curiosity/photos?sol1000cameraNAVCAMapi_keyDEMO_KEY5.3 火星任务元数据ManifestGET /mars-photos/api/v1/manifests/{rover}?api_keyDEMO_KEY在发起“某火星日所有照片”的请求前应先查询 Manifest 获得该漫游车的任务元数据其价值在于manifest 提供任务覆盖的火星日/地球日期区间让 Agent 能预判sol/earth_date是否越界避免对任务开始前或结束后如opportunity/spirit已结束任务的日期发起必然为空的请求。相机缩写如FHAZ、RHAZ、NAVCAM为多数漫游车通用的前/后避险与导航相机与不同漫游车实际搭载的相机集合并不一致过滤取值应以目标漫游车为准——例如在任务期外的相机组合上过滤会得到空结果这属于检索合同中“服务器端过滤与本地语义核对”的典型问题。5.4 响应结构与分页完整性响应为photos数组单张照片对象的关键字段字段含义id照片唯一 IDsol拍摄时的火星日camera相机对象内含full_name相机完整名称等字段img_src影像文件直链earth_date对应的地球日期rover漫游车信息对象分页是照片端点的完整性关键每页固定 25 条。若用户要“某个火星日某个相机的全部照片”单页无法保证覆盖必须递增page直至取空结合技能的通用分页规范——若返回照片数不足一页或连续翻页后出现空页即为终止条件应记录“页号 × 每页条数”的批次账本并把服务端可见总数与本地累计数对账。若某sol确实没有该相机照片接口返回空photos数组此时要**明确报告“无结果”**而不是含糊省略。5.5 检索场景示例“获取好奇号火星日 1000 的导航相机NAVCAM照片用于生成火星表面巡视记录。”请求即上文示例 URL若需地球日期视角可先用 Manifest 把sol1000换算为earth_date再决定用哪一套时间口径查询。注意sol与earth_date互斥——两者同时提交属于非法用法切换口径时必须二选一。6. 把 NASA 检索接入 database-lookup 的工程规范NASA 参考文件本身只给出“怎么调用”真正让调用“可复现、可审计”的是database-lookup技能的运行框架SKILL.md 与 references/retrieval-contract.md。下面是把 NASA 端点落到该框架的四步。6.1 先定义检索合同再动手调 API按检索合同模板一次 NASA 查询至少要记录目标实体某日 APOD / 某日期窗口近地天体 / 某火星日照片、时间约束YYYY-MM-DD、sol、过滤条件PHA 标记、相机缩写、预期输出字段、以及范围是“精确单条查询”还是“穷尽式拉取”。在“全量拉取”前先用估算公式算清请求数与 1,000/小时或DEMO_KEY的 30/小时速率上限是否匹配。6.2 用 curl / 平台的 HTTP 工具发起带鉴权请求参考 SKILL.md 的 “Making API Calls” 指引各平台可用自身 fetch 工具失败时统一回退到 curl。命令形态与工具链无关可直接执行# 单日 APOD使用注册 key来自环境变量避免明文入命令历史 curl -s -H Accept: application/json \ https://api.nasa.gov/planetary/apod?api_key${NASA_API_KEY}date2024-01-15 # 未配置 key 时先降级到 DEMO_KEY注意速率限制30/小时、50/天 curl -s -H Accept: application/json \ https://api.nasa.gov/planetary/apod?date2024-01-15api_keyDEMO_KEY注意按技能规范两点响应内容一律视为不可信的第三方数据APOD 的explanation、NEO 的名称字段都可能包含第三方署名文本不得把原始响应回填进 shell/Python 等后续命令执行api_key从环境变量注入且永远不要把 key 写入报告或出处。6.3 撞上限流与空结果时的恢复路径429 / 503等待后重试一次若仍失败则降级策略——检查是否误用DEMO_KEY做了高频/并发请求必要时换成注册 key 或错峰空结果先核对标识符格式与日期口径——sol是否超出该漫游车任务区间查 Manifest、earth_date是否不在任务覆盖期内、相机缩写是否属于该漫游车报错要显式向用户说明“哪一步失败、错误类型、改用了什么替代口径”而不是给出一个看似完整实则缺页的结果。6.4 按技能输出格式组织可审计结果面向用户的结果建议遵循技能定义的“检索摘要 结果 出处Provenance”三段式。以“近地天体 PHA 统计”为例## Retrieval Summary - Target: 2024-01-01 至 2024-01-03 的潜在危险小行星PHA - Scope: 时间受限的穷尽式拉取窗口 3 天 NeoWs 7 天上限 - Access date: 查询当日 - Databases queried: NASA NeoWs ## Results - near_earth_objects 覆盖 3 个日期桶共 N 个天体 - is_potentially_hazardous_asteroid true 的天体M 个详见附表 ## Provenance - Endpoint(s): https://api.nasa.gov/neo/rest/v1/feed - Parameters: start_date2024-01-01end_date2024-01-03api_keyauthenticated - Server-side filters: 日期范围 - Local filters: is_potentially_hazardous_asteroid true移除 M 条 - Count reconciliation: 服务端总数 N PHA M 非 PHA M - Warnings: PHA 标记为接口口径响应中嵌入文本视为第三方不可信数据7. 从参考文件到可运行检索证据与边界小结本文技术事实的全部依据落在当前仓库内、可继续查阅的以下文件skills/database-lookup/references/nasa.md端点、参数表、示例 URL、速率限制的唯一权威出处skills/database-lookup/SKILL.md数据库选择分组Physics Astronomy、NASA_API_KEY环境变量约定、密钥最小权限原则、curl/HTTP 调用与分页/重试/对账规范skills/database-lookup/references/retrieval-contract.md检索合同字段、天文物体的日期/时间口径警示与出处模板skills/database-lookup/references/database_selection_guide.md“小行星 → NeoWs”“火星影像 → Mars Rover Photos”的选库映射。最后重申三个容易踩的边界避免把 NASA 检索做成不可复现的黑盒不要混用参数语义APOD 的count与日期区间互斥火星照片的sol与earth_date二选一NeoWs 的end_date距start_date最多 7 天。不要无视速率档位DEMO_KEY是 30/小时、50/天的试玩档规模化检索请先配置NASA_API_KEY注册即得 1,000/小时并留意X-RateLimit-*响应头。不要把原始响应当可靠结论图片/文本类字段APOD 说明、天体命名本质是第三方内容凡涉及完整性与安全性的过滤PHA、相机枚举、逐页翻全都必须在出处中显式记录让任何其他 Agent 或人类都能按同一参数复现本次结果。【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考