Hellowork API

Access structured job listing data from Hellowork.com — one of France's leading employment platforms. Search vacancies by keyword, location, distance, salary, and recency, and retrieve full job details including salary ranges, education requirements, experience criteria, and remote work status via a clean REST API.

原始信息汇总

Hellowork API 数据集概述

基本信息

• 数据集名称: Hellowork API
• 数据来源: Hellowork.com（法国领先的就业平台）
• 数据类型: 结构化职位列表数据
• API类型: REST API
• 当前版本: 1.0.0

API 概述

该API提供对法国在线就业平台Hellowork.com职位列表的程序化访问。适用于构建法国职位聚合器、劳动力市场分析工具、薪资基准仪表板或自动化候选人匹配系统。API提供覆盖法国各行业和地区的结构化、即用型职位空缺数据。

核心功能与关键特性

• 薪资范围数据: 提供结构化的min_value和max_value薪资字段（欧元），包含unit_text（YEAR/MONTH），支持直接薪资比较和基准测试。
• 教育与经验要求: 结构化credential_category（例如postgraduate degree）和months_of_experience字段，适用于候选人匹配和技能差距分析。
• 远程工作标识: job_location_type字段在搜索阶段识别远程职位（TELECOMMUTE），无需检查完整描述。
• 最低薪资过滤器: min_salary作为数字过滤参数，支持直接薪资下限过滤。
• 职业类别: occupational_category返回角色的功能领域（例如"Audit"、"Informatique"、"Marketing"），支持基于分类法的过滤和报告。
• 基于距离的位置搜索: distance参数支持以公里为单位的半径过滤（0、5、10、20、50），围绕给定城市或邮政编码进行搜索。

API 端点

1. GET /job/search — 使用过滤器搜索职位

主要发现端点。keyword是唯一必需参数，所有其他过滤器均为可选且可自由组合。

查询参数:

• keyword: 职位名称、角色或技能（必需）
• location: 城市、邮政编码或地区名称
• distance: 搜索半径（公里）：0（精确）、5、10、20或50
• min_salary: 最低年薪或月薪下限（欧元）
• posted_date: 新近度过滤器：h（24小时）、d（3天）、w（上周）、m（上月）或空值表示任意时间
• sort_by: date（最新优先）或空值表示相关性
• page: 分页页码（最小值为1）

2. POST /job/listing-by-url — 通过URL获取职位列表

通过传递完整的Hellowork搜索结果URL直接检索职位结果列表。适用于复制特定的预过滤搜索，包括使用Hellowork界面专用过滤器或搜索端点未涵盖的高级URL参数的搜索。

请求体:

• url: Hellowork职位列表页面的完整URL（必需）

3. POST /job/get-by-url — 通过URL获取完整职位详情

通过传递其直接的Hellowork列表URL检索单个职位的完整数据记录。响应结构与搜索和列表端点相同，无需额外的数据丰富步骤。

请求体:

• url: 单个Hellowork职位列表页面的完整URL（必需）

响应结构

所有端点返回统一的JSON响应信封：

成功响应: json { "statusCode": 200, "messageCode": "OK", "data": [ /* 职位对象数组 */ ] }

错误响应: json { "statusCode": 404, "messageCode": "NOT_FOUND", "message": "Job not found" }

常见HTTP状态码:

• 200: 成功 — 数据已返回
• 400: 错误请求 — 参数或URL格式无效
• 404: 未找到 — 职位列表不存在或已过期
• 500: 内部服务器错误 — 抓取器执行失败

数据字段（所有端点返回）

• url: 职位在Hellowork上的直接链接
• title: 发布的职位标题（通常包含法国惯例的H/F性别标记）
• industry: 行业部门
• occupational_category: 功能性职位类别
• employment_type: 合同类型：FULL_TIME、PART_TIME、CONTRACTOR等
• job_location_type: 远程职位为TELECOMMUTE；现场职位为缺失或null
• base_salary.value.min_value: 最低薪资（年薪或月薪）
• base_salary.value.max_value: 最高薪资（年薪或月薪）
• base_salary.value.unit_text: 薪资周期：YEAR或MONTH
• base_salary.currency: 法国始终为EUR
• date_posted: ISO 8601发布时间戳
• valid_through: ISO 8601列表过期日期
• direct_apply: 布尔值 — 是否直接在Hellowork上提交申请
• hiring_organization.name: 雇主或招聘机构名称
• hiring_organization.logo: 雇主徽标图像URL
• hiring_organization.same_as: 雇主Hellowork公司资料链接
• job_location.address.address_region: 法国地区
• job_location.address.address_country: 国家代码（FR）
• education_requirements.credential_category: 教育水平
• experience_requirements.months_of_experience: 最低经验月数
• applicant_location_requirements.name: 地理申请人要求
• description: 完整的HTML职位描述，包括任务、个人资料要求和雇主介绍

使用建议与最佳实践

• 推荐工作流: 所有三个端点返回相同的数据结构，无需两步发现-丰富流程。
• 关键词使用: keyword是搜索的唯一必填字段。从宽泛开始，然后根据需要缩小范围。
• 薪资过滤: min_salary是数字过滤器 — 传递原始数字如35000（非格式化字符串）。
• 远程职位识别: job_location_type: "TELECOMMUTE"无需解析描述即可识别远程职位。
• 薪资数据结构化: min_value和max_value为数字，支持直接比较和聚合。
• 经验要求: experience_requirements.months_of_experience提供数字最低经验阈值。
• 列表有效期: valid_through跟踪列表过期时间 — 法国列表通常在发布后约30天过期。
• 新近度过滤: posted_date=h或posted_date=d适用于需要仅显示上次运行以来最新列表的高频监控流程。
• 雇主资料: hiring_organization.same_as字段提供雇主Hellowork公司资料链接，可用于构建雇主级别的聚合。

错误处理

• 缺少必需参数: 状态码400 — 发送前验证输入。
• 列表过期或移除: 状态码404 — 跳过并记录；列表定期过期。
• 抓取器执行失败: 状态码500 — 使用指数退避重试。

法律合规

使用此API需确保符合Hellowork的服务条款以及适用的法国和欧盟数据保护法规（RGPD/GDPR）。职位列表可能包含个人数据，如招聘人员姓名、公司联系信息和薪资信息。应以适当的简化实践处理所有个人数据，避免存储或重新发布超出用例必要范围的内容。

定价计划

• BASIC: 0.00美元/月
• PRO: 15.00美元/月
• ULTRA: 49.00美元/月
• MEGA: 139.00美元/月

技术指标

• 流行度: 9.2
• 服务等级: 100%
• 延迟: 16274ms
• 测试通过率: 100%

提供商信息

• API创建者: kakoto
• 订阅者数量: 2
• 类别: Jobs