---
name: vertical-maps
description: Find and export US local businesses (name, address, phone, website, email, size) by business type and area with Vertical Maps. Use when the user wants a list of local businesses to prospect, a count of businesses of a type in a city, state or radius, or a CSV of leads such as "dentists in Phoenix" or "restaurants near 10001 without a website".
---

# Vertical Maps

Vertical Maps has 15M+ US businesses with contact details (listings marked closed are left out).
Counting and previewing are free; exporting costs 1 credit per business (re-exporting a business
already bought is free).

Base URL: `https://verticalmaps.co`
Auth: `Authorization: Bearer $VERTICALMAPS_API_KEY` (create a key at https://verticalmaps.co/account)

## Workflow

1. **Resolve the business type.** `GET /api/categories?q=<word>` returns two lists with counts.
   `trades` are everyday trade names ("plumbers", "realtors", "dentists"): if one matches, use its
   `nodes` as the `categories` of the search. Otherwise use `categories`: search with the first 4-5
   letters of the word and pick the broadest match, since a parent type such as `dental_clinic`
   covers all its children.
2. **Count for free.** `POST /api/count` with the search body below. Report the total and how many
   have an email, phone and website.
3. **Preview for free.** `POST /api/preview` returns 10 sample rows with contact details partly hidden.
4. **Ask before spending credits.** Tell the user how many businesses the export will contain and
   that it costs that many credits (minus any they already own). Send the export body with
   `"dryRun": true` first: it returns `charge` (credits it would take, businesses already owned left
   out) and `exact`, and spends nothing. Only export after they confirm, with `"maxCharge"` set to
   that figure.
5. **Export.** `POST /api/export` with the same body plus `"max": <number of rows>`. The response is a
   CSV. HTTP 402 means not enough credits: the JSON says how many are needed and how many they have
   (on a search of more than 1,000 businesses with `max` above what the credits cover, `needed` is
   the most the export could cost, and the real cost can be lower; the JSON then carries
   `"exact": false`). HTTP 409 means the export would take more credits than `maxCharge`: nothing
   was charged, so run the dry run again. HTTP 429 means too many exports
   in a short time (an account can run 10 every 10 minutes and 100 a day): wait a few minutes and
   try again.

## Search body

```json
{
  "categories": ["dental_clinic"],
  "state": "AZ",
  "city": "Phoenix",
  "hasEmail": false,
  "hasPhone": false,
  "noWebsite": false,
  "excludeChains": true,
  "sizeBands": ["5-9", "10-19"]
}
```

- Location: either `state` (2 letters) with an optional `city`, or a radius: `"lat": 33.45, "lon": -112.07, "miles": 10`.
  To turn an address into lat/lon: `GET /api/geocode?address=<address>`.
- `sizeBands`: any of `1-4`, `5-9`, `10-19`, `20-49`, `50-99`, `100-249`, `250+` (employees, from public payroll records; not every business has one).
- `noWebsite: true` finds businesses with no website listed.
- `excludeChains: true` keeps independents only.
- `hasOwner: true` keeps businesses with the owner's name on file (state licence records; the CSV column is `owner_name`).
- `confirmedOpen: true` keeps businesses that match an active government record (the field keeps its old name; call it "active government record" when you talk to the user): an active Texas sales tax permit, a state licence in force (contractors and trades in nine states), an active registration or licence with the city of Los Angeles, San Francisco, Seattle, Chicago or New York, an active US DOT registration (businesses that run commercial trucks), an active entry in a state business register (Oregon, Colorado, Connecticut, Texas, New York, Pennsylvania, Delaware), a liquor licence in force (New York, Texas) or an active federal contractor registration. The CSV column is `confirmed_open` and names the record. It shows the record is in force today. It is not proof that the location is operating, and a business without it is not closed. Coverage differs by state.

## CSV columns

business_name, owner_name, category, address, city, state, zip, phone, website, email, email_status, email_source,
email_type, chain, employees, status, lat, lon, facebook, instagram, confirmed_open

The file is UTF-8 and starts with a byte order mark, so Excel shows accented names correctly. In
Python read it with `encoding="utf-8-sig"`, or the first column name will not match. Rows are sorted
by ZIP code, then street. When `max` is smaller than the number of matches, businesses with an
email are picked first.

- `zip` is five digits, or empty when we have no ZIP code for the business. Keep it as text, or ZIP
  codes such as 02134 lose their first zero.
- `phone` is written `(512) 555-0142` for US numbers.
- `email_status` is `Previously delivered` when the address has already received email without
  bouncing, with the day where it is on record (`Previously delivered on 2026-08-18`). Otherwise
  `not tested`. No address has been through a verification check. Empty when the business has no email.
- `email_type` is `generic inbox` (info@, contact@...) or `named` (a person's or owner's own address).
- `status` is `listed as open`, or `not marked closed` when the listing gives no status. Businesses
  listed as closed are left out. Only `confirmed_open` has a government record behind it, and neither
  column proves the location is operating today. Do not tell the user a business is "confirmed open".
- `employees` is a band such as `5 to 9`, where known.

## New-business feed and business changes

`POST /api/new/search` (free) and `POST /api/new/export` (key, same credits) list new government
records from the last 12 months: permits, licences and registrations. Body: `state` (2 letters),
optional `city` or `lat`/`lon`/`miles`, `trades` (names from the search response), `opened`
(`soon`, `30`, `90`, `365`, `all`: a filter on the date on the record), `storefrontOnly`,
`newOwnerOnly`, `hasContact`, `event`.

- A row is a new record, not proof that a business has opened. Say "new sales tax permit", "first
  contractor licence" or "newly registered with the US DOT", as `rows[].signals[0].label` does.
  A new US DOT registration is never a "newly opened business": it can be an existing business
  putting trucks on the road.
- `rows[].opened` is the date on the record and `rows[].date_label` says which date it is. In
  Texas it is the first-sale date the business declared; when it is still ahead it is an expected
  opening date, declared and not checked. No opening date is inferred.
- `event`: `branch` is a new location, reported by the register (Texas, Los Angeles, Chicago;
  inferred from register dates in San Francisco). `changed_hands` (possible change of owner),
  `replaced_same`, `replaced` and `incorporated` (same business, new registration) are inferred by
  matching street addresses, in Texas, Los Angeles and San Francisco only. Each entry of
  `rows[].signals` carries `basis` (`reported` or `inferred`) and `how`: pass both on to the user.
- Call these business changes. They are a reason to get in touch, not a sign that the business is
  looking for a supplier.
- Coverage differs by state: Texas has new sales tax permits for all trades; California, Washington,
  Illinois, Connecticut, Oregon and Minnesota have a city register, a state register or a licence
  board; every other state has US DOT registrations only.

## Rules

- Never export without the user's go-ahead on the credit cost.
- The data is business contact information. The user is responsible for following the rules where
  they send, such as CAN-SPAM in the US.
