# Arbeitsagentur Jobs API – Germany Job Search (Jobbörse) (`extractlyspace/german-jobs-scraper`) Actor

Returns job openings in Germany from the Federal Employment Agency's job board (Arbeitsagentur): title, employer, town, postal code, coordinates, posting date and link. Search by keyword, place and radius; filter by working time and offer type. Optional full description. No login needed.

- **URL**: https://apify.com/extractlyspace/german-jobs-scraper.md
- **Developed by:** [Spase Nikolov](https://apify.com/extractlyspace) (community)
- **Categories:** Jobs, Automation
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.40 / 1,000 jobs

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?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Arbeitsagentur Jobs API – Germany Job Search (Jobbörse)

This Actor returns job openings in Germany from the Federal Employment Agency's job board (Arbeitsagentur), read live at run time. Each row has the job title, employer, town, postal code, coordinates, posting date, working time, home office, contract type, stated pay and a link to the job, plus the job description as plain text (up to 20,000 characters) if you ask for it. Search by keyword, place and radius; filter by working time, offer type and how recently the job was published. No login is needed.

### Use this to

- **Search for jobs in Germany**: "Find part-time Pflegefachkraft jobs within 30 km of Hamburg, published in the last 7 days."
- **Find apprenticeships**: "Which Ausbildung places for Mechatroniker are open around Stuttgart?"
- **Monitor a local job market**: "Every morning, list the new Softwareentwickler jobs in Berlin and Potsdam" (schedule a run with `onlyNew` turned on).

### Sample output

| recordType | title | company | location | postedAt | isRemote | applyUrl |
|---|---|---|---|---|---|---|
| job | Softwareentwickler (m/w/d) | Beispiel GmbH | 10115 Berlin | 2026-11-12 | null | https://www.arbeitsagentur.de/jobsuche/jobdetail/10001-1000000000-S |

These values are invented for illustration. Every job row has the same 23 fields: `recordType`, `jobId`, `title`, `occupation`, `company`, `location`, `city`, `postalCode`, `region`, `country`, `latitude`, `longitude`, `postedAt`, `startDate`, `url`, `applyUrl`, `isRemote`, `employmentType`, `contractType`, `salaryText`, `description`, `source` and `scrapedAt`. A value the job board does not provide is returned as `null`. `title` is the job's title, or the occupation when the ad has none. `company` is `null` for an anonymous ad. `postalCode` keeps a leading zero. `postedAt` is a date without a time. `url` is the job's public page; `applyUrl` is the ad's external application link when it has one, otherwise `url`. `source` is always `arbeitsagentur`. `region` and `country` are written out, such as `Sachsen-Anhalt` and `Deutschland`. `isRemote` is true when the ad says home office is possible, false when it says it is not, and `null` when it does not say. `employmentType` lists the working time the ad offers (`full_time`, `part_time`, `shift_night_weekend`, `remote`, `mini_job`), joined by commas. `contractType` is `permanent` or `temporary`. `salaryText` is filled when the ad states an amount, such as `55000 EUR per year` or `14–16 EUR per hour`. `description` is filled only with `includeDescription`.

### Pricing

Draft prices, not final. You pay per event:

- `job`: $0.0004 for each job returned.
- `job-description`: $0.0003 more for each job that has a description, only when `includeDescription` is on. A job returned with its description therefore costs $0.0007.

Examples: 50 jobs cost $0.02. 50 jobs with descriptions cost $0.035.

Explanatory rows (see below) are never charged. The run stops when it reaches your spending limit.

### Input

- **keywords**: job title words, one search per keyword, up to 10. German titles work best, such as `Softwareentwickler` or `Pflegefachkraft`.
- **locations**: German towns or postal codes, up to 10, such as `Berlin`, `München` or `01067`. Each keyword is searched in each location, at most 20 searches per run. Send at least one of `keywords` and `locations`.
- **radiusKm**: search radius around each location, 0 to 200 km (default 25). Used only with a location.
- **postedWithinDays**: only jobs published in the last N days, 1 to 100.
- **workingTime**: `full_time`, `part_time`, `shift_night_weekend`, `remote` or `mini_job`; leave empty for all. `remote` means "home office possible": it keeps only jobs whose ad says so, also when combined with other values.
- **offerType**: `job` (default), `apprenticeship` (Ausbildung or dual study), `internship` (also trainee) or `self_employment`.
- **excludeStaffingAgencies**: leave out jobs offered by temporary staffing agencies (default off).
- **maxJobs**: the most jobs to return in total, 1 to 1000 (default 50). Each returned job is charged. Searches are read in the order given until the limit is reached; a job found by two searches is returned once.
- **includeDescription**: adds the description as plain text, up to 20,000 characters (default off). It is charged as an add-on for each job that has one, and the run is slower because the Actor reads each job's page.
- **onlyNew**: returns only jobs this Actor has not returned to you before for the same searches and offer type (default off).

### What you get when nothing matches

An input the form itself rejects, such as a text where a list belongs, is refused before the run starts. When nothing matches or the input needs correcting in another way, the run succeeds and returns a short explanatory row instead of an empty result. The run fails, with a clear message, only when the job board could not be read and nothing was returned. The explanatory row has `recordType: "status"`, a `message` in plain language and a `subject`. The `status` is one of:

- `invalid_input`: no keyword and no location (`Send at least one of: keywords, locations. Example: {"keywords": ["Softwareentwickler"], "locations": ["Berlin"]}`), or more than 20 searches (`Too many searches: N keyword and location combinations, at most 20 per run. Send fewer keywords or locations.`).
- `no_results`: `No job on the Arbeitsagentur job board matches the search.` or, with `onlyNew`, `No new jobs since the last run.`
- `partial`: `The job board could not be read for LABEL right now; this search was skipped. Try again later.` or `N jobs are returned without a description: the job board did not answer for them. Try again later.` LABEL is `"keyword" in "location"`, `"keyword"`, or `jobs in "location"`. The jobs that were read are returned.
- `limit_reached`: `Stopped: the spending limit for this run was reached. Delivered N jobs.`

### What it never returns

No contact persons, no phone numbers or email addresses of contacts, and nothing about applicants. The description is the ad's own text with email addresses and clearly formatted phone numbers removed; it may still mention people the employer chose to name.

### FAQ

**Where does the data come from?** From the public job board of the Federal Employment Agency (Bundesagentur für Arbeit), read live when the run happens. The Actor keeps no copy of its own. It is not an official API of the agency and is not affiliated with or endorsed by the agency.

**Which search words work best?** German job titles and German town names: `Erzieher`, `Elektroniker`, `München`, `Köln`. English words find fewer jobs.

**Does it find every job in Germany?** No. It returns what the job board lists for your search at the time of the run; completeness is not promised.

**Do I need an account?** No. The Actor reads only the public job board.

**How does `onlyNew` remember jobs?** The Actor stores the IDs of jobs it has returned in a key-value store named `german-jobs-scraper-seen` in your own Apify account, separately for each set of searches and offer type. A later run with the same searches skips them.

This Actor reports usage statistics to its developer to keep it reliable: the Actor's name and build number, the time of the run, the run's outcome, row counts, events charged, an estimate of the revenue from those events, an estimate of what paid data sources cost for the run (always zero for this Actor), duration, a short error category when a run fails, partly fails or meets upstream data in an unexpected shape, how the run was started, whether the account is on a paid plan, and a one-way hash of the Apify user ID. It never reports your inputs or the data returned.

# Actor input Schema

## `keywords` (type: `array`):

Job title words, one search per keyword, up to 10. German titles work best. Send at least one of keywords and locations. Example: \["Softwareentwickler", "Pflegefachkraft"]

## `locations` (type: `array`):

German towns or postal codes, up to 10. Each keyword is searched in each location, at most 20 searches per run. Send at least one of keywords and locations. Example: \["Berlin", "München", "01067"]

## `radiusKm` (type: `integer`):

Search radius around each location, from 0 to 200 km. Used only with a location. Example: 50

## `postedWithinDays` (type: `integer`):

Only jobs published in the last N days, from 1 to 100. Leave empty for all open jobs. Example: 7 for the last week

## `workingTime` (type: `array`):

Optional working-time filter. Values: full_time, part_time, shift_night_weekend, remote, mini_job. remote means "home office possible" and keeps only such jobs, also when combined with other values. Leave empty for all. Example: \["part_time", "remote"]

## `offerType` (type: `string`):

What kind of offer to search. Values: job, apprenticeship (Ausbildung or dual study), internship (also trainee), self_employment. Example: apprenticeship

## `excludeStaffingAgencies` (type: `boolean`):

Leave out jobs offered by temporary staffing agencies (Zeitarbeit). Example: true

## `maxJobs` (type: `integer`):

The most jobs to return in total, from 1 to 1000. Each returned job is charged. Searches are read in the order given. Example: 50

## `includeDescription` (type: `boolean`):

Add the job description as plain text, up to 20,000 characters. Charged as an add-on for each job that has one, and slower. Example: true

## `onlyNew` (type: `boolean`):

Return only jobs this Actor has not returned to you before for the same searches. Use it for scheduled monitoring. Example: true

## Actor input object example

```json
{
  "keywords": [
    "Softwareentwickler"
  ],
  "locations": [
    "Berlin"
  ],
  "radiusKm": 25,
  "workingTime": [],
  "offerType": "job",
  "excludeStaffingAgencies": false,
  "maxJobs": 5,
  "includeDescription": false,
  "onlyNew": false
}
```

# Actor output Schema

## `jobs` (type: `string`):

One row per job opening (recordType "job"). A run that could return nothing gives an explanatory row instead (recordType "status", with status, message and subject).

# 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 = {
    "keywords": [
        "Softwareentwickler"
    ],
    "locations": [
        "Berlin"
    ],
    "maxJobs": 5
};

// Run the Actor and wait for it to finish
const run = await client.actor("extractlyspace/german-jobs-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 = {
    "keywords": ["Softwareentwickler"],
    "locations": ["Berlin"],
    "maxJobs": 5,
}

# Run the Actor and wait for it to finish
run = client.actor("extractlyspace/german-jobs-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 '{
  "keywords": [
    "Softwareentwickler"
  ],
  "locations": [
    "Berlin"
  ],
  "maxJobs": 5
}' |
apify call extractlyspace/german-jobs-scraper --silent --output-dataset

```

## MCP server setup

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