# Jobs SHZ Scraper — Schleswig-Holstein Vacancies (`khadinakbar/jobs-sh-scraper`) Actor

Extract public Jobs SHZ vacancies with employer, location, work arrangement, dates, and application links. Use for recruitment research and local labor-market analysis in Schleswig-Holstein. Returns one validated record per vacancy. Charged $0.003 per vacancy plus a $0.00005 start event.

- **URL**: https://apify.com/khadinakbar/jobs-sh-scraper.md
- **Developed by:** [Khadin Akbar](https://apify.com/khadinakbar) (community)
- **Categories:** Jobs, Automation, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 vacancy scrapeds

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#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

## Jobs SHZ vacancy scraper

Turn a Jobs SHZ keyword or public listing URL into one structured vacancy record per job. Recruitment teams, staffing researchers, and regional labor-market analysts receive the employer, location, job category, work arrangement, dates, public description, and source URL required to assess an opportunity in Schleswig-Holstein.

### Best fit for this Actor

- Start with a German role keyword such as `Pflegefachkraft`, `Elektroniker`, or `Softwareentwickler`, or provide a public `jobs.shz.de` search/job URL.
- Select `concise` for compact agent-ready records and `detailed` for richer public job descriptions.
- Use one focused query per run and set `maxResults` to the number of vacancies your workflow can evaluate.

### Standalone workflow

This actor works as a focused standalone workflow for Jobs SHZ, the regional Schleswig-Holstein board reached through `jobs.sh`.

### Workflow: monitor nursing vacancies in Schleswig-Holstein

A staffing researcher starts with `Pflegefachkraft` and requests 20 records. The actor reads the live Jobs SHZ search pages, follows each public vacancy page, and returns title, employer, location, posting date, and public source URL. The researcher can then export the dataset, compare active employers, and keep the source URLs for a later freshness check.

### Quick start input

```json
{
  "searchQuery": "Pflegefachkraft",
  "maxResults": 20,
  "includeJobDetails": true,
  "responseFormat": "concise"
}
```

`searchQuery` uses the live Jobs SHZ public index. `maxResults` limits returned rows and establishes the maximum number of billable vacancy events for that run.

### Input reference

| Field | Type | What it controls |
| --- | --- | --- |
| `searchQuery` | string | A Jobs SHZ keyword, for example `Pflegefachkraft`; blank collects the newest listings. |
| `startUrls` | array | Public Jobs SHZ search or job-detail URLs; these override the keyword when supplied. |
| `maxResults` | integer | A 1–200 record cap; default 20. |
| `includeJobDetails` | boolean | Opens each public vacancy page for its description and richer fields; default `true`. |
| `responseFormat` | enum | `concise` limits description text to 1,200 characters; `detailed` allows 8,000 characters. |

### What data you receive

Every dataset item represents one public Jobs SHZ vacancy. Stable semantic fields include `jobId`, `title`, `companyName`, `location[]`, `occupationalFields[]`, `remoteOptions[]`, `postedAt`, `applicationUrl`, `sourceUrl`, and `scrapedAt`.

```json
{
  "jobId": "1990313",
  "title": "Elektroniker für IT-gestützte Systeme (m/w/d)",
  "companyName": "Example GmbH",
  "location": ["Kiel, Deutschland"],
  "occupationalFields": ["Elektrotechnik"],
  "postedAt": "ISO 8601 publication timestamp",
  "sourceUrl": "https://jobs.shz.de/job/example-1990313",
  "scrapedAt": "ISO 8601 collection timestamp",
  "source": "jobs-shz"
}
```

The `sourceUrl` identifies the canonical public vacancy page and supports freshness checks. `scrapedAt` records the collection time. When a result cap truncates a search, narrow the keyword or use an additional focused query for the next page of work.

### Use through the API

Start an execution with your Apify token, then read the default dataset linked in the completed execution response.

```bash
curl -X POST "https://api.apify.com/v2/acts/khadinakbar~jobs-sh-scraper/runs?token=<APIFY_TOKEN>" \
  -H 'Content-Type: application/json' \
  -d '{"searchQuery":"Pflegefachkraft","maxResults":20,"responseFormat":"concise"}'
```

Use the returned default dataset URL to export JSON, CSV, XLSX, or another Apify dataset format.

### Use with AI agents through Apify MCP

> Find up to 20 current nursing vacancies on Jobs SHZ. Return the title, employer, location, posting date, and public source URL as concise records.

After the call, inspect `OUTPUT.outcome`, read the default dataset, and preserve `sourceUrl` plus `scrapedAt` in downstream decisions. Set a bounded `maxResults` before an agent runs the actor. Use [Apify MCP](https://mcp.apify.com) for current client-specific setup.

### Pricing

This Actor uses **Pay per event**. It charges **$0.003 per validated vacancy** and **$0.00005 per actor start**; these event prices cover the platform usage for this Actor. Open the live pricing tab for the current event details and use `maxResults` plus Apify run cost controls to keep the workflow aligned with your budget.

### Best results

- Use the German role vocabulary that candidates and employers use on Jobs SHZ, such as `Pflegefachkraft` or `Elektroniker`.
- Keep one role or research question per run, then export each bounded dataset for clear comparisons.
- Enable job details when descriptions, company pages, or application workflow signals matter to the decision.
- Retain `sourceUrl` and `scrapedAt` whenever a workflow needs repeatable provenance or freshness checks.

### Builder's note

I designed this actor around the structured data Jobs SHZ renders into every public Next.js page before the browser executes its interface. In my testing, reading that server-rendered payload and validating each normalized row before storage kept the output stable while supporting the normal search and detail workflow without a browser dependency.

### Responsible use

Use public or authorized data in accordance with applicable terms and laws. Keep vacancy records connected to legitimate recruitment, market research, and job-monitoring workflows.

# Actor input Schema

## `searchQuery` (type: `string`):

Keyword search sent to Jobs SHZ, for example 'Pflegefachkraft' or 'Softwareentwickler'. The site matches its public vacancy index and accepts German job terms. Leave blank to collect the newest listings across the board. This is not a URL or an applicant name.

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

Optional public Jobs SHZ search or job-detail URLs to collect, for example 'https://jobs.shz.de/jobs?search=Pflege'. The actor uses these instead of Job search query when provided. Up to 20 URLs are accepted. Do not provide login, applicant, or employer-admin pages.

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

Maximum number of validated vacancy records to return. Enter an integer from 1 to 200; the default is 20. The per-vacancy event charges stop at this cap, keeping event costs bounded. This is not a page count.

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

Whether to open each public vacancy page for its description and additional fields. Keep enabled for recruitment research and detailed records. Default is true; disabling it returns listing-level fields faster. This does not access private applicant data.

## `responseFormat` (type: `string`):

Controls the maximum public description length in every dataset record. Choose 'concise' for short agent-friendly records or 'detailed' for up to 8,000 characters of job text. Defaults to concise. This does not translate or summarize the original German content.

## Actor input object example

```json
{
  "searchQuery": "Pflegefachkraft",
  "startUrls": [
    {
      "url": "https://jobs.shz.de/jobs?search=Pflegefachkraft"
    }
  ],
  "maxResults": 20,
  "includeJobDetails": true,
  "responseFormat": "concise"
}
```

# Actor output Schema

## `vacancies` (type: `string`):

Validated Jobs SHZ vacancy records.

## `summary` (type: `string`):

Terminal outcome and diagnostics.

## `output` (type: `string`):

Stable machine-readable result summary.

# 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 = {
    "searchQuery": "Pflegefachkraft",
    "startUrls": [
        {
            "url": "https://jobs.shz.de/jobs?search=Pflegefachkraft"
        }
    ],
    "maxResults": 10,
    "includeJobDetails": true,
    "responseFormat": "concise"
};

// Run the Actor and wait for it to finish
const run = await client.actor("khadinakbar/jobs-sh-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 = {
    "searchQuery": "Pflegefachkraft",
    "startUrls": [{ "url": "https://jobs.shz.de/jobs?search=Pflegefachkraft" }],
    "maxResults": 10,
    "includeJobDetails": True,
    "responseFormat": "concise",
}

# Run the Actor and wait for it to finish
run = client.actor("khadinakbar/jobs-sh-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 '{
  "searchQuery": "Pflegefachkraft",
  "startUrls": [
    {
      "url": "https://jobs.shz.de/jobs?search=Pflegefachkraft"
    }
  ],
  "maxResults": 10,
  "includeJobDetails": true,
  "responseFormat": "concise"
}' |
apify call khadinakbar/jobs-sh-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,khadinakbar/jobs-sh-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/eEmG7ByAaXJgmUPHY/builds/BbhKYGBupslgUP8bO/openapi.json