# Google Reviews | Low-Star Business Finder (`danthedataman/google-business-low-star-ledger`) Actor

Find businesses with recent low-star Google reviews. Export published contacts, review counts and scan coverage without reviewer profiles or review text.

- **URL**: https://apify.com/danthedataman/google-business-low-star-ledger.md
- **Developed by:** [Eli J](https://apify.com/danthedataman) (community)
- **Categories:** Lead generation, Marketing
- **Stats:** 2 total users, 1 monthly users, 94.4% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.85 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

### What you can export

Use this **Google low-star review business finder** to identify businesses with recent negative-review activity. Supply a business search, location, time window and star ceiling to export published business contacts, matching review counts and review-window coverage.

Each result is a business summary. Reviewer names, profiles, avatars and review text are excluded. Counts are lower bounds when `scanComplete` is false.

### Try the shipped prefill

Use the input form's example values for a first run. Prefills are examples, not API defaults; check the billing and limits before starting.

```json
{
  "searches": [
    {
      "query": "dentist",
      "location": "Austin, TX"
    }
  ],
  "maxBusinessesPerSearch": 3,
  "windowDays": 180,
  "maxStars": 2
}
```

### Input

| Field | Type | What it does |
| --- | --- | --- |
| `searches` | array | Objects with `query` (category or keywords) and `location` text; form prefill is dentist in Austin, TX. |
| `maxBusinessesPerSearch` | integer | Maximum businesses scanned per search before filtering; form prefill 3. Zero, omitted or null means no work. |
| `windowDays` | integer | Positive window in days before run start; form prefill 180. Omitted or null means no work. |
| `maxStars` | integer | Count stars from 1 through this value, between 1 and 5; form prefill 2 selects 1–2 stars. Omitted or null means no work. |
| `minimumLowStarCount` | integer | Minimum observed count for output, nonnegative; omitted or null uses 1. Zero includes businesses with no observed low-star reviews. |

Omitting `searches` (including `{}`) or sending `[]` is refused before any run or charge. With other inputs valid, null `searches` succeeds with guidance and no rows; Actor Start still applies. Input rejected by the Actor produces guidance and an ERRORS record, with no source request or result row.

### Output

One business row per search context; duplicates within a search are removed by place ID. The same business can appear under separate searches.

Illustrative row:

```json
{
  "placeId": "ChIJexample",
  "cid": "1110",
  "name": "Example Business",
  "category": "Dentist",
  "address": "Example address",
  "website": "https://example.com",
  "phone": "(512) 123-4567",
  "mapsUrl": "https://www.google.com/maps/place/?q=place_id:ChIJexample&hl=en",
  "overallRating": 4.2,
  "totalReviewCount": 123,
  "lowStarCountInWindow": 2,
  "newestLowStarReviewAt": "2026-10-04T10:13:20Z",
  "oldestReviewReadAt": "2026-09-01T10:13:20Z",
  "scanComplete": true,
  "searchContext": {"query": "dentist", "location": "Austin, TX"},
  "sourceUrl": "https://www.google.com/maps/place/?q=place_id:ChIJexample&hl=en",
  "scrapedAt": "2026-10-05T10:13:20Z"
}
```

| Output field | Meaning |
| --- | --- |
| `placeId`, `cid` | Google's place ID and decimal CID, stored as strings. |
| `name`, `category`, `address` | Business name, primary published category and formatted address. Category can be null; service-area businesses without a published address have `address: null`. |
| `website`, `phone` | Website and phone as published in the business listing; null when absent. |
| `mapsUrl`, `sourceUrl` | Public Google Maps link to this business. |
| `overallRating` | Overall business rating on the 1–5 star scale, or null when absent. |
| `totalReviewCount` | Overall published review count, in reviews; independent of the selected window. |
| `lowStarCountInWindow` | Distinct reviews rated at most `maxStars` within the inclusive window, in reviews. A lower bound when the scan is incomplete. |
| `newestLowStarReviewAt` | Newest matching review timestamp in UTC ISO 8601, or null when none observed. |
| `oldestReviewReadAt` | Oldest review timestamp read, including reviews outside the window, in UTC ISO 8601; null if no dated review was read. |
| `scanComplete` | True only when newest-first paging reaches a review older than the window or the source explicitly ends paging. |
| `searchContext` | Query and location text supplied for this search. |
| `scrapedAt` | UTC ISO 8601 timestamp when the row was assembled. |

### Coverage and billing

Uses anonymous Google Search-side HTTP results and newest-first review paging. No signed-in Maps reviews route is used. Searches use English interface labels and the US search-region setting. Location text guides Google's ranking; results are not an exhaustive or strict geographic census. The maximum limits businesses scanned, so the minimum-count filter can yield fewer rows.

Edited reviews are counted at the timestamp Google exposes, which may be their edit date. Source changes, challenges, invalid ordering, broken continuation, a terminal count below the published total while still inside the window, and the 100-page review limit per business can interrupt scans. Incomplete rows retain observed counts and `scanComplete: false`; review failures and skipped business summaries are recorded in ERRORS, never in the dataset. Review bodies are discarded after projection and never logged or stored.

Pay per event: one dataset item per delivered business row, plus an Actor Start event when configured. The Actor stops fetching and delivering when the customer's charge limit binds. No-match runs succeed with guidance; runs where every attempted search fails and no row is delivered fail with a safe message. Pricing is shown on the Actor's pricing page.

# Changelog

This Actor's version history is a separate document: https://apify.com/danthedataman/google-business-low-star-ledger/changelog.md

# Actor input Schema

## `searches` (type: `array`):

Objects with query (category or keywords) and location text. Results follow Google's search ranking, not a census. Omitted or \[]: Apify refuses the start, with no run or charge. With other inputs valid, null succeeds with guidance and no rows; Actor Start still applies.

## `maxBusinessesPerSearch` (type: `integer`):

Maximum businesses to scan per search, before the minimum-count filter. Zero means no work; omitted or null means no work.

## `windowDays` (type: `integer`):

Positive number of days before run start, such as 30, 90 or 180. Required to fetch; omitted or null means no work.

## `maxStars` (type: `integer`):

Count reviews rated from 1 through this value (1–5). Form prefill 2 selects 1–2 stars. Required to fetch; omitted or null means no work.

## `minimumLowStarCount` (type: `integer`):

Minimum observed low-star count for output. Omitted or null uses 1. Zero includes businesses with no observed low-star reviews.

## Actor input object example

```json
{
  "searches": [
    {
      "query": "dentist",
      "location": "Austin, TX"
    }
  ],
  "maxBusinessesPerSearch": 3,
  "windowDays": 180,
  "maxStars": 2
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `errors` (type: `string`):

Handled source failures, when present; never result rows.

# 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 = {
    "searches": [
        {
            "query": "dentist",
            "location": "Austin, TX"
        }
    ],
    "maxBusinessesPerSearch": 3,
    "windowDays": 180,
    "maxStars": 2
};

// Run the Actor and wait for it to finish
const run = await client.actor("danthedataman/google-business-low-star-ledger").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 = {
    "searches": [{
            "query": "dentist",
            "location": "Austin, TX",
        }],
    "maxBusinessesPerSearch": 3,
    "windowDays": 180,
    "maxStars": 2,
}

# Run the Actor and wait for it to finish
run = client.actor("danthedataman/google-business-low-star-ledger").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 '{
  "searches": [
    {
      "query": "dentist",
      "location": "Austin, TX"
    }
  ],
  "maxBusinessesPerSearch": 3,
  "windowDays": 180,
  "maxStars": 2
}' |
apify call danthedataman/google-business-low-star-ledger --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,danthedataman/google-business-low-star-ledger"
        }
    }
}
```

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/4VJv3VU3fKpQqyefe/builds/xjiiaZ5sHBSwceDbA/openapi.json