# TotalJobs Scraper - UK Jobs & Salaries (`santamaria-automations/totaljobs-scraper`) Actor

Extract UK job listings from TotalJobs.com. Returns title, company, salary (min/max/currency/period), full description, employment type, location, posting date, apply URL, and 30+ more fields. Search by keyword, location, or URL. Pay-per-result: $3 per 1,000 jobs.

- **URL**: https://apify.com/santamaria-automations/totaljobs-scraper.md
- **Developed by:** [NanoScrape](https://apify.com/santamaria-automations) (community)
- **Categories:** Jobs, Lead generation
- **Stats:** 4 total users, 3 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## TotalJobs Scraper - UK Jobs, Salaries and Descriptions

Extract job listings from [TotalJobs.com](https://www.totaljobs.com), the UK's largest independent job board and flagship brand of Totaljobs Group (StepStone-Xing). Search by keyword, location, or paste any TotalJobs URL. Full-detail mode delivers structured salary, HTML and Markdown descriptions, and contact extraction.

### What it does

- Searches TotalJobs via the same JSON API the website uses (no HTML scraping for SERPs)
- SERP-only mode returns 22 fields per job including title, company, salary (min/max/currency/period), location, and snippet
- Full-detail mode adds the complete description (text, HTML, Markdown), employment type, ISO posting dates, and extracted contact info
- Results stream to the dataset as each job is extracted - no waiting for the full run to finish
- Deduplicates across multiple queries by job ID
- Strips Emotion CSS-in-JS artifacts from descriptions before delivery

### Sample output

```json
{
  "_type": "job",
  "id": "107247777",
  "title": "Senior Software Engineer",
  "job_url": "https://www.totaljobs.com/job/senior-software-engineer/mcgregor-boyall-job107247777",
  "source_url": "https://www.totaljobs.com/job/senior-software-engineer/mcgregor-boyall-job107247777",
  "company_name": "McGregor Boyall Associates Limited",
  "company_logo_url": "https://www.totaljobs.com/CompanyLogos/c8ddb65522b549209fafb5ab49f14314.png",
  "location": "London",
  "country": "UK",
  "postcode": "EC2A",
  "salary_min": 65000,
  "salary_max": 75000,
  "salary_currency": "GBP",
  "salary_period": "year",
  "salary_text": "From £65,000 to £75,000 per annum",
  "employment_type": "Full-time",
  "description": "You will be joining an engineering-led team building greenfield software...",
  "description_full": "You will be joining an engineering-led team building greenfield software...",
  "description_html": "<p>You will be joining an engineering-led team...</p>",
  "description_md": "You will be joining an engineering-led team...",
  "posted_at_text": "2026-05-07T09:22:20Z",
  "posted_at_datetime": "2026-05-07T09:22:20Z",
  "expires_at": "2026-06-18T09:22:20Z",
  "apply_url": null,
  "contact_emails": [],
  "contact_phones": [],
  "contact_urls": [],
  "search_query": "software engineer",
  "scraped_at": "2026-08-22T10:00:00Z",
  "source_platform": "totaljobs.com"
}
```

### Pricing

| Event | Price | When charged |
|-------|-------|-------------|
| Actor start | $0.001 | Once per run |
| SERP result | $0.003 | Per job in fast mode (includeJobDetails=false) |
| Detail result | $0.005 | Per job in full-detail mode (includeJobDetails=true) |

SERP-only mode: **$3 per 1,000 jobs**. Full-detail mode: **$5 per 1,000 jobs**. The two events are mutually exclusive: one is charged per job, not both.

New Apify accounts get **$5 free monthly credit** - enough for ~1,000 full-detail results at no cost.

### Input

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| searchQueries | string\[] | - | Job search keywords. Each runs as a separate search. |
| searchUrls | string\[] | - | TotalJobs search URLs with filters already applied. |
| startUrls | string\[] | - | Individual job page URLs for full details or alive checks. |
| location | string | - | City, town, or postcode (keywords only, not URLs). |
| includeJobDetails | boolean | false | Fetch full description from each job's detail page. |
| includeCompanyDetails | boolean | false | Resolve employer website from description (deny-list guarded). |
| maxResultsPerQuery | number | 5 | Max results per search query. |
| maxResults | number | 5 | Total cap across all queries. |
| maxConcurrency | number | 3 | Parallel detail page requests. |

### Output fields

**Identity**

- `_type` - always "job"
- `id` - TotalJobs job ID
- `title` - job title
- `job_url` / `source_url` - canonical totaljobs.com URL

**Company**

- `company_name` / `company` - employer name
- `company_logo_url` - company logo from TotalJobs CDN
- `company_url` - TotalJobs employer profile URL
- `company_website` - external employer website (null if not in description or if matches deny-list)

**Location**

- `location` - city or region
- `country` - always "UK"
- `postcode` - postcode if available

**Pay**

- `salary_min`, `salary_max` - structured numbers
- `salary_currency` - always "GBP"
- `salary_period` - year / month / week / day / hour
- `salary_text` - raw salary string from TotalJobs

**Description**

- `description` - plain text with line breaks
- `description_full` - same as description (full text)
- `description_html` - HTML with style/script stripped
- `description_md` - Markdown conversion

**Dates**

- `posted_at_text` - raw ISO date from TotalJobs
- `posted_at_datetime` - ISO 8601
- `expires_at` - ISO 8601

**Contacts**

- `contact_emails` - array (empty if none found)
- `contact_phones` - array (empty if none found)
- `contact_urls` - array, job-board URLs excluded (empty if none found)
- `apply_url` - null (users apply on the TotalJobs page directly)

**Meta**

- `search_query` - the keyword that returned this job
- `scraped_at` - ISO 8601 run timestamp
- `source_platform` - "totaljobs.com"

### Use with AI Agents

Connect directly to Claude, GPT-4, or any MCP-compatible assistant:

```
https://mcp.apify.com?tools=santamaria-automations/totaljobs-scraper
```

### Why this scraper

- Uses the native TotalJobs JSON API - faster and more reliable than HTML scraping
- CSS-in-JS artifacts stripped before delivery - no `.job-ad-display-` pollution in descriptions
- Structured salary parsed automatically - min, max, currency, period
- Three description formats - plain text, HTML, and Markdown - ready for any downstream use
- company\_website deny-list blocks job-board self-referential URLs (totaljobs, cwjobs, reed, indeed, linkedin, glassdoor, monster, cv-library)
- Fleet-standard output with `_type: "job"`, ISO dates, and array contact fields

### Common use cases

- **Job market research** - track salary trends and demand by keyword in the UK
- **Recruitment operations** - feed job listings into ATS or CRM workflows
- **HR analytics** - benchmark titles, pay bands, and location distributions
- **AI-powered job matching** - description\_md ready for embedding and semantic search
- **Lead generation** - contact\_emails and contact\_urls from employer job postings

### Notes

**TotalJobs Group backend**: TotalJobs is the flagship brand of Totaljobs Group (StepStone-Xing). CWJobs (IT specialist) and Milkround (graduate specialist) are sister brands using the same underlying job catalog. This actor covers the full inventory, cwjobs-uk-scraper filters to IT-only, and milkround-uk-scraper filters to graduate-only.

### Related Actors

- [Job Feed](https://apify.com/santamaria-automations/job-feed) - aggregate results from all scrapers into one unified feed
- [Career Site Jobs Scraper](https://apify.com/santamaria-automations/career-site-jobs-scraper) - scrape employer career pages directly
- [Website Job Extractor](https://apify.com/santamaria-automations/website-job-extractor) - extract jobs from any website URL
- [Reed.co.uk Scraper](https://apify.com/santamaria-automations/reed-uk-scraper) - direct UK competitor with 280,000+ listings
- [CWJobs UK Scraper](https://apify.com/santamaria-automations/cwjobs-uk-scraper) - IT specialist vertical, Totaljobs Group family
- [Milkround UK Scraper](https://apify.com/santamaria-automations/milkround-uk-scraper) - graduate specialist vertical, Totaljobs Group family

### Support

Found a bug or have a question? [Open an issue](https://console.apify.com/actors/santamaria-automations~totaljobs-scraper/issues) on the actor page or email **contact@nanoscrape.com**. We respond within 24 hours.

# Actor input Schema

## `searchQueries` (type: `array`):

One or more job search keywords (e.g. 'Software Engineer', 'Data Analyst'). Each runs as a separate search. Results are deduplicated across queries.

## `searchUrls` (type: `array`):

Paste one or more TotalJobs search URLs. Go to totaljobs.com, set your filters, and copy the URL. All filters are preserved automatically.

## `startUrls` (type: `array`):

Paste individual job page URLs for full details or alive checks. Supports any totaljobs.com/job/... URL.

## `location` (type: `string`):

City, town, or postcode. Applied to search keywords only (not search URLs). Leave empty for all UK.

## `includeJobDetails` (type: `boolean`):

Fetch each job's detail page for the full description (text, HTML, Markdown), employment type, salary, and contact extraction. Slower but provides complete data. Charged at job-detail-result rate.

## `includeCompanyDetails` (type: `boolean`):

Resolve the employer's company\_website from the job description. Uses deny-list to reject job-board URLs. Only works when includeJobDetails is also true.

## `maxResultsPerQuery` (type: `integer`):

Maximum results per search keyword or search URL.

## `maxResults` (type: `integer`):

Total cap across all queries. Set to 0 for unlimited.

## `maxConcurrency` (type: `integer`):

Number of detail pages fetched in parallel. Higher is faster. Default 3.

## Actor input object example

```json
{
  "searchQueries": [
    "Software Engineer"
  ],
  "location": "London",
  "includeJobDetails": false,
  "includeCompanyDetails": false,
  "maxResultsPerQuery": 5,
  "maxResults": 5,
  "maxConcurrency": 3
}
```

# Actor output Schema

## `jobListings` (type: `string`):

Dataset containing scraped job listings with 44 fields per job.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "searchQueries": [
        "Software Engineer"
    ],
    "includeJobDetails": false,
    "includeCompanyDetails": false,
    "maxResultsPerQuery": 5,
    "maxResults": 5,
    "maxConcurrency": 3
};

// Run the Actor and wait for it to finish
const run = await client.actor("santamaria-automations/totaljobs-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "searchQueries": ["Software Engineer"],
    "includeJobDetails": False,
    "includeCompanyDetails": False,
    "maxResultsPerQuery": 5,
    "maxResults": 5,
    "maxConcurrency": 3,
}

# Run the Actor and wait for it to finish
run = client.actor("santamaria-automations/totaljobs-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "searchQueries": [
    "Software Engineer"
  ],
  "includeJobDetails": false,
  "includeCompanyDetails": false,
  "maxResultsPerQuery": 5,
  "maxResults": 5,
  "maxConcurrency": 3
}' |
apify call santamaria-automations/totaljobs-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,santamaria-automations/totaljobs-scraper"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/2NTvtogLOnMctWaMD/builds/EZJtnHpwp5PSgb7yC/openapi.json