{"info":{"version":"1.0.0","description":"工劳网是关注中国劳工议题的新闻资料库，收录劳工新闻文章与劳动争议判决文书（lawcases）。本 API 完全公开、只读、无需认证，专为程序与 LLM/AI 代理设计。所有过滤参数的合法值见 GET /api/v1/vocabularies；人类可读文档见 /api/v1/docs；机读简介见 /llms.txt 与 /llms-full.txt。搜索结果中 title 与 match_snippet 可能包含高亮标签。","title":"工劳网 (Gonglao) 公开 API"},"components":{"schemas":{"ArticleDetail":{"type":"object","description":"文章完整内容（data 字段内）","properties":{"id":{"type":"integer"},"date":{"type":"string","format":"date"},"origin":{"type":"string"},"description":{"type":"string"},"title":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}},"author":{"type":"string"},"source":{"type":"string"},"content":{"type":"string","description":"文章全文"},"locations":{"type":"array","items":{"type":"object","properties":{"city":{"type":"string"},"province":{"type":"string"},"county":{"type":"string"}}}},"url":{"type":"string"},"content_type":{"type":"array","items":{"type":"string"}},"theme":{"type":"array","items":{"type":"string"}},"industry":{"type":"array","items":{"type":"string"}},"occupation":{"type":"array","items":{"type":"string"}},"issues":{"type":"array","items":{"type":"string"}},"archive_org_url":{"type":"string"},"archive_today_url":{"type":"string"},"published_date":{"type":"string","description":"本站发布时间"},"feature_img":{"type":"string"},"summaries":{"type":"array","description":"劳工权益视角的列点摘要","items":{"type":"string"}},"site_url":{"type":"string"}}},"ArticleHit":{"type":"object","description":"搜索结果条目。title 与 match_snippet 可能包含高亮标签","properties":{"id":{"type":"string","description":"文章 id，可用于 GET /api/v1/articles/{id}"},"date":{"type":"string","format":"date"},"origin":{"type":"string","enum":["crawler","tg"]},"title":{"type":"string"},"location":{"type":"object","properties":{"city":{"type":"array","items":{"type":"string"}},"province":{"type":"array","items":{"type":"string"}},"county":{"type":"array","items":{"type":"string"}}}},"keywords":{"type":"array","items":{"type":"string"}},"author":{"type":"string"},"source":{"type":"string","description":"来源媒体"},"url":{"type":"string","description":"文章原始链接"},"content_type":{"type":"array","items":{"type":"string"}},"match_snippet":{"type":"string","description":"命中片段"},"theme":{"type":"array","items":{"type":"string"}},"industry":{"type":"array","items":{"type":"string"}},"occupation":{"type":"array","items":{"type":"string"}},"issues":{"type":"array","items":{"type":"string"}},"site_url":{"type":"string","description":"本站文章页面链接"}}},"ArticleList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ArticleDetail"}},"meta":{"$ref":"#/components/schemas/ListMeta"}}},"ArticleSearchResult":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ArticleHit"}},"meta":{"$ref":"#/components/schemas/SearchMeta"},"facet_counts":{"type":"object","description":"各 facet 字段的值分布，如 {\"theme\": {\"劳动者权益事件\": 98}}。键包括 theme、content_type、industry、occupation、issues、keywords、origin、location.province"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_params","not_found","search_unavailable"]},"message":{"type":"string"},"details":{"type":"object","description":"各参数的具体错误，含合法值列表"}}}}},"LawcaseDetail":{"type":"object","description":"判决文书完整内容（data 字段内）。字段名为拼音缩写，含义见 description","properties":{"no":{"type":"string","description":"案号"},"id":{"type":"integer"},"name":{"type":"string","description":"案件名称"},"users":{"type":"array","items":{"type":"string"}},"caseLevel":{"type":"string","description":"审理级别"},"courtNm":{"type":"string","description":"法院名称"},"pbDt":{"type":"string","format":"date","description":"判决日期"},"province":{"type":"string"},"cpjg":{"type":"string","description":"裁判结果"},"dsr":{"type":"string","description":"当事人"},"fbqw":{"type":"string","description":"发布全文"},"fxgc":{"type":"string","description":"分析过程"},"jbqk":{"type":"string","description":"基本情况"},"ssjl":{"type":"string","description":"诉讼记录"},"site_url":{"type":"string"}}},"LawcaseHit":{"type":"object","description":"判决文书搜索结果条目。name/match_snippet 可能包含高亮标签","properties":{"no":{"type":"string","description":"案号"},"id":{"type":"string","description":"文书 id，可用于 GET /api/v1/lawcases/{id}"},"name":{"type":"string","description":"案件名称"},"users":{"type":"array","items":{"type":"string"}},"caseLevel":{"type":"string","description":"审理级别"},"courtNm":{"type":"string","description":"法院名称"},"match_snippet":{"type":"string"},"pbDt":{"type":"string","format":"date","description":"判决日期"},"province":{"type":"string"},"site_url":{"type":"string"}}},"LawcaseSearchResult":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/LawcaseHit"}},"meta":{"$ref":"#/components/schemas/SearchMeta"},"facet_counts":{"type":"object","description":"province 与 caseLevel 的值分布"}}},"ListMeta":{"type":"object","properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"total_count":{"type":"integer"},"total_pages":{"type":"integer"}}},"SearchMeta":{"type":"object","properties":{"q":{"type":"string"},"range":{"type":"string"},"order":{"type":"string","description":"实际生效的排序字段"},"page":{"type":"integer"},"per_page":{"type":"integer"},"total_count":{"type":"integer"},"total_pages":{"type":"integer"}}},"Vocabularies":{"type":"object","description":"data.articles 内为文章的过滤词汇表；data.lawcases 内为判决文书的 province/caseLevel 可用值"}}},"paths":{"/api/v1/articles":{"get":{"parameters":[{"in":"query","name":"page","description":"页码，从 1 开始","required":false,"schema":{"default":1,"type":"integer","minimum":1}},{"in":"query","name":"per_page","description":"每页条数，1 到 50","required":false,"schema":{"default":20,"maximum":50,"type":"integer","minimum":1}},{"in":"query","name":"origin[]","description":"内容来源过滤。默认 [\"tg\"]（编辑收录内容）","required":false,"schema":{"type":"array","items":{"type":"string","enum":["crawler","tg"]}},"style":"form","explode":true}],"summary":"按文章日期倒序分页列出文章（默认只含编辑收录内容，与人类浏览一致）","responses":{"200":{"description":"文章列表","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArticleList"}}}},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/articles/by-url":{"get":{"parameters":[{"in":"query","name":"url","description":"文章的原始 url（精确匹配）","required":true,"schema":{"type":"string"}}],"summary":"按原始 url 查找文章","responses":{"200":{"description":"文章详情","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArticleDetail"}}}},"400":{"description":"缺少 url 参数","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"文章不存在","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/articles/search":{"get":{"description":"基于 Typesense 的全文搜索，支持按主题、内容类型、行业、职业、议题、省份、日期范围过滤，返回 facet 统计。q 为空（或 *）时表示浏览全部，按日期倒序，此时 order 参数被忽略。","parameters":[{"in":"query","name":"q","description":"搜索关键词。留空或 * 表示浏览全部（按日期倒序）","required":false,"schema":{"default":"","type":"string"}},{"in":"query","name":"page","description":"页码，从 1 开始","required":false,"schema":{"default":1,"type":"integer","minimum":1}},{"in":"query","name":"per_page","description":"每页条数，1 到 50","required":false,"schema":{"default":20,"maximum":50,"type":"integer","minimum":1}},{"in":"query","name":"order","description":"排序字段（倒序）。q 为空时固定按 date","required":false,"schema":{"default":"_text_match","type":"string","enum":["_text_match","date"]}},{"in":"query","name":"range","description":"限定搜索的字段范围","required":false,"schema":{"default":"all","type":"string","enum":["all","title","content","author"]}},{"in":"query","name":"start_date","description":"日期（含当天），格式 YYYY-MM-DD","required":false,"schema":{"type":"string","format":"date"}},{"in":"query","name":"end_date","description":"日期（含当天），格式 YYYY-MM-DD","required":false,"schema":{"type":"string","format":"date"}},{"in":"query","name":"theme[]","description":"主题过滤","required":false,"schema":{"type":"array","items":{"type":"string","enum":["劳动者权益事件","劳动法律案件","劳动政策与管制","劳动事件","劳动者处境","经济与行业发展"]}},"style":"form","explode":true},{"in":"query","name":"content_type[]","description":"内容类型过滤","required":false,"schema":{"type":"array","items":{"type":"string","enum":["普通新闻报道","深度报道或非虚构写作","分析或评论","统计数据或调查报告","个人自述"]}},"style":"form","explode":true},{"in":"query","name":"industry[]","description":"行业过滤","required":false,"schema":{"type":"array","items":{"type":"string","enum":["采矿业","制造业","机械/设备生产","电子/仪器/计算机","纺织/服饰/家具","化工/医药/生物","交通物流业","出租车/网约车","公交/长途巴士","货车/物流","邮政/快递","建筑业","服务业","批发/零售","住宿/餐饮","居民服务/修理/物业服务","体育休闲/文化娱乐","金融","互联网信息服务","房地产/租赁商务服务","医疗卫生","教育","外卖","党政机关","农业"]}},"style":"form","explode":true},{"in":"query","name":"occupation[]","description":"职业过滤","required":false,"schema":{"type":"array","items":{"type":"string","enum":["白领受雇者","蓝领受雇者","政府公务员或事业单位工作者","摊贩/店主/小业主","青年学生/职校/实习生"]}},"style":"form","explode":true},{"in":"query","name":"issues[]","description":"议题过滤","required":false,"schema":{"type":"array","items":{"type":"string","enum":["中高龄劳动者","人口","人口移动/流动","人口老龄化或少子女化","企业停业停产或倒闭","企业管理","公共就业服务","劳动合同","劳动条件","劳工健康","压迫行为","员工体检","员工条例/工作规则","失业","实习","就业","就业歧视","岗位调动与晋升","工人仲裁/起诉","工人运动/行动","工人隐私（劳动监控）","工会","工伤/职业病","工作","工作时间","工资报酬","性骚扰","技术变革与自动化","拖欠工资","招聘","教育与考试","新冠肺炎","残疾劳动者","求职诈骗","派遣劳动/外包工作","海外中国工人","灵活就业/零工经济/平台劳动","社会保护","社会保障（五险一金）","离职辞退（包含遭到裁员或逼退）","私人职业介绍所/劳务中介","绩效考核","考试","职业培训","职业教育","职场欺凌","肮脏或危险的工作环境","行动与组织","裁员","请假休假","远程办公/居家办公","退休","集体谈判与集体协议","青年失业","（协助工人的）志愿组织或非政府组织"]}},"style":"form","explode":true},{"in":"query","name":"loc_p[]","description":"省份过滤（如广东省），合法值见搜索结果的 facet_counts","required":false,"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true},{"in":"query","name":"origin[]","description":"内容来源过滤。默认 [\"tg\"]（编辑收录内容）","required":false,"schema":{"type":"array","items":{"type":"string","enum":["crawler","tg"]}},"style":"form","explode":true}],"summary":"全文搜索劳工新闻文章","responses":{"200":{"description":"搜索结果","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArticleSearchResult"}}}},"400":{"description":"参数错误（响应中会列出合法值）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"搜索服务不可用","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/articles/{id}":{"get":{"parameters":[{"in":"path","name":"id","description":"文章 id（搜索结果中的 id 字段）","required":true,"schema":{"type":"integer"}}],"summary":"获取单篇文章的完整内容（含正文与摘要）","responses":{"200":{"description":"文章详情","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArticleDetail"}}}},"404":{"description":"文章不存在","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/lawcases/search":{"get":{"description":"q 为空时按判决日期（pbDt）倒序浏览全部。province 与 caseLevel 的可用值见 /api/v1/vocabularies。","parameters":[{"in":"query","name":"q","description":"搜索关键词。留空表示浏览全部","required":false,"schema":{"default":"","type":"string"}},{"in":"query","name":"page","description":"页码，从 1 开始","required":false,"schema":{"default":1,"type":"integer","minimum":1}},{"in":"query","name":"per_page","description":"每页条数，1 到 50","required":false,"schema":{"default":20,"maximum":50,"type":"integer","minimum":1}},{"in":"query","name":"order","description":"排序字段（倒序）","required":false,"schema":{"default":"_text_match","type":"string","enum":["_text_match","pbDt"]}},{"in":"query","name":"range","description":"限定搜索的字段范围","required":false,"schema":{"default":"all","type":"string","enum":["all","no","name","fbqw","courtNm"]}},{"in":"query","name":"start_date","description":"日期（含当天），格式 YYYY-MM-DD","required":false,"schema":{"type":"string","format":"date"}},{"in":"query","name":"end_date","description":"日期（含当天），格式 YYYY-MM-DD","required":false,"schema":{"type":"string","format":"date"}},{"in":"query","name":"province[]","description":"省份过滤","required":false,"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true},{"in":"query","name":"caseLevel[]","description":"审理级别过滤（如一审、二审）","required":false,"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true}],"summary":"全文搜索劳动争议判决文书","responses":{"200":{"description":"搜索结果","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LawcaseSearchResult"}}}},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"搜索服务不可用","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/lawcases/{id}":{"get":{"parameters":[{"in":"path","name":"id","description":"判决文书 id（搜索结果中的 id 字段）","required":true,"schema":{"type":"integer"}}],"summary":"获取单个判决文书的完整内容","responses":{"200":{"description":"判决文书详情","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LawcaseDetail"}}}},"404":{"description":"判决文书不存在","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/openapi.json":{"get":{"summary":"本 OpenAPI 3.0 规范文档","responses":{"200":{"description":"OpenAPI 文档"}}}},"/api/v1/vocabularies":{"get":{"description":"LLM 调用搜索前应先读取本端点，了解 theme/content_type/industry/occupation/issues/origin 及 lawcase 的 province/caseLevel 的合法值。","summary":"所有过滤参数的合法值（受控词汇表）","responses":{"200":{"description":"词汇表","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Vocabularies"}}}}}}}},"openapi":"3.0.3","servers":[{"url":"/"}]}