# 工劳网 (Gonglao)

> 工劳网是关注中国劳工议题的中文新闻资料库，收录经编辑筛选的劳工新闻文章（含劳工权益视角的列点摘要、主题/行业/议题/地区标注）与劳动争议判决文书资料库。全站数据通过完全公开、只读、无需认证的 JSON API 提供。

重要说明：

- API base URL 为本站根路径，无需 API key，支持 CORS（任意来源）。
- 调用搜索前建议先读取 /api/v1/vocabularies，了解所有过滤参数的合法值。
- 参数错误时返回 400，响应中会列出该参数允许的值，可据此自行修正。
- 日期参数格式为 YYYY-MM-DD；分页参数 page 从 1 开始，per_page 最大 50。
- 搜索结果中 title 与 match_snippet 可能包含 <mark> 高亮标签。

## API

- [文章全文搜索](/api/v1/articles/search): GET，参数 q、page、per_page、order、range、start_date、end_date、theme[]、content_type[]、industry[]、occupation[]、issues[]、loc_p[]、origin[]，返回命中列表 + facet 统计
- [文章列表](/api/v1/articles): GET，按文章日期倒序分页，默认来源 tg（编辑收录），可加 origin[] 参数
- [文章详情](/api/v1/articles/{id}): GET，返回全文、摘要与全部标注
- [按原始 url 查文章](/api/v1/articles/by-url?url=...): GET
- [判决文书全文搜索](/api/v1/lawcases/search): GET，参数 q、page、per_page、order、range、start_date、end_date、province[]、caseLevel[]
- [判决文书详情](/api/v1/lawcases/{id}): GET
- [过滤词汇表](/api/v1/vocabularies): GET，所有过滤参数的合法值
- [OpenAPI 3.0 规范](/api/v1/openapi.json): 机读接口定义

## 文档

- [人类可读 API 文档](/api/v1/docs)
- [完整机读文档（含全部词汇表与示例）](/llms-full.txt)

## 其它

- [RSS 订阅](/rss.xml)

---

# 完整参考

## 文章搜索 GET /api/v1/articles/search

| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| q | string | （空） | 搜索关键词。留空或 * 表示浏览全部，此时按日期倒序、order 被忽略 |
| page | integer | 1 | 页码，从 1 开始 |
| per_page | integer | 20 | 每页条数，最大 50 |
| order | string | _text_match | 排序字段（倒序）。可选：_text_match、date |
| range | string | all | 限定搜索字段。可选：all、title、content、author |
| start_date / end_date | string | （空） | 日期范围，格式 YYYY-MM-DD |
| theme[] | array | [] | 主题过滤，见下方词汇表 |
| content_type[] | array | [] | 内容类型过滤 |
| industry[] | array | [] | 行业过滤 |
| occupation[] | array | [] | 职业过滤 |
| issues[] | array | [] | 议题过滤 |
| loc_p[] | array | [] | 省份过滤（如 广东省） |
| origin[] | array | ["tg"] | 内容来源：crawler（自动抓取的未筛选内容）、tg（工劳网编辑收录内容（默认）） |

响应：`{"data": [命中列表], "meta": {"page","per_page","total_count","total_pages","order","range"}, "facet_counts": {字段: {值: 数量}}}`。
命中条目的 id 可用于文章详情端点。

## 文章词汇表

- theme（主题）：劳动者权益事件、劳动法律案件、劳动政策与管制、劳动事件、劳动者处境、经济与行业发展
- content_type（内容类型）：普通新闻报道、深度报道或非虚构写作、分析或评论、统计数据或调查报告、个人自述
- industry（行业）：采矿业、制造业、机械/设备生产、电子/仪器/计算机、纺织/服饰/家具、化工/医药/生物、交通物流业、出租车/网约车、公交/长途巴士、货车/物流、邮政/快递、建筑业、服务业、批发/零售、住宿/餐饮、居民服务/修理/物业服务、体育休闲/文化娱乐、金融、互联网信息服务、房地产/租赁商务服务、医疗卫生、教育、外卖、党政机关、农业
- occupation（职业）：白领受雇者、蓝领受雇者、政府公务员或事业单位工作者、摊贩/店主/小业主、青年学生/职校/实习生
- issues（议题）：中高龄劳动者、人口、人口移动/流动、人口老龄化或少子女化、企业停业停产或倒闭、企业管理、公共就业服务、劳动合同、劳动条件、劳工健康、压迫行为、员工体检、员工条例/工作规则、失业、实习、就业、就业歧视、岗位调动与晋升、工人仲裁/起诉、工人运动/行动、工人隐私（劳动监控）、工会、工伤/职业病、工作、工作时间、工资报酬、性骚扰、技术变革与自动化、拖欠工资、招聘、教育与考试、新冠肺炎、残疾劳动者、求职诈骗、派遣劳动/外包工作、海外中国工人、灵活就业/零工经济/平台劳动、社会保护、社会保障（五险一金）、离职辞退（包含遭到裁员或逼退）、私人职业介绍所/劳务中介、绩效考核、考试、职业培训、职业教育、职场欺凌、肮脏或危险的工作环境、行动与组织、裁员、请假休假、远程办公/居家办公、退休、集体谈判与集体协议、青年失业、（协助工人的）志愿组织或非政府组织

## 文章详情 GET /api/v1/articles/{id}

返回 data 对象：id、site_url、url（原始链接）、title、description、content（全文）、author、date、published_date、source、origin、theme、content_type、industry、occupation、issues、keywords、summaries（劳工权益视角列点摘要）、locations（[{province,city,county}]）、feature_img、archive_org_url、archive_today_url。

## 判决文书搜索 GET /api/v1/lawcases/search

参数：q、page、per_page、order（_text_match、pbDt）、range（all、no、name、fbqw、courtNm）、start_date、end_date、province[]、caseLevel[]。
province 与 caseLevel 的可用值见 /api/v1/vocabularies。

## 判决文书字段对照（拼音缩写）

| 字段 | 含义 |
|---|---|
| no | 案号 |
| name | 案件名称 |
| dsr | 当事人 |
| jbqk | 基本情况 |
| ssjl | 诉讼记录 |
| fxgc | 分析过程 |
| cpjg | 裁判结果 |
| fbqw | 发布全文 |
| pbDt | 判决日期 |
| courtNm | 法院名称 |
| caseLevel | 审理级别 |

## 错误格式

所有错误返回 `{"error": {"code", "message", "details"}}`，code 为 invalid_params（400，details 中列出各参数允许的值）、not_found（404）或 search_unavailable（503）。

## 示例

按议题搜索拖欠工资相关文章（每页 5 条）：

    curl "https://本站域名/api/v1/articles/search?q=工资&issues[]=拖欠工资&per_page=5"

浏览制造业最新文章（q 留空即按日期倒序）：

    curl "https://本站域名/api/v1/articles/search?industry[]=制造业"

按日期范围搜索深度报道：

    curl "https://本站域名/api/v1/articles/search?q=外卖&content_type[]=深度报道或非虚构写作&start_date=2024-01-01&end_date=2024-12-31"

搜索加班相关判决文书并取详情：

    curl "https://本站域名/api/v1/lawcases/search?q=加班"
    curl "https://本站域名/api/v1/lawcases/123"