Kununu Company Data Fetcher

Fetch public Kununu company data for a German city. The Actor accepts a city such as Berlin, resolves Kununu's opaque location token, follows source-provided pagination, visits each discovered company profile, and can enrich it from the employee review, salary, jobs, and culture sections.

The input city controls company discovery. Section summaries and detail records are company-wide Kununu data and are not restricted to that city. Use the Actor only for workloads for which you have authorization and in accordance with applicable law and platform terms. Kununu is a trademark of its respective owner; this project is not affiliated with Kununu.

Why the Actor uses both HTTP and Playwright

Kununu's search, profile, and enrichment data is available in rendered HTML, so the main crawl uses Crawlee's BeautifulSoupCrawler for speed and lower cost. Playwright resolves a free-text city and completes Kununu's browser challenge. Challenged browser identities are retired explicitly. After a successful bootstrap, both crawlers share the same Crawlee session, cookies, Chromium user agent and TLS fingerprint, sticky proxy session, and mandatory Apify Proxy configuration. Playwright remains available as a bounded fallback.

Input

Field	Type	Default	Description
city	string	Berlin	German city to resolve.
locationToken	string	—	Optional known Kununu city-UUID token; skips city resolution.
maxCompanies	integer	2	Maximum unique company profiles, up to 500.
maxPages	integer	20	Maximum search pages.
includeExtendedProfile	boolean	true	Include profile sections, factors, and benefits.
enrichmentMode	enum	summary	none, summary, detailed, or full.
sections	string array	all four	Any of reviews, salary, jobs, and culture.
maxReviewsPerCompany	integer	10	Review rows in Detailed or Full mode, up to 100.
maxSalaryRolesPerCompany	integer	20	Salary-role rows, up to 300. Full mode opens each accepted role page.
maxJobsPerCompany	integer	30	Job rows, up to 300.
maxJobDetailsPerCompany	integer	0	Individual job pages opened in Full mode, up to 50.
enableBrowserFallback	boolean	true	Retry exhausted HTTP requests in Playwright.
maxConcurrency	integer	3	Maximum HTTP request concurrency.
proxyConfiguration	object	Residential, Germany	Required Apify Proxy settings.
debug	boolean	false	Enable verbose diagnostics. Raw HTML is never stored.

Example:

{
  "city": "Berlin",
  "maxCompanies": 25,
  "maxPages": 20,
  "includeExtendedProfile": true,
  "enrichmentMode": "detailed",
  "sections": ["reviews", "salary", "jobs", "culture"],
  "maxReviewsPerCompany": 10,
  "maxSalaryRolesPerCompany": 20,
  "maxJobsPerCompany": 30,
  "maxJobDetailsPerCompany": 0,
  "enableBrowserFallback": true,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"],
    "apifyProxyCountry": "DE"
  }
}

Live cloud verification showed that Kununu rejects Apify's automatic proxy pool with HTTP 403 responses. The Actor therefore defaults to the RESIDENTIAL group in Germany. Your Apify account must have access to this group, which has usage-based proxy costs. You can supply another available group through the standard proxyConfiguration editor; explicitly supplied settings are preserved. The Actor rejects useApifyProxy: false by design.

The Actor defaults to 1 GB of memory and 2 companies. This Store-safe prefill is sufficient for a representative result while keeping the memory-based start event plus result events within the current platform run-cost guard. Increase maxCompanies for production collection and set a matching maximum run charge in Apify Console or through the API. Increase memory only for deliberately larger browser-heavy runs and review the resulting start charge first.

Enrichment modes

• none: fetch the base company profile only.
• summary: fetch one page from each selected section and add company-wide reviewsSummary, salarySummary, jobsSummary, and cultureSummary objects to the company row. This is the recommended cost-controlled default.
• detailed: also follow exact section pagination URLs until the configured per-company item limits and write review, salary-role, and job rows to their own datasets.
• full: additionally open every accepted salary-role page and up to maxJobDetailsPerCompany accepted job pages. Each row reports detailStatus as succeeded, failed, or notRequested.

Dataset output

The Actor defines four run-scoped datasets:

Alias	Contents
default	One finalized row per successfully fetched company profile, including enrichment summaries and per-section status.
reviews	Public employee review records in Detailed and Full modes.
salary_roles	Salary-role rows; Full mode adds range, comparison, monthly, and experience-band fields from role pages.
jobs	Job rows; Full mode can add plain-text and source-HTML descriptions, responsibilities, requirements, benefits, compensation highlights, apply URLs, dates, and structured salary information from job pages.

Core company fields include:

• search context: cityInput, resolvedCity, locationToken, searchPage, and searchRank;
• identity: companyName, companySlug, companyUrl, logo and cover URLs;
• profile status: verifiedProfile, activeProfile, and topCompany;
• company data: locations, country, industry, company website, and social links;
• reputation data: Kununu score, review count, recommendation rate, score trend, followers, factor ratings, benefit names, and benefit percentages where exposed;
• optional extended text: company information, recruiting, locations, employee, career, salary, culture, FAQ, and award summaries;
• enrichment data: company-wide section summaries and enrichment.sections status, page, item, cap, and deep-detail counters;
• provenance: sourceSearchUrl, scrapedAt, schema version, and missingFields.

Fields absent on a source profile are omitted and listed in missingFields where they are part of the core profile. The dataset schema provides Overview and Extended data views in Apify Console.

Pagination and completeness

The crawler does not manufacture pagination URLs. It follows the exact next-page href exposed by Kununu for search results, reviews, salary roles, and jobs. It deduplicates canonical company and record URLs and stops each collection at the first applicable condition:

• the source no longer exposes a next link;
• maxCompanies is reached;
• maxPages is reached; or
• a page fails after both HTTP and browser retry policies; or
• the applicable per-company record limit is reached.

Kununu can report more matching employers than it exposes through its search result window. When the final accessible range is lower than the reported total, RUN_SUMMARY.isResultSetCapped is true. Limits and failures also produce explicit partial-result reasons; already written valid company items are retained.

The default key-value store record RUN_SUMMARY contains search/profile counts, the resolved city and token, per-section company/page/item/failure counters, cap flags, browser-fallback diagnostics, timestamps, a bounded final-failure URL list, and isPartial. Completed company rows are emitted progressively. On Apify, the Actor also reserves 45 seconds before ACTOR_TIMEOUT_AT to stop accepting work, flush remaining partial rows, and finish cleanly with TIME_BUDGET_REACHED telemetry instead of being killed.

Local development

Requirements:

• Python 3.12 or newer;
• Docker for the production-equivalent image;
• Apify CLI 1.9 or newer;
• an Apify account/token with access to Apify Proxy for a real target smoke test.

Create a virtual environment and run focused checks:

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
.venv/bin/ruff check .
.venv/bin/pytest -q
apify validate-schema
docker build --platform linux/amd64 -t kununu-company-data-fetcher .

Run through the Apify CLI with an inline input:

$apify run --purge --input '{"city":"Berlin","maxCompanies":3,"locationToken":"city-2fbd1016-893c-4ef0-bea2-7e709129d312","enrichmentMode":"summary","proxyConfiguration":{"useApifyProxy":true,"apifyProxyGroups":["RESIDENTIAL"],"apifyProxyCountry":"DE"}}'

The known token in this diagnostic skips city resolution; remove it to test the full resolver. A genuine Apify Proxy run is best verified in Apify Cloud because local proxy access depends on account credentials and plan settings.

Docker

The image uses Apify's Python Playwright base with the browser revision matched to playwright==1.61.0. The Apify base is a Linux/AMD64 image, matching Apify Cloud; ARM-based development Macs should therefore keep the explicit --platform linux/amd64 build flag shown above. The image installs runtime dependencies, compiles the package during build, and starts the Actor with python3 -m kununu_actor.

GitHub CI/CD

The CI workflow lints, compiles, tests, validates all Apify schemas, and builds the Docker image. A successful push to main deploys the beta build tag. Production is separate: the Release latest Actor build workflow is manually dispatched and targets the protected apify-production environment.

Configure these GitHub Actions secrets:

• APIFY_TOKEN: Apify API token allowed to update the Actor;
• APIFY_ACTOR_ID: existing Actor ID or username/actor-name.

Create the apify-beta and apify-production GitHub environments. Add required reviewers to apify-production before the first release.

Publication checklist

Before making the Actor public in Apify Store:

1. Run CI and build the Docker image successfully.
2. Deploy beta and run a small proxy-backed Berlin smoke test.
3. Confirm the default company dataset, all selected summaries, aliased detail datasets for Detailed/Full mode, pagination, and RUN_SUMMARY in Apify Console.
4. Test a city without a supplied token to exercise the resolver and test one invalid city for a clear failure.
5. Review proxy cost, memory, timeout, privacy, legal, pricing, support, and Store metadata settings.
6. Trigger the protected latest workflow and verify the live build and sample run before publishing.

Selector drift remains possible on any third-party site. Sparse results are surfaced through missingFields; structural failures are retried and then reported instead of being silently treated as complete.