# SEEK Search

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/seek/search` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 2 credits per call |
| **Documentation** | https://www.piloterr.com/library/seek-search |

## Description

Search SEEK Australia jobs by keyword or by a results URL.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/seek/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Nurse jobs, first card

```json
{
  "results": [
    {
      "id": "95568355",
      "url": "https://www.seek.com.au/job/95568355",
      "title": "Telehealth Nurse (RN or EN)",
      "salary": 45,
      "company": "Reorg Solutions",
      "currency": "AUD",
      "location": "Sydney NSW",
      "listed_at": "1d ago",
      "work_type": "This is a Casual/Vacation job",
      "salary_max": null,
      "salary_min": null,
      "company_url": "https://www.seek.com.au/Reorg-Solutions-jobs",
      "salary_period": "hour",
      "classification": "Healthcare & Medical",
      "salary_display": "$45 per hour",
      "subclassification": "Nursing - General Medical & Surgical"
    }
  ],
  "pagination": {
    "next": "https://www.seek.com.au/nurse-jobs?page=2",
    "page": 1,
    "per_page": 32,
    "total_pages": null,
    "total_results": 7894
  }
}
```

## Documentation

## Overview
Search jobs on SEEK Australia. A keyword such as `nurse` becomes `https://www.seek.com.au/nurse-jobs`. A SEEK results URL that ends in `-jobs` or contains `/jobs` is also accepted. The response is `{ results, pagination }` with the title, company, location, work type, classification, and the salary label SEEK prints.

`salary` is set when the label is a single amount, including cents, such as `$45 per hour` or `$52.54 per hour`. A range such as `$80,000 – $100,000 per year` leaves `salary` null and fills `salary_min` and `salary_max`. `salary_display` is the label itself. `currency` is `AUD` when the label contains `$`.

## Quickstart
```
GET https://api.piloterr.com/v2/seek/search?query=nurse
GET https://api.piloterr.com/v2/seek/search?query=registered%20nurse&page=2
GET https://api.piloterr.com/v2/seek/search?query=https://www.seek.com.au/nurse-jobs
```
Pass `results[].url` or `results[].id` to `/v2/seek/job`.

## Parameters
| Parameter | Required | Example |
|---|---|---|
| `query` | yes | `nurse` |
| `page` | no | `2` |

`query` is a keyword or a SEEK results URL. A job URL (`/job/95568355`) is rejected here. `page` starts at 1. Omit it for the first page. A `page` already present in a results URL is kept when you omit `page` or pass `1`. A value of `2` or higher overrides it.

## Response fields
| Field | Type | Meaning |
|---|---|---|
| `results[].id` | string | Numeric job id |
| `results[].url` | string | `https://www.seek.com.au/job/<id>` |
| `results[].title` | string or null | Job title |
| `results[].company` | string or null | Advertiser |
| `results[].company_url` | string or null | Advertiser jobs URL |
| `results[].location` | string or null | Location, such as `Sydney NSW` |
| `results[].classification` | string or null | Parent classification |
| `results[].subclassification` | string or null | Subclassification |
| `results[].work_type` | string or null | Line such as `This is a Casual/Vacation job` |
| `results[].listed_at` | string or null | Relative time, such as `1d ago` |
| `results[].salary_display` | string or null | Salary label |
| `results[].salary` | number or null | Single amount. Null for a range or a missing label |
| `results[].salary_min` | number or null | Low end of a range |
| `results[].salary_max` | number or null | High end of a range |
| `results[].salary_period` | string or null | `hour`, `day`, `week`, or `year` |
| `results[].currency` | string or null | `AUD` when the label uses `$` |
| `pagination.page` | integer | Page you asked for |
| `pagination.per_page` | integer | Number of jobs on this page |
| `pagination.total_results` | integer or null | Count SEEK prints, such as `7894` |
| `pagination.total_pages` | null | SEEK does not print a page count |
| `pagination.next` | string or null | Next page URL, or null when no next link is present |

## Pagination
`page` starts at 1. Ids are unique on a page. For `nurse`, page 1 has `next` pointing at `?page=2`, and page 2 returns `pagination.page` 2 with `next` pointing at page 3. `next` is null when that link is absent. `total_pages` stays null. One promoted job can appear again on the following page. That repeat is on SEEK's list, and ids on a single page stay unique.

## Use cases
- A hospital group tracks `nurse` vacancies and keeps hourly `salary` values for Sydney roles.
- A recruiter searches `electrician` and follows `pagination.next` until it is null.
- A compensation analyst stores `salary_min` and `salary_max` when the card prints a range.

## Error codes
| Code | Meaning |
|---|---|
| `400` | Empty query, a host other than seek.com.au, or a job URL sent to search |
| `401` | Missing API key |
| `404` | The page had no job cards |
| `500` | The fetch failed |

## Related endpoints
[SEEK Job](https://www.piloterr.com/library/seek-job)