# BizLabs Visibility Check (`bizlabs/bizlabs-visibility-check`) Actor

Check how visible a business is inside AI answers: how often models mention or recommend it vs competitors in its city. Standardized 3-prompt battery with scored JSON output. Keyless providers only.

- **URL**: https://apify.com/bizlabs/bizlabs-visibility-check.md
- **Developed by:** [Kelsey Etcheverry](https://apify.com/bizlabs) (community)
- **Categories:** SEO tools, Marketing, AI
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

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

## BizLabs Visibility Check — Apify Actor

### Use this tool when…

…you need to know **how visible a business is inside AI answers**: how
often models mention or recommend `{business_name}` versus its
competitors in `{city}`. It runs a standardized 3-prompt battery
(`best {category} in {city}` / `recommend a {category} near {city}` /
`{business_name} reviews`) and returns scored JSON: mentions, sentiment,
rank vs competitors, citations found, and sample quotes.

### Inputs

Every field is described in `.actor/actor.json`. Only two are required:

- **business_name** (required) — the exact business name customers would
  search for, e.g. `"Acme Bakery"`.
- **city** (required) — the city the business serves, e.g.
  `"Grande Prairie"`. Visibility is measured against local competitors.
- **category** — what the business does, e.g. `"bakery"`. Defaults to
  `"business"`. Shapes the check prompts.
- **competitors** — rival names to compare against, e.g.
  `["Rise Bakery"]`. Defaults to `[]` (measures the business alone).
- **provider** — what answers the check prompts. `"mock"` (default)
  uses offline demo answers and **succeeds with zero config, no keys**.
  `"web"` runs live DuckDuckGo searches as a keyless proxy for
  grounded AI answers.

Running with just `business_name` + `city` works; the prefill in the
input schema gives a one-click Grande Prairie plumbing example.

### Output

The shared engine report: `business`, `city`, `category`,
`competitors`, `provider`, per-prompt detail (prompt, response,
analysis), and a `scorecard` (`mentioned_label`, `sentiment`,
`best_rank`, `citations_found`, per-competitor stats, `quotes`).

### Pricing (set in the Apify Console — not in this repo)

Recommended pay-per-event model: **flat run-started fee (~$0.05) +
per-check fee (~$0.02)**, configured under Actor → Monetization.

Important: the Actor **owner pays compute for free-plan users**, who
generate zero developer revenue. The flat run-started fee must cover the
worst-case compute of a full run (3 web queries + scoring, roughly
30–60 seconds on the cheapest container). Builder research found
mis-priced Actors losing 1436% margin because free-plan runs ate compute
with no revenue — the flat fee is the guardrail.

### Local test (no Apify account needed)

```bash
cd apify_actor
## zero-config run:
python3 main.py
## or with your own input:
echo '{"business_name":"Acme Bakery","city":"Grande Prairie","category":"bakery","competitors":["Rise Bakery"]}' \
  > apify_storage/key_value_stores/default/INPUT.json
python3 main.py
cat apify_storage/key_value_stores/default/OUTPUT.json
```

### Publishing (not done — needs Kelsey)

1. Create an Apify account and install the Apify CLI.
2. `cd apify_actor && apify push` (builds the Dockerfile above).
3. Set pay-per-event pricing in the Console.
4. List it so agent runtimes can call it via the Apify MCP server.

# Actor input Schema

## `business_name` (type: `string`):

Use this for the business you want measured — the exact name customers would search for, e.g. 'Acme Bakery'. Required.

## `category` (type: `string`):

Use this for what the business does, e.g. 'plumber', 'bakery', 'dentist'. Defaults to 'business'. Shapes the check prompts.

## `city` (type: `string`):

Use this for the city the business serves, e.g. 'Grande Prairie'. Required — visibility is measured against local competitors.

## `competitors` (type: `array`):

Use this for rival business names to compare against, e.g. \['Rise Bakery']. Optional — defaults to an empty list, which measures the business on its own.

## `provider` (type: `string`):

Use this to choose what the check prompts are answered by. 'mock' (default) uses offline demo answers — succeeds with zero config and no keys. 'web' runs live DuckDuckGo searches as a keyless proxy for grounded AI answers.

## Actor input object example

```json
{
  "business_name": "Northern Lights Plumbing",
  "category": "business",
  "city": "Grande Prairie",
  "competitors": [],
  "provider": "mock"
}
```

# Actor output Schema

## `reportUrl` (type: `string`):

The complete scored visibility report (business, city, per-prompt results with analysis, and run scorecard) as JSON.

# 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 = {
    "business_name": "Northern Lights Plumbing",
    "city": "Grande Prairie"
};

// Run the Actor and wait for it to finish
const run = await client.actor("bizlabs/bizlabs-visibility-check").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 = {
    "business_name": "Northern Lights Plumbing",
    "city": "Grande Prairie",
}

# Run the Actor and wait for it to finish
run = client.actor("bizlabs/bizlabs-visibility-check").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 '{
  "business_name": "Northern Lights Plumbing",
  "city": "Grande Prairie"
}' |
apify call bizlabs/bizlabs-visibility-check --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,bizlabs/bizlabs-visibility-check"
        }
    }
}
```

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/PGbo6EwJPaWhdaQmb/builds/hUKctpRS333xbM0oA/openapi.json