journapi

标准、可扩展的学术制品元数据检索 SDK + CLI —— 首个数据源为期刊（通过公开的 ISSN Portal），提供 Provider 抽象层，为后续更多数据源（文献、DOI 等）预留扩展能力。

项目状态：stable。ISSN Portal 公开网页接口已实现并经独立复审验证；官方订阅 API（api.issn.org, REST + JWT）提供完整 Provider 骨架（需订阅凭据端到端验证）。

功能特性

• 期刊检索 — 按刊名 / ISSN / eISSN / ISSN-L 搜索与精确查询
• ISSN-L / ISSN-H — 同刊多介质（Print/Online）聚合与历史沿革（更名前后继）家族
• 多数据源 — ISSN Portal（国际）+ 中国 ISSN 中心 nlc（中文刊名检索优先使用）+ 官方订阅 API；注册式 Provider 便于扩展
• 多使用方式 — Python SDK / CLI / Web UI / MCP 服务器 / Agent Skill
• 礼貌抓取 — 限速（robots.txt Crawl-delay 1s）、重试退避、可选磁盘缓存（RFC 9111）

安装

包已发布到 PyPI（包名 journapi）：

uvx journapi --help              # 免安装直接运行（推荐）
pip install "journapi[chinese]"  # 或 pip 安装（含中文刊名分词）
uv tool install journapi         # 或全局工具安装

开发环境搭建见 CONTRIBUTING.md。

快速开始

# 搜索（刊名 / ISSN 均可；已知 ISSN 优先传 ISSN）
journapi search "Hearing research"
journapi search 0378-5955 --json

# 中文刊名检索优先走中国 ISSN 中心源
journapi search 自动化学报 --provider nlc_issn

# 单条记录 / ISSN-L 集群 / Web UI
journapi get 0964-1998
journapi cluster 0378-5955
journapi web   # 浏览器打开 http://127.0.0.1:8787

import asyncio
from journapi import ArtifactSearchClient


async def main():
    async with ArtifactSearchClient() as client:
        results = await client.search("Hearing research")
        print([(r.issn, r.title) for r in results.items])


asyncio.run(main())

检索策略（search 与 get 的取舍、中文刊三步链路）见 docs/API.md；可运行示例见 examples/。

使用方式

文档

• API 参考 — 客户端、模型、错误、数据源选择与检索策略、Web 服务路由
• MCP 接入指南 — 智能体接入配置、工具清单、推荐查询链路
• 架构与设计 — 分层架构、项目结构、模块说明、关键设计、环境变量
• 数据源调研 — ISSN Portal / 中国 ISSN 中心接口能力边界与实测结论
• 示例 — 可运行脚本

合规

journapi 遵循公开门户 robots.txt（目录级允许/禁止 + 1s 爬取延迟）。生产 / 批量场景请订阅官方搜索 API，细节见数据源调研。

贡献指南

欢迎参与贡献！详细的贡献规范和开发流程请参考 CONTRIBUTING.md。

许可证

MIT