---
name: build-niche-company-database
description: Build a source-backed company and location database for a niche using Google Maps and Google Search.
---

# Build a company database for your niche

Build company and location records with phones, domains and source evidence for
CRM staging in the user's chosen niche and locations. The example budget covers
two categories in three cities, with two Maps pages per query and up to 20
identity/qualification searches: **32 calls, $0.00480** at $0.15 per 1,000
successful calls. This is a reusable plan, not a measured run.

## 1. Check the key and scope

Before making any API requests, ask the user: "Which business niche or categories
should I include, and which cities or areas should I cover?" Skip only inputs
already supplied by the user. Do not infer a niche or location from examples;
clarify ambiguous place names before searching.

Agree pages per query and an attempt cap for the supplied scope. Specify exact-city
versus metro/service-area coverage, whether a street address is required, and
any commercial-service, independent-ownership or franchise exclusions. Separate
those requirements: a local franchise can be independently owned, and a Maps
query does not prove a firm offers commercial services. Check the balance:

```bash
curl --fail-with-body --silent --show-error https://api.litescrape.com/api/keys/status \
  -H "Authorization: Bearer $LITESCRAPE_API_KEY"
```

Read `remaining_calls` and `concurrency_limit`; use at most that concurrency and
never start a request that would exceed the lower of the agreed cap and remaining
calls. Calculate Maps calls from the agreed category/location combinations and
pages per query; the example's two categories times three cities times two pages
use twelve Maps calls. Reserve up to 20 remaining attempts for identity and
qualification checks, including retries. Agree the allocation before starting;
ask before expanding beyond the 32-attempt example budget. Save every raw
response under a unique query/page filename.

## 2. Collect location candidates

Set `BUSINESS_CATEGORY` and `LOCATION` from the user's inputs for each query.
For an agreed two-page scan, run each category-location combination at `start=0`
and `start=20`; otherwise follow the agreed page count in increments of 20:

```bash
curl --fail-with-body --silent --show-error -G https://api.litescrape.com/api/google/maps \
  -H "Authorization: Bearer $LITESCRAPE_API_KEY" \
  --data-urlencode "q=${BUSINESS_CATEGORY:?Set the user-supplied business niche} in ${LOCATION:?Set the user-supplied location}" \
  --data-urlencode 'type=search' --data-urlencode 'start=0' \
  -o category-location-0.json
```

Read `local_results`; retain `title`, `address`, `phone`, `website`, category,
`place_id`, map link, query and page. Deduplicate physical locations by
`place_id`. Group them into a company only when returned names, domain or other
identity evidence supports the relationship. Do not merge namesakes, branches
or franchises merely because their names resemble each other. A place ID
identifies a listing, not verified physical premises. Preserve missing addresses
as `physical_address_status=unknown`, and classify geography from returned
address evidence, not the query alone. Do not discard service-area businesses
unless a physical address is a stated requirement. Generated company IDs are
provisional account identifiers, not verified legal entities.

## 3. Resolve identity and qualify the shortlist

Within the agreed search reserve, first resolve company entities lacking a
supported domain using quoted name and location. Set `COMPANY_NAME` from the
returned listing and `COUNTRY_CODE` from the user's target geography, clarifying
if needed. `fast_mode=true` returns organic results only.

```bash
curl --fail-with-body --silent --show-error -G https://api.litescrape.com/api/google/search \
  -H "Authorization: Bearer $LITESCRAPE_API_KEY" \
  --data-urlencode "q=\"${COMPANY_NAME:?Set the returned company name}\" ${LOCATION:?Set the user-supplied location}" \
  --data-urlencode 'fast_mode=true' --data-urlencode "gl=${COUNTRY_CODE:?Set the target country code}" \
  -o company-domain.json
```

Match a domain only when result identity evidence supports that company and
geography. Directories, marketplaces and social profiles are not company domains.
A name substring in a URL alone is not enough. Keep high, medium and unresolved
match confidence with evidence URLs; this is domain-association confidence,
not ownership verification. Keep business-specific hosted subdomains/paths;
sharing Wix, Jobber or another platform host is not a company relationship.

Use remaining search slots to qualify a bounded shortlist against the supplied
requirements. Prioritize otherwise in-scope records with usable business contacts,
then original query/page/rank and place ID. Search the exact business identity,
city and unresolved requirement (for example commercial services or ownership),
using `as_sitesearch` with its supported company hostname when available. Keep
the evidence snippet and link for each supported status. Query words, absence
from a chain-name list and unverified Maps website fields are not proof. Leave
unsupported facts unknown and report how many companies were actually checked.
Label first-party ownership statements as `self_reported`, not independently
verified legal ownership. A dated ownership story is historical evidence until
current status is supported. Prefer one unresolved requirement per query; keep
stale or anomalous indexed pages in review rather than using them to qualify an
account. Preserve the exact source date when available.
Do not exceed the agreed cap (32 attempts in the example plan) or silently
research every candidate.

## 4. Return separate company and location files

Write `companies.csv`:

```text
company_id,name,domain,domain_confidence,domain_evidence,category,ownership_status,franchise_affiliation,commercial_service_fit,qualification_status
```

Write `locations.csv`:

```text
location_id,company_id,name,address,phone,place_id,source_query,source_url,physical_address_status,geography_status
```

Write `qualification-review.csv` with missing requirements, conflicts, evidence
URLs and next checks. Keep `crm-ready.csv` limited to records satisfying every
supplied hard requirement; the full database remains a staging dataset and may
contain zero ready accounts. Do not make an arbitrary high-confidence domain
score stand in for ownership, service fit or address verification.

Also write `manifest.json` with the user-supplied scope, agreed cap, queries,
pages, attempted/successful calls, dedupe rules,
unresolved identities and a stop reason. Report raw locations, unique locations,
companies and domain-confidence totals. Ask before more than 32 calls; stop on
empty continuation, exhausted balance or the agreed cap. A missing result does
not prove a company does not exist. Stop immediately on 401, 403 or 402. Retry a
429 or transient 5xx once, honoring `Retry-After`, only when the retry remains inside the cap; otherwise
record the error. Never print the key or send it to a source link.