# Business Locations Analyzer — Bulk CSV API (`apivault_labs/business-locations-analyzer`) Actor

Filter permitted business-location data by category, country and contact fields. Usage restrictions apply. Bulk export: JSON, CSV, Excel and API. PPE: from $7/1K locations; start fee, usage extra.

- **URL**: https://apify.com/apivault_labs/business-locations-analyzer.md
- **Developed by:** [Apivault Labs](https://apify.com/apivault_labs) (community)
- **Categories:** Lead generation, Business, Marketing
- **Stats:** 2 total users, 1 monthly users, 90.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $7.00 / 1,000 business locations

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
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

## Business Locations Analyzer — 28M+ Records

![Business Locations Analyzer — market research, location coverage and business insights](https://api.apify.com/v2/key-value-stores/u4YZtIlXXYEybGzl4/records/business-locations-analyzer-hero-v1.png)

Find local business prospects for **web design, SEO and digital marketing**,
then prioritize your own research by location, reviews and digital-presence
signals. Business Locations Analyzer searches a historical **28M+ location
snapshot across 14 countries** and a separate collection of official company
branches. Use it for internal prospect research, market analysis and your CRM.

### Find leads for your agency

| Your service | Find with the analyzer | Your next step |
|---|---|---|
| Website creation | Businesses with no recorded website and an available phone | Check whether a website exists today and assess a suitable service offer |
| Website redesign or SEO | Businesses with a recorded website, filtered by industry and area | Audit the actual site before diagnosing design, speed or SEO problems |
| Local marketing | Location segments with review activity and digital-presence signals | Research the business and its local context |
| Territory planning | Filtered counts and phone/website coverage by country | Compare segments before exporting a small sample |

**Try a 5-record sample:** choose a country and business collection, set
`hasPhone: true`, and select `noWebsite: true` for website-creation candidates
or `hasWebsite: true` for site-audit candidates. Open **Business locations** to
inspect the results. [Copy the tested JSON examples](#lead-research-for-web-design-seo-and-local-marketing-agencies).
Use `countOnly: true` to preview a segment without paid result rows.

`websiteOpportunityScore` helps prioritize research; `digitalPresenceScore`
describes listing completeness. **The analyzer does not audit website quality
or establish that a business needs your services.** Missing sites and contacts
must be checked against current information. Keep prospects in your own CRM;
resale, redistribution and unsolicited bulk messaging are prohibited safeguards.
Data, scores and applicable outreach requirements need independent verification.

### More ways to use Business Locations Analyzer

| Who it helps | Research goal | Supported filters and outputs |
|---|---|---|
| B2B suppliers and industry SaaS teams | Find restaurants for POS research, hotels for equipment services, salons for booking tools or repair shops for business software | `businessCollection`, country/city, phone/website filters and small CRM exports |
| Retailers and franchise teams | Research an area before opening a location | Category plus radius, `countOnly`, coordinates, ratings and review counts |
| Local operators and consultants | Compare businesses in the same market | Category/city segments, rating, review count, hours and digital-presence signals |
| Partnership and channel teams | Research prospective partners, distributors and local service networks | Category, geography, `minRating`, `minReviews`, phone and website |
| Brand and chain researchers | Investigate a brand's geographic presence | `companies`, `nameMatch`, snapshot or official-website locations, source verification and observation dates |
| CRM and sales operations teams | Check or supplement their own business records | Name/geography searches, normalized addresses, phone, website and `locationId` |

#### B2B supplier and SaaS prospect research

For example, select `restaurants` to research possible customers for restaurant
equipment or business software. Select `hotels`, `beauty_salons` or `auto_repair`
for other verticals. This finds businesses in an industry; it does not reveal
their installed software, purchasing budget or intention to buy.

```json
{
  "dataSource": "snapshot",
  "countries": ["it"],
  "businessCollection": "restaurants",
  "hasPhone": true,
  "hasWebsite": true,
  "minReviews": 20,
  "maxItems": 5,
  "sortBy": "reviews",
  "intendedUse": "internal_business_research"
}
```

#### Location and franchise expansion research

Count a category around a proposed location before requesting individual
records. This example counts cafes within 5 km of central Rome:

```json
{
  "dataSource": "snapshot",
  "countries": ["it"],
  "businessCollection": "coffee_shops",
  "nearLatitude": 41.9028,
  "nearLongitude": 12.4964,
  "radiusKm": 5,
  "countOnly": true,
  "intendedUse": "site_planning"
}
```

Open **Count preview** / `COUNT_SUMMARY`. These are matching observations in
the covered snapshot, not a complete census or proof of demand. Foot traffic,
rent, demographics, spending and predicted revenue are not provided. A count
can inform research; it cannot establish that an area is underserved.

#### Competitor, partner and chain research

For local comparisons, select the same category and geography, then inspect
ratings, reviews and listing signals. For partnership research, combine
`minRating` / `minReviews` with phone or website filters and verify candidates
independently. These rating filters work with the snapshot source only.

For chain research, use `companies` and `nameMatch` or choose
`dataSource: official_websites` with `officialCountries`. Check source
verification and dates in the **Official website locations** view. Name matches
do not establish legal ownership or franchise status, and coverage may omit
branches. Neither mode provides live competitor monitoring, Google ranking,
review sentiment or a measured market share.

#### Research for your own CRM

Search by name and geography and compare returned business details with your
existing records. Use `locationId` as a key in your own deduplication workflow;
it is derived from location facts and can change when those facts change.
Bulk CSV upload/matching and native HubSpot/Salesforce synchronization are not
implemented. Standard Apify exports can support your own import workflow.

All these scenarios are for internal research and your own organization. They
do not authorize resale, redistribution, customer-facing data products or
unsolicited bulk messages. Verify historical observations and applicable
outreach requirements before acting on any candidate.

### Start with a market analysis

For aggregate analysis without exporting individual records, use the snapshot
source and set `analyticsOnly: true`:

```json
{
  "dataSource": "snapshot",
  "countries": ["it"],
  "businessCollection": "pharmacies",
  "analyticsOnly": true,
  "intendedUse": "market_analysis"
}
```

Open **Aggregate market analytics** in the run Output, or the `MARKET_ANALYTICS` JSON
record. It contains filtered location counts, phone/website coverage, average
ratings and review counts, and observation dates by country. No individual
Dataset rows are created in this mode. `countOnly` provides counts without
record exports for either source. Official-site mode supports location research
and counts; these market aggregates are available only for the snapshot.

You can also export selected location records for internal research and your
own CRM. This capability remains available and is subject to the usage
safeguards below; the product is not offered for data resale or redistribution.

### Quick start: choose the right location source

Choose the source, country, collection and result limit, then run. No additional
acknowledgement checkbox is required. The legacy `acceptTerms` input is ignored,
including saved inputs with `false`; usage restrictions remain described below.

> **Usage boundary:** internal research and your own CRM only. Do not resell or
> redistribute exported records, put them into a customer-facing data product,
> or use them for spam, harassment or unlawful profiling. See
> [Responsible use](#responsible-use) before exporting. Running the Actor does
> not establish consent from the people or businesses appearing in the output.

Use `dataSource=snapshot` for the existing 14-country business-listing snapshot.
Use `dataSource=official_websites` for the separate collection of company branches
from official websites. The default remains `snapshot` for existing integrations.

The input form starts with a limit of **5 results**. Existing API inputs and saved
Tasks retain their explicit limits. Preview coverage with `countOnly` before
requesting a larger export.

Small official-website export:

```json
{
  "dataSource": "official_websites",
  "officialCountries": ["US"],
  "hasPhone": true,
  "maxItems": 5,
  "intendedUse": "internal_business_research"
}
```

Choose the **Official website locations** Dataset view to see the official page,
verification status and age of the record together. `country` is a recognized
ISO country code (plus XK); `countryRaw` preserves the original value. Unknown
values are returned with `country=null`, never guessed from an address. Use
`officialCountries=["UNKNOWN"]` to inspect that group, or `listCountries=true`
to obtain normalized counts without exporting rows. Names such as United States
and aliases such as USA are accepted. Raw-value filters remain supported.

Official data supports company, city, postal-code, region, phone, website, radius,
freshness and export/count filters. Ratings, review counts, ownership flags,
collections and snapshot analytics are unavailable in this mode. Use the snapshot
source for those features. Source verification does not guarantee that a phone
works today or that a location is still open.

Delivered rows use the existing tiered price: $0.015 each on FREE and $0.007 on
BRONZE–DIAMOND, plus the Actor start event and platform usage. Five delivered rows
therefore cost $0.075 or $0.035 in row events, respectively. Check the Pricing tab
and set a run spending limit; owner QA runs do not measure customer billing.

Query the maintained business-location snapshot for research instead of waiting
for a new live scrape. Analyze a segment by country, city, category or radius,
or investigate physical branches by company name. Optional internal-use exports
include normalized addresses, phones, websites, ratings, opening hours and
coordinates through Apify's standard Dataset formats and API.

The delivered-location price pays for the work and infrastructure required to
collect, clean, normalize coordinates, deduplicate, structure, maintain, query
and deliver the snapshot and its calculated analytics. The Creator does not
claim ownership of underlying public business facts merely because they were
collected or structured.

> **Data-quality notice:** this is a historical snapshot, not a verified live
> registry. Records and calculated scores may be inaccurate, incomplete,
> duplicated or outdated. Validate important details independently before use.

Search **28.2M+ business-location records across 14 countries**. Current coverage:

| Country | Locations |
|---|---:|
| Germany | 5.40M+ |
| Italy | 4.45M+ |
| United Kingdom | 4.31M+ |
| Turkey | 3.41M+ |
| Spain | 3.21M+ |
| Netherlands | 1.27M+ |
| Ukraine | 1.04M+ |
| France | 1.03M+ |
| Poland | 945K+ |
| Belgium | 822K+ |
| Portugal | 819K+ |
| Austria | 714K+ |
| Sweden | 594K+ |
| Romania | 253K+ |

Counts were verified on 2026-09-13. Run `listCountries` for machine-readable
coverage metadata.

The 2026-09-13 launch audit also verified all 40 ready-made collections against
live private runs. Across all 196 data sources, coordinates are present on 100%
of rows and the source snapshot dates range from 2026-08-19 through 2026-08-26.
Source-specific identifiers, photos and email addresses are not returned.

### Common searches

- Find every available location of a company or retail brand.
- Build a list of restaurants, banks, pharmacies, hotels or other businesses.
- Export local prospects that have a phone or website.
- Find businesses without websites for agency outreach.
- Create map-ready datasets with addresses and coordinates.
- Find businesses within a radius of any map coordinate.
- Count a segment before exporting any paid rows.

### Lead research for web-design, SEO and local marketing agencies

Use the analyzer to shortlist businesses for your own CRM and investigate
potential service needs. A record is a research candidate, not a verified sales
lead or evidence that the business wants to buy. The use safeguards apply:
no resale, redistribution, spam or unsolicited bulk messaging. Public contact
details are not marketing consent; verify details and assess outreach rules.

#### Find active-looking businesses with no recorded website

This snapshot example finds Italian restaurants with a phone number, at least
20 reviews and no website recorded. Closed locations are excluded by default.
Missing a website in the snapshot does not prove the business has no site today.

```json
{
  "dataSource": "snapshot",
  "countries": ["it"],
  "businessCollection": "restaurants",
  "noWebsite": true,
  "hasPhone": true,
  "minReviews": 20,
  "sortBy": "reviews",
  "maxItems": 5,
  "intendedUse": "internal_business_research"
}
```

Review `websiteOpportunityScore`, `digitalPresenceScore`, `reviewCount`,
`contactabilityScore`, `dataConfidenceScore` and `dataAsOf` together. These
estimates help prioritize manual research, not predict purchases. You can sort
exported records by a score in your own analysis; the Actor's `sortBy` supports
reviews, distance and name, not opportunity-score ordering or score thresholds.

#### Find businesses with websites for a separate site audit

```json
{
  "dataSource": "snapshot",
  "countries": ["it"],
  "businessCollection": "restaurants",
  "hasWebsite": true,
  "hasPhone": true,
  "minReviews": 20,
  "sortBy": "reviews",
  "maxItems": 5,
  "intendedUse": "internal_business_research"
}
```

Use the returned `website` values as candidates for a separate website audit.
This analyzer does **not** visit websites or test design, loading speed, mobile
usability, SEO, security or broken pages. A low `digitalPresenceScore` means
missing listing signals; it is not a bad-website diagnosis.
`websiteOpportunityScore` combines whether a website is recorded with rating
and review signals, not a technical website-quality assessment. Audit the site
and confirm findings before claiming that a business needs a redesign or SEO.

For territory planning, add `city` or radius filters. Preview the same segment
with `countOnly: true` before exporting a larger sample. Ratings/review filters
in these examples apply to the snapshot source, not official-site mode.

### Why use a business-location analyzer?

This Actor queries an existing location snapshot. It is designed for bulk POI
research, branch discovery, territory planning and local lead generation where
you need predictable coverage and export volume.

| Business Locations Analyzer | Live map scraper |
|---|---|
| Search 28.2M+ already collected records | Collects records during every run |
| Preview a segment count before exporting | Final result volume is often unknown |
| Export up to 10,000 normalized rows for a narrowly filtered segment | Search-page limits can restrict each query |
| Repeatable global sorting within each run | Results may change while pages are collected |
| Snapshot dates are disclosed | Usually fresher at the moment of collection |

Choose this analyzer for repeatable market research and filtered exports. Choose a live scraper
when the newest possible listing changes, review text or website contact
enrichment matter more than immediate scale.

### Start in three steps

1. Run `countOnly: true` with a country and collection or custom filters. Open
   **Count preview** to see the volume without creating paid Dataset rows.
2. Disable `countOnly` and request a small sample such as `maxItems: 100`.
   Check field availability and relevance before ordering a large export.
3. Refine country, category, company and geographic filters before increasing
   `maxItems`, which is capped at 10,000 records per run.

For the lowest-cost validation, request five rows first. At the paid-plan rate
the delivered-row charge is $0.035, plus the start event and platform usage.
Inspect that sample before purchasing a larger result window.

### Ready-made business collections

Choose `businessCollection` instead of learning category names. Each collection
contains tested category aliases, so `coffee_shops` covers both coffee shops and
cafes, while `banks` includes banks, savings banks and credit unions but removes
food-bank and blood-bank matches.

The catalog contains **40 collections**, including banks, coffee shops,
pharmacies, restaurants, hotels, supermarkets, dentists, doctors, medical
clinics, veterinarians, opticians, real estate agencies, car dealers, auto
repair shops, gas stations, car washes, gyms, beauty salons, schools, day care,
bakeries, bars and pubs, lawyers, accountants, insurance agencies, travel and
marketing agencies, photographers, electricians, plumbers, cleaning and moving
services, construction companies, roofers, landscapers, florists and pet stores.

Collection aliases use exact discovery categories to avoid substring mistakes
such as bars matching barber shops. Custom `categories` remain flexible partial
matches and can be combined with any collection.

```json
{
  "countries": ["fr"],
  "businessCollection": "coffee_shops",
  "countOnly": true,
  "intendedUse": "market_analysis"
}
```

Open `COUNT_SUMMARY` to see the available volume, then rerun with
`countOnly: false` and `maxItems` to export a filtered segment.

### Find company branches

Use a brand name together with a category to prevent unrelated street, transit
stop or landmark matches:

```json
{
  "countries": ["at"],
  "companies": ["McDonald's"],
  "nameMatch": "starts_with",
  "categories": ["restaurant"],
  "excludeCategories": ["bus stop"],
  "maxItems": 100,
  "intendedUse": "internal_business_research"
}
```

`contains` finds the widest set of matches, `starts_with` is the recommended
default for well-known brands, and `exact` returns only identical business names.

### Discover businesses

Company names are optional. Search an entire category in one or more cities:

```json
{
  "countries": ["at"],
  "categories": ["pharmacy"],
  "cities": ["Linz"],
  "hasPhone": true,
  "maxItems": 250,
  "intendedUse": "internal_business_research"
}
```

### Search around a point

Use coordinates and a radius together. The result includes `distanceKm`, so it
can be ranked or filtered further after export:

```json
{
  "countries": ["at"],
  "categories": ["restaurant"],
  "nearLatitude": 48.2082,
  "nearLongitude": 16.3738,
  "radiusKm": 2,
  "sortBy": "distance",
  "hasOpeningHours": true,
  "maxItems": 100,
  "intendedUse": "site_planning"
}
```

You can also filter by `postalCodes`, `states` and minimum rating or review
count. Permanently closed locations are excluded unless
`includeClosed` is enabled.

![Analyst searching a map and structured business-location dataset](https://api.apify.com/v2/key-value-stores/u4YZtIlXXYEybGzl4/records/business-location-search-workflow-v1.png)

### Output

Each Dataset row represents one physical location and can include:

- name, address, city, postal code, state and country;
- phone and website when available in the selected country;
- rating, review count and business categories;
- latitude, longitude and a provider-neutral `locationId` generated by this Actor;
- opening hours, claimed/closed status, distance and the observation date;
- freshness, confidence, digital-presence, contactability, review-strength,
  website-opportunity and market-competition scores;
- the ready-made collection id when a collection was selected.

Field availability varies by country. A missing phone or website is returned as
`null`; it is not inferred or guessed. Scores are indicators, not verified facts.

Example Dataset row:

```json
{
  "locationId": "loc_94be7fd8c23658efea180c1a",
  "name": "Example Pharmacy",
  "address": "12 Market Street",
  "city": "Manchester",
  "postalCode": "M1 1AA",
  "country": "GB",
  "phone": "+44 161 000 0000",
  "website": "https://example.com",
  "rating": 4.6,
  "reviewCount": 128,
  "categories": ["Pharmacy"],
  "latitude": 53.4808,
  "longitude": -2.2426,
  "isClosed": false,
  "collection": "pharmacies",
  "dataAsOf": "2026-08-24T00:00:00+00:00",
  "freshnessDays": 20,
  "methodologyVersion": "2026-09-13.1",
  "digitalPresenceScore": 90,
  "dataConfidenceScore": 94
}
```

The current snapshot was collected between **August 19 and August 26, 2026**.
Coordinates are present for all 28.27M records. Email, source-specific IDs,
photos, booking links and raw source attributes are deliberately excluded.
Claimed-profile filtering is hidden because the current sources do not provide
positive claimed flags.

### Data provenance and storage

The underlying records were collected from business-listing pages that were
publicly accessible without signing in. The collection process did not use a
paid official listings API.

This Actor does not visit those pages during a run. It queries a pre-collected
snapshot held in managed storage and returns the matching rows. Results are
therefore repeatable, but they are not live and a business may have changed
since the recorded `dataAsOf` date.

Public accessibility does not by itself grant unlimited reuse rights. This
section describes the collection and delivery method; it is not a warranty
that every possible downstream use is lawful.

The Actor uses its own one-way `locationId`, calculated from normalized location
facts. It never returns the source identifier used during collection. A
creator-managed suppression list is applied before Dataset rows are written.

### Analytics methodology

Set `analyticsOnly: true` to receive non-row-level market analytics in
`MARKET_ANALYTICS`. The result includes filtered location counts, phone and
website coverage, average rating and review count, and the oldest/newest
observation dates by country. No individual Dataset rows are created.

Row-level scores use methodology version `2026-09-13.1` and a 0–100 scale:

- `digitalPresenceScore` uses website, phone, hours and claimed signals;
- `websiteOpportunityScore` is higher for locations without a website and with
  stronger review signals;
- `reviewStrengthScore` combines rating and logarithmically scaled review count;
- `contactabilityScore` uses the presence of phone and website;
- `marketCompetitionPercentile` is a heuristic review-volume benchmark, not an
  observed percentile of every business in the market;
- `dataConfidenceScore` combines field completeness and snapshot age.

These scores are deterministic analytical estimates. They are not credit,
consumer, employment, health or legal assessments and must not be used for
high-impact decisions about individuals.

### Count and discovery previews

Set `countOnly: true` to save the number of matches in `COUNT_SUMMARY` without
creating Dataset rows. Set `listCategories: true` to save available category
names and counts in `CATEGORIES`. Set `listCountries: true` to save the current
country catalog in `COUNTRIES`; this mode does not require a country selection.
Set `listCollections: true` to save collection ids and category aliases in
`COLLECTIONS`. Catalog modes do not require a country selection. All preview
modes also write a structured `SUMMARY`.
Set `analyticsOnly: true` for aggregate metrics in `MARKET_ANALYTICS` without
creating result rows.
They do not create result rows, so no per-location charge applies; normal
platform runtime usage may still apply.

The Output selector is a list of separate outputs, not alternative views of the
same Dataset. **Business locations** contains the paid location rows. The other
entries open JSON records for the run summary or discovery modes. Country and
collection catalogs are included in every run; count and category outputs show
instructions when their modes were not requested, so an output no longer opens
as an unexplained empty page.

### Pricing

The price is **$0.007 per delivered location ($7 per 1,000)** on paid Apify
plans. The Free-plan tier is **$0.015 per location ($15 per 1,000)**. A small
Actor-start event and platform usage are charged separately. Empty results and
preview modes do not incur per-location charges.

#### What does an export actually cost?

| Delivered locations | Paid Apify plans | Apify Free plan |
|---:|---:|---:|
| 5 | $0.035 | $0.075 |
| 100 | $0.70 | $1.50 |
| 1,000 | $7.00 | $15.00 |
| 10,000 | $70.00 | $150.00 |

These amounts are the delivered-location fee. The small Actor-start event and
normal Apify platform usage are additional. Use `countOnly: true` before a
large export to check the available volume without paying per location.

#### How does this compare with lead-data services?

This Actor has no separate monthly data subscription: you pay for the business
locations delivered. For context, [UpLead Essentials](https://www.uplead.com/pricing/)
lists **$99 per month for 170 contact credits**, with one credit unlocking one
contact. That is about $0.58 per enriched contact before considering unused
monthly credits, compared with **$0.007 per location** here on paid Apify plans.

The products are not identical. UpLead includes person-level enrichment such as
verified emails and mobile direct dials. This Actor delivers physical business
and branch records and excludes email. The comparison explains the different
price level rather than claiming equivalent data.

Some live map scrapers can be cheaper per raw row. This Actor's value is
immediate access to a disclosed 28.2M-record snapshot, free counts, bulk
filtering and consistent scoring.

The compared price was checked on **2026-09-13** and can change. Follow the
linked official pricing page for current terms.

The Actor uses pay per event. Apify is retiring monthly rental pricing, so a new
subscription-priced Store Actor is not a durable launch option.

### Export limits

Each run is limited to 10,000 rows and offset pagination is disabled. Narrow the
request by country, company, collection, category, city, postal code, region or
radius. These controls discourage bulk replication of the entire location snapshot.

Sorting is global across every selected country and underlying data segment.
`hasMore` is based on a one-row lookahead rather than on page size alone. If any
source remains unavailable after retries, the run stops before
creating paid Dataset rows, so retrying the same input cannot silently skip a
recovered segment.

If the run's Apify maximum-charge ceiling is reached, Dataset upload stops at
the last accepted row. `rowsReturned` reflects the rows actually stored.

Large result windows are staged on local temporary storage and uploaded in
bounded batches instead of being retained in memory as one large list.

### Frequently asked questions

#### Is this a live map scraper?

No. It searches a pre-collected business-location snapshot. This makes large
exports fast and repeatable, but a recently changed listing may not yet be
reflected in the historical snapshot.

#### Can I check how many results exist before paying for an export?

Yes. Use `countOnly: true`. It writes the match total to `COUNT_SUMMARY` and
does not create per-location Dataset charges.

#### Does every record contain a phone and website?

No. These fields are returned only when present in the snapshot. Coordinates
are available throughout the current dataset. Email is not returned.

#### Can I find businesses without websites?

Yes. Set `noWebsite: true`, optionally combine it with a collection, city,
minimum rating or minimum review count, and request a small sample first.

#### How do I export more than 10,000 rows?

The Actor does not provide unrestricted offset traversal. Split a legitimate
research request into narrower geographic or category segments. Bulk snapshot
replication and redistribution are prohibited.

### API and MCP

Actor ID: `apivault_labs/business-locations-analyzer`

For an MCP-compatible client:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=apivault_labs/business-locations-analyzer"
    }
  }
}
```

AI agents should send explicit `countries`, a small `maxItems`, and a
company/category filter. An empty Dataset is a valid successful result; inspect
`SUMMARY` to distinguish zero matches from a partial data-source failure.

### Responsible use

Use of the Actor is governed by Apify's
[Standard Actor Contract](https://docs.apify.com/legal/standard-actor-contract).
That contract already requires independent verification of Actor Output,
places responsibility for downstream output use on the user, provides the Actor
as-is/as-available and limits the Creator's aggregate contractual liability to
USD 100, subject to non-waivable law. Its limitations do not exclude fraud,
negligently caused death or personal injury, or other non-excludable liability.
The product safeguards below do not replace that contract or modify statutory
rights. In particular, they do not transfer the Creator's own collection,
licensing or data-protection obligations to the user.

The Actor and its Creator are independent from, and are not sponsored,
authorized or endorsed by, any company or brand that may appear in search input
or output. Company and brand names identify the business being searched only.

The Actor is intended for internal business research, market analysis, site
planning and maintaining the user's own CRM. Users are responsible for having
an appropriate lawful basis and for providing any notices required by privacy,
marketing and communications laws.

Do not:

- resell, sublicense, publish or redistribute exported records, whether free
  or paid, including a selected subset or records repackaged in another format;
- share the output outside the purchasing individual or the single legal entity
  operating the purchasing Apify account;
- embed or repackage output in a customer-facing SaaS product, downloadable
  dataset, API, application or data marketplace;
- use the output to train, fine-tune, evaluate or enrich an AI/LLM model;
- use the output to create or augment a competing business-listing directory;
- use it for spam, harassment, stalking, discrimination, impersonation,
  fraud, unlawful profiling or unsolicited bulk messaging;
- infer sensitive personal information or make credit, employment, housing,
  insurance or healthcare eligibility decisions about individuals;
- represent snapshot data as verified current information without independent
  checks.

These boundaries concern redistribution of exported records and data products;
they do not prohibit internal reports or aggregated research findings that do
not disclose or allow reconstruction of individual records. Users remain
responsible for their inputs, campaign choices, recipients, lawful basis,
required notices, opt-outs, export security and downstream rights requests.
Publicly visible contact details are not evidence of marketing consent.

Output is provided as available and may be incomplete, duplicated or outdated.
No warranty is made about accuracy, completeness, uniqueness, merchant status,
fitness for a particular purpose, commercial value or continued availability.
Users must
independently verify records and scores before consequential use. Requests to
access, correct or remove a business or personal record can be submitted to the
Creator through the Issues tab on this Actor's Apify page.

The Actor excludes photos, email, source-specific identifiers and raw source
payloads. The usage restrictions are described here; there is no separate
checkbox gate. `intendedUse` defaults to internal business research. The Creator may refuse, limit or suspend access when
the declared or observed use creates legal, privacy, security or abuse risk.

Report suspected abuse or submit a privacy/data-quality request through the
Issues tab. Do not post identity documents or sensitive evidence publicly;
request a private channel when verification is needed. Users should inspect
purchased output within seven days; this
commercial review period does not reduce privacy rights or statutory remedies.
See `ACCEPTABLE_USE_POLICY.md`, `PRIVACY.md`, `DATA_REQUESTS.md` and the draft
`END_USER_TERMS_DRAFT.md` in the source package. The draft is not active.

Broader redistribution or product-embedding rights are not included. They may
exist only under a separate written license that has been legally reviewed and
is permitted by Apify. Billing, refunds and payment disputes are governed by
Apify's applicable platform terms; this README does not override them.

The governing contract takes precedence if a product safeguard conflicts with
it. Additional contractual output-license restrictions or customer indemnities
require legally reviewed custom terms and the process in
[Apify Store Publishing Terms, section 4](https://docs.apify.com/legal/store-publishing-terms-and-conditions#4-creator-responsibilities-towards-users).
No custom contract or indemnity is activated by this README. There is no
technical control over copies users have already exported; the safeguards are
not a claim that resale or misuse can be automatically prevented.

These usage rules allocate responsibility for a user's downstream conduct.
They do not exclude responsibilities that applicable law places on the Creator.

### Official website locations

Select `dataSource: official_websites` to read the separate collector output. Use `officialCountries` to filter countries (empty searches all), `listCountries` to discover values, or `countOnly` for a preview. Ratings and review counts are unavailable in this collection. Count, export, suppression, deduplication and existing usage restrictions apply; category catalogs and market analytics currently use the listing snapshot only. The output catalog refreshes automatically as collector storage partitions rotate.

# Changelog

This Actor's version history is a separate document: https://apify.com/apivault_labs/business-locations-analyzer/changelog.md

# Actor input Schema

## `dataSource` (type: `string`):

Snapshot: business listing records from 14 countries, including available ratings. Official websites: separate company-branch collection with normalized countries and source verification, without ratings. Default preserves existing snapshot runs.

## `officialCountries` (type: `array`):

For official_websites only. Enter ISO codes or country names, for example US, USA or United States. UNKNOWN selects records whose country cannot be recognized. Empty means all countries. listCountries reports normalized counts; countryRaw preserves the source value.

## `countries` (type: `array`):

For snapshot only: choose from the 14 connected listing countries. In official_websites mode use Official websites: countries instead.

## `maxItems` (type: `integer`):

Start with 5 results. Increase after checking coverage and the Pricing tab. Hard cap: 10000 delivered records per run.

## `businessCollection` (type: `string`):

Choose a popular business type. The Actor automatically searches the relevant category aliases. Leave empty for a custom search.

## `companies` (type: `array`):

Find physical locations whose names match any supplied company or brand, for example McDonald's, BILLA or OMV.

## `nameMatch` (type: `string`):

Contains is flexible; starts with avoids street names containing the brand; exact returns only identical names.

## `categories` (type: `array`):

Include categories such as restaurant, bank, pharmacy, supermarket, doctor or hotel. Values are OR-combined.

## `excludeCategories` (type: `array`):

Remove irrelevant matches, for example bus stop when searching for a company name.

## `categoryExact` (type: `boolean`):

Match the discovery category exactly instead of looking in all category text.

## `cities` (type: `array`):

One or more city names, partial matching, OR-combined.

## `postalCodes` (type: `array`):

Return locations in any of these postal codes.

## `states` (type: `array`):

Filter by state, province or administrative region when present in the source.

## `hasPhone` (type: `boolean`):

Return only locations that include a phone number.

## `hasWebsite` (type: `boolean`):

Return only locations that include a website.

## `noWebsite` (type: `boolean`):

Useful for web-design and local marketing prospecting.

## `includeClosed` (type: `boolean`):

Closed locations are excluded by default.

## `hasOpeningHours` (type: `boolean`):

Return only locations that include an opening-hours schedule.

## `minRating` (type: `number`):

Snapshot only. Snapshot only. Return locations with at least this rating.

## `minReviews` (type: `integer`):

Snapshot only. Snapshot only. Return locations with at least this many reviews.

## `nearLatitude` (type: `number`):

Use together with longitude and radius to search around a point.

## `nearLongitude` (type: `number`):

Use together with latitude and radius to search around a point.

## `radiusKm` (type: `number`):

Maximum distance from the center coordinates.

## `columns` (type: `array`):

Leave empty to return every available normalized field.

## `sortBy` (type: `string`):

Distance requires center coordinates and a radius.

## `countOnly` (type: `boolean`):

Preview the number of matches without creating paid Dataset rows. The result is stored in COUNT_SUMMARY.

## `listCategories` (type: `boolean`):

Snapshot only. Snapshot only. Save the available category names and counts to the CATEGORIES storage record without creating Dataset rows.

## `listCountries` (type: `boolean`):

Save the currently connected countries to the COUNTRIES storage record without creating Dataset rows.

## `listCollections` (type: `boolean`):

Snapshot only. Snapshot only. Save every collection id and its category aliases to the COLLECTIONS storage record without creating Dataset rows.

## `analyticsOnly` (type: `boolean`):

Snapshot only. Snapshot only. Return exact country-level counts, coverage, averages and freshness for the selected filters without exposing individual records or creating paid Dataset rows.

## `intendedUse` (type: `string`):

Choose your research use case. Defaults to internal business research. Usage restrictions remain described in the README.

## Actor input object example

```json
{
  "dataSource": "snapshot",
  "officialCountries": [],
  "countries": [
    "at"
  ],
  "maxItems": 5,
  "nameMatch": "contains",
  "categoryExact": false,
  "hasPhone": false,
  "hasWebsite": false,
  "noWebsite": false,
  "includeClosed": false,
  "hasOpeningHours": false,
  "sortBy": "reviews",
  "countOnly": false,
  "listCategories": false,
  "listCountries": false,
  "listCollections": false,
  "analyticsOnly": false,
  "intendedUse": "internal_business_research"
}
```

# Actor output Schema

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

Normalized physical business and branch records.

## `summary` (type: `string`):

Run status, totals, quality notice and export-limit information.

## `countSummary` (type: `string`):

Free countOnly result by country, or instructions when this mode was not requested.

## `marketAnalytics` (type: `string`):

Non-row-level counts, coverage, averages and freshness, or instructions when analyticsOnly was not requested.

## `categories` (type: `string`):

Free category discovery result, or instructions when this mode was not requested.

## `availableCountries` (type: `string`):

Snapshot country catalog, or normalized official-country counts when listCountries is requested. UNKNOWN groups unrecognized source values.

## `availableCollections` (type: `string`):

Collection ids and category aliases. This catalog is included in every run.

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("apivault_labs/business-locations-analyzer").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("apivault_labs/business-locations-analyzer").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 '{}' |
apify call apivault_labs/business-locations-analyzer --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,apivault_labs/business-locations-analyzer"
        }
    }
}
```

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/yPvv9eeqbTqh4ki8t/builds/E3Sep9mvUbJCIZS0B/openapi.json