> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pubrio.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 职位搜索
> 按公司、职位名称、职能、职级、国家和上线日期查找在招职位——并读取 Pubrio 为每条职位附加的分类。
[职位搜索](/cn/api-reference/endpoint/companies/job_search)返回 Pubrio 抓取到的在招职位，每条职位一行，并关联到发布该职位的公司。每一行包含原始职位信息（名称、地点、URL、发布日期），以及 Pubrio 根据职位名称派生的三个字段：`functions`、`seniority_rank` 和 `location_id`。
```bash theme={null}
curl -X POST https://api.pubrio.com/companies/jobs/search \
-H "pubrio-api-key: $PUBRIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"domains": ["stripe.com"],
"seniority_ranks": [4, 5],
"launch_dates": ["2026-08-01", "2026-08-31"],
"per_page": 25
}'
```
## 适用场景
* **单个客户的招聘信号**——传入公司，查看他们在招什么岗位、在哪里、什么级别。
* **按角色找潜在客户**——在某个国家搜索正在开放资深工程或销售岗位的公司，再用每行的 `domain_search_id` 跳转到[人员搜索](/cn/api-reference/endpoint/people/search)。
* **增量同步**——把 `created_at` 设为你已存储的最新抓取时间进行轮询。
如果你需要的是统计而不是行，请使用[职位洞察](/cn/api-reference/endpoint/companies/job_insights)。如果你希望在公司发布职位时收到通知，请创建一个 `signal_types: ["jobs"]` 的[监控器](/cn/developer-guides/examples/tracking-job-postings)。
## 限定到公司
最快的搜索是指定公司。三种标识符都解析到同一条记录，可以混用：
| 键 | 值 | 说明 |
| --------------- | --------------------------------------------- | --------------------------------------------- |
| `domains` | `["stripe.com"]` | `https://www.stripe.com/jobs` 这类 URL 会被规范化为域名 |
| `linkedin_urls` | `["https://www.linkedin.com/company/stripe"]` | 仅限公司主页 |
| `companies` | `["5378845d-7726-4817-aba9-ced8c5f41dee"]` | 任意此前响应中的 `domain_search_id` |
不指定公司的搜索也是允许的——`{"locations": ["SG"], "seniority_ranks": [5]}` 可以正常工作——但会针对整个索引计数。此时 `total_entries` 是估算值，在非常宽泛的筛选下 `is_timeout` 可能为 `true`。
## 筛选器
### 文本
| 键 | 类型 | 匹配 |
| -------------- | ---------- | ---------------------------------------------------------------------- |
| `titles` | `string[]` | 职位名称。按词匹配，因此 `["engineer"]` 也会返回 `Senior Software Engineer`。匹配任一列出的名称。 |
| `search_term` | `string` | 针对职位名称的自由文本。 |
| `search_terms` | `string[]` | 多个自由文本词，任一匹配即可。 |
### 分类
| 键 | 类型 | 匹配 |
| ----------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `functions` | `string[]` | 根据职位名称派生的职能 slug：`engineering`、`sales`、`marketing`、`finance`、`product_management` 等。匹配任一列出的 slug。见[职能](/cn/api-reference/enums#职能)。 |
| `seniority_ranks` | `integer[]` | `1` 初级 · `2` 资深 · `3` 经理 · `4` 总监 · `5` 高管。见[职级层级](/cn/api-reference/enums#职级层级)。 |
两者对错误输入的处理不同。未知的 `functions` slug 返回**零**行；`seniority_ranks` 中 1–5 以外的值会被**忽略**并返回所有行。两者都不会报错。
### 日期
| 键 | 类型 | 匹配 |
| -------------- | ------------ | ----------------------------------------------------------------------------------------- |
| `launch_dates` | `[from, to]` | 职位的上线日期——发布方给出 `posting_date` 时使用它，否则使用 Pubrio 首次看到该职位的日期。UTC 日期边界；可与职位洞察对账，**默认请使用此参数。** |
| `posted_dates` | `[from, to]` | 仅 `posting_date`。日期边界遵循你的工作区时区。 |
| `created_at` | 日期或 ISO 时间戳 | 在该时刻当时或之后抓取（UTC）。增量轮询时传入你已存储的最新一行的精确 `created_at`。 |
两个窗口都是闭区间。`launch_dates` 只传一个元素时匹配当天。
### 地点
| 键 | 类型 | 匹配 |
| ------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------- |
| `locations` | `string[]` | 职位所在国家，ISO alpha-2。 |
| `exclude_locations` | `string[]` | 要排除的职位所在国家。 |
| `location_ids` | `integer[]` | 按 Pubrio `location_id` 指定职位所在国家，与 [Locations](/cn/api-reference/endpoint/locations/locations) 端点及每行 `location_id` 中的数字一致。 |
| `company_locations` | `string[]` | **公司总部**所在国家，可能与职位所在地不同。 |
### 分页与排序
| 键 | 默认值 | 说明 |
| -------------------- | ------- | -------------------------------------------------------- |
| `per_page` | 25 | 受套餐的 `max_search_per_page` 限制。 |
| `page` | 1 | 受 `max_search_page` 限制；响应中的 `total_display_pages` 告诉你上限。 |
| `is_ascending_order` | `false` | 行按 `created_at` 排序，最新在前。`true` 则改为最旧在前。 |
## 一行数据的样子
```json theme={null}
{
"job_id": "4418496a-6a4f-4432-8910-50153e9ba27c",
"job_search_id": "4418496a-6a4f-4432-8910-50153e9ba27c",
"created_at": "2026-08-30T00:02:52.531Z",
"last_modified": "2026-09-01T16:08:09.324Z",
"title": "Finance and Strategy Partner",
"job_url": "https://www.linkedin.com/jobs/view/4460586030",
"location": "United States",
"location_id": 357,
"country": "United States",
"country_code": "US",
"posting_date": "2026-08-29",
"source_type": "linkedin",
"functions": ["consulting"],
"seniority_rank": 5,
"base_salary": null,
"experience_requirement": null,
"education_requirement": null,
"employment_type": null,
"companies": {
"domain_search_id": "5378845d-7726-4817-aba9-ced8c5f41dee",
"company_name": "Stripe",
"linkedin_name": "stripe",
"country_code": "US",
"company_url": "https://stripe.com/",
"domain": "stripe.com",
"logo_url": "https://buckets.pubrio.com/company-logo/....jpg"
}
}
```
* 职位名称无法分类时，`functions` 为 `null`、`seniority_rank` 为 `0`。照常用它们筛选即可——未分类的行只是不会匹配。
* `posting_date` 是发布方的日期；`created_at` 是 Pubrio 首次看到该职位的时间，也是默认排序键。
* `job_id` 和 `job_search_id` 是同一个值；任一都可传给[职位查询](/cn/api-reference/endpoint/companies/job_lookup)。
### 相信结果前先读 `metadata`
```json theme={null}
"metadata": {
"profile": null,
"filters": { "domains": ["stripe.com"], "seniority_ranks": [4, 5], "per_page": 25, "language": "en" },
"ignored_fields": []
}
```
`ignored_fields` 列出端点无法识别的所有请求键。像 `"seniorty_ranks"` 这样的拼写错误不会让请求失败——它会静默扩大搜索范围。在任何自动化流程中都要检查该数组为空。
## 示例
```bash cURL theme={null}
curl -X POST https://api.pubrio.com/companies/jobs/search \
-H "pubrio-api-key: $PUBRIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"domains": ["stripe.com", "adyen.com", "checkout.com"],
"functions": ["engineering", "data_science"],
"seniority_ranks": [3, 4, 5],
"launch_dates": ["2026-08-05", "2026-09-04"],
"per_page": 25
}'
```
```python Python theme={null}
import os, requests
r = requests.post(
"https://api.pubrio.com/companies/jobs/search",
headers={"pubrio-api-key": os.environ["PUBRIO_API_KEY"], "Content-Type": "application/json"},
json={
"domains": ["stripe.com", "adyen.com", "checkout.com"],
"functions": ["engineering", "data_science"],
"seniority_ranks": [3, 4, 5],
"launch_dates": ["2026-08-05", "2026-09-04"],
"per_page": 25,
},
)
body = r.json()
assert body["metadata"]["ignored_fields"] == []
for job in body["data"]["jobs"]:
print(job["companies"]["company_name"], "-", job["title"], job["seniority_rank"])
```
```bash cURL theme={null}
curl -X POST https://api.pubrio.com/companies/jobs/search \
-H "pubrio-api-key: $PUBRIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"locations": ["SG"],
"functions": ["sales", "business_development"],
"seniority_ranks": [4, 5],
"launch_dates": ["2026-08-01", "2026-09-04"],
"per_page": 25
}'
```
按 `companies.domain_search_id` 对行分组——每家不同的公司都是一个潜在客户，该 id 可直接放入[人员搜索](/cn/api-reference/endpoint/people/search)的 `companies`。
```python Python theme={null}
import os, requests
API = "https://api.pubrio.com/companies/jobs/search"
HEADERS = {"pubrio-api-key": os.environ["PUBRIO_API_KEY"]}
def sync(domains, since):
"""获取在 `since`（ISO 时间戳）当时或之后抓取的所有职位，返回新的游标。"""
newest = since
page = 1
while True:
body = requests.post(API, headers=HEADERS, json={
"domains": domains, "created_at": since, "page": page, "per_page": 25,
}).json()
rows = body["data"]["jobs"]
if not rows:
break
for job in rows: # 最新在前
newest = max(newest, job["created_at"])
print(job["job_id"], job["title"]) # 在这里 upsert 到你的存储
if page >= body["data"]["pagination"]["total_display_pages"]:
break
page += 1
return newest
cursor = sync(["stripe.com"], "2026-09-01T00:00:00Z")
# 持久化 `cursor`，下次运行时作为 `since` 传入
```
游标是你已存储的最新一行的完整 `created_at`，因此下次运行只会重复返回那一行。请按 `job_id` 做 upsert。行按最新在前返回，所以繁忙的一天也不会让游标越过套餐的页数上限。
## 相关
所有参数和响应字段。
单家公司按职能、职级、国家和周的统计。
职级层级和完整的职能词表。
用 webhook 代替轮询。