Business Monster API

Everything the dashboard does, from your own code. Start a Google Maps search, poll it, and download every business with contact details, verified emails, social profiles, reviews and photos as JSON, NDJSON, CSV, XLSX or XML.

API keys are created in your dashboard under API. New accounts start with 20 free credits, so you can make your first calls before buying anything.

Quick start

Three calls: start a search, wait for it to finish, download the records.

# 1. Start a search
curl -X POST https://api.businessmonster.co/v1/searches \
  -H "Authorization: Bearer bm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"location": "Austin, TX, USA", "keyword": "dentist", "max_results": 500}'

# 2. Poll until "status" is "completed" (every 5 to 10 seconds is fine)
curl https://api.businessmonster.co/v1/searches/SEARCH_ID \
  -H "Authorization: Bearer bm_live_YOUR_KEY"

# 3. Download the records in the format you need
curl "https://api.businessmonster.co/v1/searches/SEARCH_ID/results?format=xlsx" \
  -H "Authorization: Bearer bm_live_YOUR_KEY" -o dentists-austin.xlsx

Authentication

Send your key in the Authorization header of every request:

Authorization: Bearer bm_live_23e8a631…

• Keys are created and revoked in the dashboard (API page). A key is shown once, at creation; we store only a hash of it.
• You can have up to 5 active keys, for example one per integration. Revoking a key stops it immediately.
• Every key acts on the credits of the account that created it. Keep keys on your server, never in browser code.

AI assistants (MCP)

Business Monster ships an MCP server, so Claude, ChatGPT, Cursor and any other assistant that speaks the Model Context Protocol can run searches for you directly in the conversation. Ask for "opticians in Kütahya with phone numbers" and the assistant starts the search, waits for it, and hands you the file. It spends the credits on your own account, at the same prices.

Connecting

If your client can send headers (Cursor, Claude Code, n8n, most SDKs), point it at the server URL and add your key as a Bearer token:

{
  "mcpServers": {
    "business-monster": {
      "url": "https://api.businessmonster.co/mcp",
      "headers": { "Authorization": "Bearer bm_live_YOUR_KEY" }
    }
  }
}

If your client only accepts a URL (for example Claude's "Add custom connector" box), put the key in the path instead. It works exactly the same:

https://api.businessmonster.co/mcp/k/bm_live_YOUR_KEY

Tools the assistant gets

What to expect

• Results come back a page at a time. A conversation cannot hold a thousand rows, so the assistant reads 25 records at a time, up to 200 if it asks, and can request only the fields you asked for. The complete file with all 100+ fields is downloaded from your dashboard, never handed out as a link in the chat.
• Searches are not instant. A few hundred businesses take one to five minutes. The assistant checks the status every 15 to 30 seconds while it waits.
• Same credits, same prices. 1 credit per business; reviews and photos beyond the free first page cost 10 items = 1 credit. No surcharge for using MCP. The assistant is told to warn you before starting anything larger than about 1,000 businesses.
• Same limits. 60 requests per minute per key. No limit on how many searches run at once.
• Built for assistants. Every tool declares an output schema, and every result carries a summary of what happened and a next_step naming the single follow-up call with the id already filled in. That is what keeps the assistant from guessing its way through a multi-step job.

Endpoints

Start a search

POST/v1/searches

JSON body. Only location and keyword are required.

The search object

{
  "id": "24b3ca0c-1f3a-4111-9ff5-31feb4e51660",
  "status": "completed",              // queued · running · completed · failed · cancelled
  "location": "Eskişehir",
  "keyword": "pharmacy",
  "query": "Eskişehir, Turkey pharmacy",
  "language": "en",
  "max_results": 20,
  "max_reviews_per_place": 15,
  "max_images_per_place": 0,
  "reviews_since": null,
  "max_credits": null,
  "results_count": 20,
  "credits": { "reserved": 50, "charged": 27 },   // charged is null until the search finishes
  "created_at": "2026-09-11T06:40:43Z",
  "started_at": "2026-09-11T06:41:02Z",
  "completed_at": "2026-09-11T06:42:18Z",
  "error": null
}

• queued: accepted, waiting to start or for credits. running: collecting. completed: results ready. failed: something went wrong, nothing charged for missing records. cancelled: cancelled before it started, reserved credits released.
• error is null or carries a code and a message:

Results and formats

GET/v1/searches/{id}/results?format=json

Each record is a full business profile with 100+ fields: name, category, address, coordinates, phone, website, opening hours, rating and review count, price level, verified email, social profiles (Facebook, Instagram, LinkedIn, X, TikTok, YouTube and more), website technology signals and, when requested, the reviews and photos. See what's in a record.

Choosing the columns: view, fields, unwind

GET /v1/searches/{id}/results?format=csv&view=simple                       → the lead list
GET /v1/searches/{id}/results?format=json&fields=title,phone,email         → three columns only
GET /v1/searches/{id}/results?format=xlsx&unwind=reviews&fields=title,stars,text → one row per review

Streaming a running search:

GET /v1/searches/{id}/results?format=ndjson&after_id=0     → first batch, remember the last _id
GET /v1/searches/{id}/results?format=ndjson&after_id=48213 → only records written since

Pricing and credits

The API uses the same credits as the dashboard, with no extra fee.

• 1 credit = 1 business record. All 100+ fields included.
• Reviews and photos: the first page is always included. Beyond it, 10 reviews = 1 credit and 10 photos = 1 credit, per business.
• No minimum per search. Ask for 5 businesses or 50,000.
• No results, no charge. Credits never expire.

Check your balance any time with GET /v1/account. Buy credits in the dashboard.

Errors

Errors use HTTP status codes and a JSON body:

{ "error": { "code": "insufficient_credits", "message": "Not enough credits to start a search. Available: 0. Buy credits in your dashboard." } }

Rate limits

• 60 requests per minute per API key. Above that you get 429 rate_limited with a Retry-After header. Polling a search every 5 to 10 seconds stays far below the limit.
• There is no limit on how many searches run at the same time, nor on the number of businesses or credits.

Code examples

Python

import requests, time

API = "https://api.businessmonster.co/v1"
H = {"Authorization": "Bearer bm_live_YOUR_KEY"}

search = requests.post(f"{API}/searches", headers=H, json={
    "location": "Austin, TX, USA", "keyword": "dentist", "max_results": 500,
}).json()

while search["status"] in ("queued", "running"):
    time.sleep(10)
    search = requests.get(f"{API}/searches/{search['id']}", headers=H).json()

if search["status"] == "completed":
    rows = requests.get(f"{API}/searches/{search['id']}/results",
                        headers=H, params={"format": "json"}).json()
    print(len(rows), "businesses,", search["credits"]["charged"], "credits")

Node.js

const API = "https://api.businessmonster.co/v1";
const H = { Authorization: "Bearer bm_live_YOUR_KEY", "Content-Type": "application/json" };

let search = await (await fetch(`${API}/searches`, {
  method: "POST", headers: H,
  body: JSON.stringify({ location: "Berlin, Germany", keyword: "coffee shop", max_results: 300 }),
})).json();

while (["queued", "running"].includes(search.status)) {
  await new Promise(r => setTimeout(r, 10000));
  search = await (await fetch(`${API}/searches/${search.id}`, { headers: H })).json();
}

const rows = await (await fetch(`${API}/searches/${search.id}/results?format=json`, { headers: H })).json();
console.log(rows.length, "businesses");

Streaming while the search runs (Python)

import json
after = 0
while True:
    r = requests.get(f"{API}/searches/{search['id']}/results",
                     headers=H, params={"format": "ndjson", "after_id": after}, stream=True)
    for line in r.iter_lines():
        rec = json.loads(line)
        after = rec["_id"]
        handle(rec)                      # your code
    status = requests.get(f"{API}/searches/{search['id']}", headers=H).json()["status"]
    if status not in ("queued", "running"):
        break
    time.sleep(10)

Questions? Write to us from the dashboard's Support page, or open the interactive reference to try every endpoint in the browser.