# Bundesagentur Job Scraper — German Vacancies (`khadinakbar/bundesagentur-job-scraper`) Actor

Search Germany's Bundesagentur für Arbeit public Jobsuche feed and return normalized vacancies with employer, location, contract, remote-work and date signals. Use for recruitment research and labor-market analysis; not for applicant data.

- **URL**: https://apify.com/khadinakbar/bundesagentur-job-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 $2.25 / 1,000 job 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.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md).

If your project is in a different language, use 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

## Bundesagentur Job Scraper

**Bundesagentur Job Scraper** searches public vacancies from Germany's Bundesagentur für Arbeit (BA) Jobsuche API and returns one normalized record per job. Use it for German recruitment research, job-market analysis, vacancy monitoring, and data pipelines that need current roles, employers, locations, work arrangements, dates, and public descriptions.

### When to use it

Use this actor when you need structured public German job listings from the BA Jobsuche catalogue. Start with a role query and a city, then use the result cap to keep a predictable collection size. The actor can also enrich specific BA reference numbers returned by an earlier collection.

Its focused public-vacancy scope works well alongside your authorized ATS or company-career data sources when a workflow also needs those sources. This actor requests the public BA listing and detail endpoints and keeps the returned dataset centered on vacancy information.

### What each job record includes

| Field | Meaning |
| --- | --- |
| `jobId`, `title`, `companyName` | BA reference number, role title, and published employer |
| `location`, `postalCode`, `region` | Published job location |
| `employmentOfferType`, `contractDuration`, `workTime` | Offer, contract, and working-time signals |
| `remotePossible`, `careerChangeSuitable` | Public BA eligibility flags when available |
| `description`, `salaryText` | Public description and salary statement when published |
| `postedAt`, `updatedAt`, `availableFrom` | Vacancy timing metadata |
| `externalUrl`, `sourceUrl`, `scrapedAt` | Public application/source links and provenance |

### Input example

```json
{
  "searchQuery": "Softwareentwickler",
  "location": "Berlin",
  "radiusKm": 25,
  "maxResults": 20,
  "includeJobDetails": true,
  "responseFormat": "concise"
}
````

### Output example

```json
{
  "jobId": "12288-4891612390-S",
  "title": "Softwareentwickler Oracle (m/w/d)",
  "companyName": "Example GmbH",
  "location": "Berlin, Deutschland",
  "employmentOfferType": "ARBEIT",
  "contractDuration": "UNBEFRISTET",
  "workTime": ["full-time"],
  "remotePossible": false,
  "description": "Develop and maintain software systems…",
  "postedAt": "YYYY-MM-DD",
  "externalUrl": "https://careers.example.com/jobs/123",
  "source": "bundesagentur-fuer-arbeit",
  "scrapedAt": "YYYY-MM-DDTHH:MM:SS.000Z"
}
```

### Pricing

This actor uses **Pay per event + platform usage**. It charges `$0.00005` for actor start and `$0.00225` for each validated job persisted to the dataset; Apify platform compute and storage usage are additional. `maxResults` caps job events, so a collection requesting 20 results has a maximum job-event charge of `$0.045` plus the start event and platform usage. Check the live Actor Pricing tab for the current effective event prices and platform-usage details.

### API and MCP use

Run through the Apify API with the same input object:

```bash
curl -X POST 'https://api.apify.com/v2/acts/khadinakbar~bundesagentur-job-scraper/runs?token=YOUR_APIFY_TOKEN' \
  -H 'content-type: application/json' \
  -d '{"searchQuery":"Data Engineer","location":"München","maxResults":10}'
```

Agents can call this actor when they need public German BA vacancies with explicit location and result limits.

> Use the Bundesagentur Job Scraper to collect up to 10 Data Engineer vacancies within 25 km of Berlin. Request concise public details, inspect the dataset readback, cite each `sourceUrl` and `scrapedAt`, and report the collection outcome with the bounded job-event cost.

### Reliability and result semantics

Every collection writes compact `OUTPUT` and detailed `RUN_SUMMARY` records. Outcome records distinguish a complete collection, a valid empty search, a user-input refinement, a partial collection that preserves useful records, and a source-availability result. Detail enrichment complements listing-level collection, allowing a valid listing record to remain useful when a detail response is temporarily unavailable.

### Best results

Use German role terminology, a specific city, and 10–25 results for a focused current-market sample. Choose `detailed` only when downstream workflows truly need longer descriptions. Use returned `jobId` values in `jobReferenceNumbers` to refresh known vacancies without repeating a broad search. Larger collections continue through the public result pages until `maxResults` is reached.

### Builder's note

I designed this actor around BA's structured public API rather than browser rendering, which keeps small focused searches quick and makes provenance explicit. My goal is a compact, stable job record that works cleanly in recruiting and labor-market workflows while preserving source freshness through `sourceUrl` and `scrapedAt`.

### Focused standalone workflow

This actor works as a focused standalone workflow for current German vacancy collection. Start with a role and location, validate the returned public fields, then schedule the same bounded input when a workflow needs a consistent time series.

### Legal and responsible use

Data comes from public Bundesagentur für Arbeit Jobsuche responses, with `sourceUrl` and `scrapedAt` on every record. Respect applicable law, the source's terms, and your users' privacy; keep workflows focused on public vacancy information.

### Related workflow

For a broader German hiring view, combine this BA feed with company-career-page or ATS-specific data where you have an appropriate public source. Keep source attribution and freshness fields when merging datasets.

### Feedback

If an API field changes or a result needs a new normalized field, open an issue with a redacted sample reference number and the expected public field.

# Actor input Schema

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

Free-text role, skill, or occupation query for Bundesagentur Jobsuche, for example 'Softwareentwickler'. It accepts normal German search text and defaults to 'Softwareentwickler'. Use it with Location for local searches or leave the default for the quality-test search. This is not a listing URL or an applicant query.

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

City, district, postal code, or German region around which to search, for example 'Berlin'. It is optional and defaults to 'Berlin' for a dependable initial search. Radius only applies when this field is supplied. This is not a free-form employer-address filter.

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

Distance in kilometres around Location for the public BA search. Choose 0, 10, 15, 25, 50, 100, or 200; the default is 25. Use 0 for the exact location only. This is not a geographic-coordinate field.

## `jobReferenceNumbers` (type: `array`):

Known public Bundesagentur reference numbers to enrich directly, for example '10000-1000000000-S'. When supplied, they take precedence over the search filters. Enter only reference numbers returned by the BA listing API. This is not for URLs, customer identifiers, or applicant IDs.

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

Maximum number of validated jobs written and billed by this run. Choose an integer from 1 through 500; default is 20. Each persisted job costs $0.00225 plus Apify platform usage, so this is also the event-cost cap. This is not a per-page limit.

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

Fetch the public BA detail record for each listing to include description, contract, work-time and remote-work fields. It defaults to true; set false for a faster listing-only feed. A temporary detail failure preserves the valid listing and is reported as a partial outcome. This does not request authenticated or private data.

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

Controls the maximum returned job-description length for agent workflows. Choose concise for 800 characters or detailed for 5000; concise is the default. All other normalized fields are identical in both modes. This is not a CSV, JSON, or export-format setting.

## Actor input object example

```json
{
  "searchQuery": "Data Engineer",
  "location": "München",
  "radiusKm": 25,
  "jobReferenceNumbers": [
    "10000-1000000000-S"
  ],
  "maxResults": 20,
  "includeJobDetails": true,
  "responseFormat": "concise"
}
```

# Actor output Schema

## `dataset` (type: `string`):

Default dataset containing one normalized public Bundesagentur vacancy per item.

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

Compact machine-readable collection outcome with record and billing counts.

## `runSummary` (type: `string`):

Detailed public-API, pagination, validation, and billing diagnostics.

# 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": "Softwareentwickler",
    "location": "Berlin",
    "radiusKm": 25,
    "jobReferenceNumbers": [],
    "maxResults": 20,
    "responseFormat": "concise"
};

// Run the Actor and wait for it to finish
const run = await client.actor("khadinakbar/bundesagentur-job-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": "Softwareentwickler",
    "location": "Berlin",
    "radiusKm": 25,
    "jobReferenceNumbers": [],
    "maxResults": 20,
    "responseFormat": "concise",
}

# Run the Actor and wait for it to finish
run = client.actor("khadinakbar/bundesagentur-job-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).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": "Softwareentwickler",
  "location": "Berlin",
  "radiusKm": 25,
  "jobReferenceNumbers": [],
  "maxResults": 20,
  "responseFormat": "concise"
}' |
apify call khadinakbar/bundesagentur-job-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=khadinakbar/bundesagentur-job-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Bundesagentur Job Scraper — German Vacancies",
        "description": "Search Germany's Bundesagentur für Arbeit public Jobsuche feed and return normalized vacancies with employer, location, contract, remote-work and date signals. Use for recruitment research and labor-market analysis; not for applicant data.",
        "version": "1.0",
        "x-build-id": "0e1jzYbR7JG4ELweT"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/khadinakbar~bundesagentur-job-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-khadinakbar-bundesagentur-job-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/khadinakbar~bundesagentur-job-scraper/runs": {
            "post": {
                "operationId": "runs-sync-khadinakbar-bundesagentur-job-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/khadinakbar~bundesagentur-job-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-khadinakbar-bundesagentur-job-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "properties": {
                    "searchQuery": {
                        "title": "Job search query",
                        "type": "string",
                        "description": "Free-text role, skill, or occupation query for Bundesagentur Jobsuche, for example 'Softwareentwickler'. It accepts normal German search text and defaults to 'Softwareentwickler'. Use it with Location for local searches or leave the default for the quality-test search. This is not a listing URL or an applicant query.",
                        "default": "Softwareentwickler"
                    },
                    "location": {
                        "title": "Location",
                        "type": "string",
                        "description": "City, district, postal code, or German region around which to search, for example 'Berlin'. It is optional and defaults to 'Berlin' for a dependable initial search. Radius only applies when this field is supplied. This is not a free-form employer-address filter.",
                        "default": "Berlin"
                    },
                    "radiusKm": {
                        "title": "Search radius in km",
                        "type": "integer",
                        "description": "Distance in kilometres around Location for the public BA search. Choose 0, 10, 15, 25, 50, 100, or 200; the default is 25. Use 0 for the exact location only. This is not a geographic-coordinate field.",
                        "default": 25
                    },
                    "jobReferenceNumbers": {
                        "title": "Job reference numbers",
                        "type": "array",
                        "description": "Known public Bundesagentur reference numbers to enrich directly, for example '10000-1000000000-S'. When supplied, they take precedence over the search filters. Enter only reference numbers returned by the BA listing API. This is not for URLs, customer identifiers, or applicant IDs.",
                        "items": {
                            "type": "string"
                        },
                        "default": []
                    },
                    "maxResults": {
                        "title": "Max results",
                        "minimum": 1,
                        "maximum": 500,
                        "type": "integer",
                        "description": "Maximum number of validated jobs written and billed by this run. Choose an integer from 1 through 500; default is 20. Each persisted job costs $0.00225 plus Apify platform usage, so this is also the event-cost cap. This is not a per-page limit.",
                        "default": 20
                    },
                    "includeJobDetails": {
                        "title": "Fetch full job details",
                        "type": "boolean",
                        "description": "Fetch the public BA detail record for each listing to include description, contract, work-time and remote-work fields. It defaults to true; set false for a faster listing-only feed. A temporary detail failure preserves the valid listing and is reported as a partial outcome. This does not request authenticated or private data.",
                        "default": true
                    },
                    "responseFormat": {
                        "title": "Response format",
                        "enum": [
                            "concise",
                            "detailed"
                        ],
                        "type": "string",
                        "description": "Controls the maximum returned job-description length for agent workflows. Choose concise for 800 characters or detailed for 5000; concise is the default. All other normalized fields are identical in both modes. This is not a CSV, JSON, or export-format setting.",
                        "default": "concise"
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```