tam-builder

TAM Builder

Overview

This skill produces an account universe: one row per distinct company in a defined market, pulled from every ScraperCity source that covers it, deduped, with a source column showing where each row came from. It adds a coverage estimate (the share of the market the file holds), a TAM, SAM and SOM in accounts and dollars, and, when the user wants to know where to start, a fit score and Tier 1 to 3 cut to the team's capacity.

It prevents three failures. The first is quoting a market size from one database count, which double counts people as companies and misses businesses the source does not hold. The second is merging three sources without a dedupe key, which inflates the market and sends the same business three emails. The third is a Tier 1 list built from a score nobody tested and sized beyond what the reps can work.

When to Use

• "How many HVAC contractors are there in Texas, and can I get all of them?"
• "Build our TAM for the board deck."
• "Every Shopify store selling pet supplies in the US."
• "Account universe for territory planning."
• "Which metros have the most targets per rep?"
• "Which 100 accounts should our AEs work first?" or "Tier our account list."

Use a different skill when:

Prerequisites

Authoritative Foundations

Detail in references/framework-notes.md.

Workflow

1. Write the market definition

One sentence with all four parts: business type, geography, size band, exclusions. Example: "Residential and light commercial HVAC contractors in Texas, any size, excluding supply houses and manufacturers." Map it to a NAICS code for the CBP benchmark (238220 Plumbing, Heating, and Air-Conditioning Contractors in this example). Recipes for common markets are in references/market-definition-recipes.md.

2. Pick sources by market type

3. Count every source before pulling

• Local Business Database: one call with limit: 1, read pagination.total. That is a business count.
• Lead Database: pagination.total counts people, not companies. Use a one-per-company title set (Owner, Founder, CEO, President, General Manager), pull a sample (the worked example uses 500 rows), compute unique domains divided by rows, and multiply the total by that ratio for an estimated company count.
• Store Leads: there is no free count. Run a totalLeads: 100 probe with the filters ($0.0039 per lead, $0.39) and read the rows to confirm the filters fit before a large job.
• Maps: there is no count call. Estimate from metro size (see references/coverage-and-dedupe-playbook.md) and cap with maxCrawledPlacesPerSearch.

Put the counts in one table with the projected cost and show it to the user. Stop for a go-ahead if paid steps exceed $5.

4. Pull the databases with cursors

check_wallet, then page each database with after: "0" and limit: 100, passing pagination.next_after until null. Pulls above 100,000 new records per database per day split across days (by state or metro). Save each page to disk with source and source_detail.

5. Fill gaps

Decide where to scrape by comparing database counts per metro against population or against CBP per county. Metros with the lowest database count per 100k residents against the state average are gap candidates; the user picks the cutoff. For each:

• scrape_maps with searchStringsArray set to the category's keyword variants and locationQuery set to each sub-city (metros split into sub-cities; lists in references/coverage-and-dedupe-playbook.md).
• Before paying, read the local_business_database block a Maps run can return: it reports matches already in the database that the account does not have yet. Pull those from the database first.
• Poll check_run_status until the run reaches SUCCEEDED, then download_results.

6. Normalize and dedupe

Normalize every row to the business schema (references/list-quality-standard.md section 2b). Then dedupe in three passes:

1. Registrable domain (blank for social-only websites).
2. business_name_key plus postal_code, then business_name_key plus street, for rows with no domain.
3. Phone in E.164 as a final catch for rows that share neither.

When rows match, keep the most complete record by completeness score, fill empty fields from the other rows, and join every contributing source into source (for example local_db|maps).

6b. Import outside lists and tier confidence

When the market has a public register (banks, credit unions, nonprofits, federal contractors, public companies, schools), pull the register first: its count is the TAM denominator and the ScraperCity pulls supply people and emails (references/market-definition-recipes.md, Public registries). Add the outside lists that fit the market (the vertical table in the same file names one per market): state license files and association directories for trades, the CMS NPPES provider file for healthcare, exhibitor and sponsor lists for vendor markets, Inc. 5000 for growth segments, G2 categories and GitHub organizations for software, Crunchbase for funded companies, job boards for companies hiring a role. None is a ScraperCity source: tag rows source = user_upload with the list name in import_sources. Dedupe each list against itself, then against the file (domain, then phone, then name key + ZIP). Matched rows add to import_sources; new rows join only when they fit and carry a domain or phone; the rest go to a review file. Count found_in per account and label it: found in 3 or more sources High, 2 Medium, 1 Low. The labels name the count; a hand check of Low and High accounts on the user's file shows what each level means. Then write Source Yield: per source, accounts contributed, accounts no other source found, cost, and cost per unique account; a paid source whose unique accounts cost more than the Tier 3 spend ceiling (when the user's deal inputs set one) is dropped from the next refresh. Procedure, source table, overlap and yield reports: references/coverage-and-dedupe-playbook.md sections 9 to 12.

7. Estimate coverage

Pick 1-3 metros covered by two sources. Run Chapman's estimator on the overlap (formula and caveats in references/coverage-and-dedupe-playbook.md). Report observed accounts, estimated true count, and coverage percentage. Compare the statewide deduped count against the CBP establishment count for the NAICS code (data.census.gov, County Business Patterns filtered to the NAICS code and state; the Census API needs a free key), and add the NES count when the market includes owner-only businesses.

8. Size TAM, SAM, SOM

9. Score and tier (when asked)

Follow references/account-scoring-and-tiers.md: hard exclusions first, score only columns filled on at least the share of SAM rows the user sets (report every column's fill rate), points from win-rate lift (10 x log2 of lift, capped at plus or minus 10) when closed deals join the file, tier sizes from rep capacity, a spend ceiling per account only when the user supplies ACV, gross margin and win rates per tier (written on a "Deal inputs (from you):" line; otherwise the column is left out), and a backtest on current customers (Tier 1 and 2 must hold a larger share of customers than of SAM, a concentration above 1.0x, or the higher bar the user sets). Fit sets the tier; three things move an account up one tier for the next send cycle (Alex Berman spaces cycles 30 to 60 days apart, alexberman.com, October 2026): a dated trigger, first-party engagement from the user's CRM or marketing tool (pricing page visit, webinar, a past reply), and a warm path (a former customer champion now works there, a TeamLink connection). Write the Account Tiers section with its Capacity and Backtest lines, and book the quarter-end read: meetings per 100 accounts worked, by tier.

10. Deliver

Deliver the CSV and the report in templates/output-template.md, including Source Overlap and Source Yield. Run scripts/check-output.py.

ScraperCity Implementation

Calls for the HVAC example

Local Business Database count:

{"keyword": ["hvac contractor", "air conditioning contractor", "heating contractor"],
 "location": ["Texas"], "notCategory": ["Appliance store", "HVAC supply store"], "limit": 1}

Pull: same body with "limit": 100, "after": "0", then each pagination.next_after. Read searched_as in the first response to confirm Texas was read as the state.

Lead Database company proxy:

{"title": "Owner, President, CEO, Founder, General Manager",
 "notTitle": "assistant, former, sales, technician",
 "keywords": ["hvac"], "companyState": ["Texas"], "limit": 100, "after": "0"}

Maps gap fill for one metro:

{"searchStringsArray": ["hvac contractor", "air conditioning repair", "heating contractor"],
 "locationQuery": "Pasadena, TX", "maxCrawledPlacesPerSearch": 50}

maxCrawledPlacesPerSearch applies per search term, so this call can return up to 150 businesses (3 terms x 50) and cost up to $1.49. Each sub-city is a separate run; keep a list of run ids. Store Leads for an ecommerce TAM: {"platform": "shopify", "countryCode": "US", "category": "pet supplies", "totalLeads": 1000, "offset": 0}, then raise offset by totalLeads each call or send back nextOffset.

Worked cost estimate

The two database pulls use 9.8% and 6.2% of their daily allowances. $35.64 exceeds $5, so show the table and wait for approval before the Maps runs.

Output Format

1. tam-[market]-[date].csv: one row per account, business schema from the quality standard plus source, source_detail, import_sources, found_in, confidence, completeness_score, metro, in_sam (true or false).
2. tam-review-[market]-[date].csv: outside-list rows held for review, with a reason.
3. A report from templates/output-template.md: market definition, source counts, pull and dedupe funnel, source mix, source overlap, source yield (unique accounts and cost per unique account per source, with a keep or drop call for the next refresh), coverage estimate, TAM/SAM/SOM, metro breakdown, account tiers when asked, cost, output schema, next steps.
4. When tiers were asked for: fit_score, tier and tier_reason columns in the CSV.

What the reader receives is the deliverable only: no internal file paths, reference section numbers, tool ids or skill names (name the product, such as Lead Database or Email Validator, and describe the next action instead of naming a skill); each figure stated once; every outside number with its source and date on first mention; no spend ceiling without the user's deal inputs; no invented team size (one Capacity line asks for headcount); no table of checks that were not run (one "Not checked:" line instead); no legal commentary. Next Steps is a table with Step, Owner, Date and Done when.

Quality Check

• Market definition names business type, geography, size band and exclusions.
• Every source was counted before pulling; counts and cost shown before paid runs.
• Lead Database totals converted from people to companies with a sampled ratio.
• Funnel adds up from raw rows to final accounts with a reason on each drop.
• Source mix rows sum to the final account count.
• Every row has a source value from the controlled vocabulary.
• Source Overlap: found-in-N rows sum to the final count, confidence matches N, and each outside list reconciles (rows = matched + new + held).
• Coverage estimate shows observed, estimated and percentage, with its caveat.
• TAM, SAM and SOM each show accounts, ACV and dollars, and SOM states its assumption.
• Source Yield shows unique accounts per source, never more than the source contributed, with a keep or drop decision.
• If tiers are included: hard exclusions listed, tier counts sum to SAM, Tier 1 fits the stated capacity, and the Backtest line shows a concentration above 1.0x.
• scripts/check-output.py report.md prints PASS.

Common Pitfalls

Execution Artifacts

Related Skills

• icp-list-builder for a contact list from one slice of this TAM.
• local-business-list for one city with validated emails.
• ecommerce-by-techstack for online store markets by app or technology.
• decision-maker-finder to add buyers to the accounts, starting with Tier 1.
• account-researcher for a brief on each Tier 1 account.
• signal-triggered-outbound to find the triggers that lift an account one tier.
• crm-enricher to load the account universe into HubSpot or Pipedrive.
• scrapercity-local-business-database and scrapercity-lead-database for every parameter.