Google Maps scraper API

Authentication

Generate a key in Settings. It starts with hub_live_ and is shown once. We only store a hash, so if you lose it you rotate it rather than recover it. Pass it as a Bearer token on every request.

curl https://hubertino.com/api/v1/scrapes \
  -H "Authorization: Bearer hub_live_your_key_here"

Base URL: https://hubertino.com/api/v1. Request and response bodies are JSON, except the export, which returns the file. A key can spend the whole account's credits (there are no read-only keys yet), so keep it server-side.

Quickstart: curl, Python, Node

Start a scrape, poll it until it's done, then download the CSV. The same three calls in each language:

export HUBERTINO_API_KEY=hub_live_your_key_here
API=https://hubertino.com/api/v1
AUTH="Authorization: Bearer $HUBERTINO_API_KEY"

# 1. Start a scrape: 1 category x 1 location, up to 50 places
#    (Starter/Pro: add "seoAudit":true and/or "findContacts":true for the paid add-ons)
ID=$(curl -sS "$API/scrapes" -H "$AUTH" -H "content-type: application/json" \
  -d '{"categories":["dentist"],"locations":["Austin, TX, United States"],"maxResults":50}' \
  | jq -r .scrape.id)

# 2. Poll until it finishes: queued -> running -> done | error
while :; do
  STATUS=$(curl -sS "$API/scrapes/$ID" -H "$AUTH" | jq -r .scrape.status)
  echo "$STATUS"
  case "$STATUS" in done) break ;; error) exit 1 ;; esac
  sleep 5
done

# 3. Download the CSV: one business per row, 38 columns (more with add-ons)
curl -sS "$API/scrapes/$ID/export?format=csv" -H "$AUTH" -o leads.csv

# pip install requests
import os, time, requests

API = "https://hubertino.com/api/v1"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['HUBERTINO_API_KEY']}"

def call(method, path, **kwargs):
    res = session.request(method, API + path, timeout=120, **kwargs)
    if res.status_code >= 400:  # every error body is {"error": "..."}
        raise SystemExit(f"HTTP {res.status_code}: {res.text}")
    return res

# 1. Start a scrape
scrape = call("POST", "/scrapes", json={
    "categories": ["dentist"],
    "locations": ["Austin, TX, United States"],
    "maxResults": 50,
    # "seoAudit": True, "findContacts": True,  # paid add-ons, Starter/Pro
}).json()["scrape"]

# 2. Poll until it finishes (and, with paid add-ons, until their charge is final)
while scrape["status"] not in ("done", "error") or scrape.get("addonsPending"):
    time.sleep(5)
    scrape = call("GET", f"/scrapes/{scrape['id']}").json()["scrape"]
if scrape["status"] == "error":
    raise SystemExit(scrape["error"])  # the reserved credits were refunded

# 3. Download the CSV
csv = call("GET", f"/scrapes/{scrape['id']}/export", params={"format": "csv"})
with open("leads.csv", "wb") as f:
    f.write(csv.content)
print(scrape["resultCount"], "businesses,", scrape["creditsCharged"], "credits charged")

// Node 18+, no dependencies. Save as scrape.mjs and run: node scrape.mjs
import { writeFile } from "node:fs/promises";

const API = "https://hubertino.com/api/v1";
const auth = { authorization: `Bearer ${process.env.HUBERTINO_API_KEY}` };

async function call(path, init = {}) {
  const res = await fetch(API + path, { ...init, headers: { ...auth, ...init.headers } });
  if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`); // {"error": "..."}
  return res;
}

// 1. Start a scrape
let { scrape } = await (
  await call("/scrapes", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({
      categories: ["dentist"],
      locations: ["Austin, TX, United States"],
      maxResults: 50,
      // seoAudit: true, findContacts: true, // paid add-ons, Starter/Pro
    }),
  })
).json();

// 2. Poll until it finishes (and, with paid add-ons, until their charge is final)
while ((scrape.status !== "done" && scrape.status !== "error") || scrape.addonsPending) {
  await new Promise((r) => setTimeout(r, 5000));
  ({ scrape } = await (await call(`/scrapes/${scrape.id}`)).json());
}
if (scrape.status === "error") throw new Error(scrape.error); // credits refunded

// 3. Download the CSV
await writeFile("leads.csv", await (await call(`/scrapes/${scrape.id}/export?format=csv`)).text());
console.log(`${scrape.resultCount} businesses, ${scrape.creditsCharged} credits charged`);

The full scripts add error handling, progress output and paging through the rows as JSON: scrape.sh (bash, curl, jq), scrape.py (Python 3 + requests), scrape.mjs (Node 18+).

The 38 columns

One row per business, in the same order in JSON results and in the CSV/XLSX export. Any column can be empty when the listing or website doesn't publish it. In our own samples (67,173 businesses, harvested July 2026), an email was found for 64% of the businesses where the website check ran.

A scrape that ran with an existing-contacts list adds one more column after these: existing, true for places on your list and false for the rest in JSON, written as True/False in the CSV and as a TRUE/FALSE cell in the XLSX. Then come the columns of any paid add-on the scrape ran with. Download a sample CSV (fictional businesses, both add-ons' columns filled in, decision makers masked) to see the exact format, or read why to keep place_id and CID.

Compared with the Google Places API

Google's Places API has no email field and no social profile fields, so a lead list built on it still needs every business's website crawled afterwards. This API does that crawl as part of each row.

Credits & price per 1,000

One credit is one new business delivered (places on your existing-contacts list are free, see below); the email and social lookups cost nothing extra, and paid add-ons are extra. Per 1,000 businesses that's $0.38 on Starter ($19/month for 50,000 credits), $0.276 on Pro ($69/month for 250,000), or $0.58 / $0.472 / $0.396 with one-time packs that never expire. Plan figures assume the month's credits get used. Counting only businesses where an email was found, Pro works out at $0.434 per 1,000. See pricing or how that compares with other scrapers.

When a scrape starts we reserve its worst case (categories × locations × maxResults × (1 + the price of each add-on on), capped at your balance). When it finishes you're charged only for rows delivered and the rest is refunded. A failed scrape is refunded in full, a search that finds nothing costs nothing, and a cancelled scrape costs only the new places whose details were in by then. That's why creditsReserved can be much larger than the final creditsCharged, which stays null until the scrape settles, add-ons included (addonsPending).

Places you already have are free. Import their Google Place IDs (up to 50,000) under Dashboard → Settings → Existing contacts, and every scrape, API scrapes included, checks against that list by Place ID. A match is still delivered with its Google Maps data, but its website isn't visited (no email lookup), it costs no credit and it doesn't count toward maxResults, so each search still returns up to maxResults new places. A scrape lists roughly one match per place it reserved (placesReserved; a few more when a place's ID only shows up once its listing loads) and leaves any further ones out; while the scrape runs, progress.excludedSkipped counts them. On the scrape, exclusionsApplied is the size of the list it started with (0 without one), excludedCount how many rows matched it (each entry in searches also gives its own as excluded), and resultCount counts every row, matches included. After a cancel, both catch up with the matches the engine finishes while it winds the scrape down, usually within a couple of minutes.

Paid add-ons: Website Analysis and Lead Enrichment

Add-ons are optional extras on the Starter and Pro plans, off unless you ask for them. They cost credits on top of the 1 per place, and only for the places where they deliver something. On the Free plan, asking for one returns 403 with code: addon_plan_required (or 503 addon_unavailable for one that isn't available on any plan right now).

Turn them on per scrape in the create request (Starter and Pro):

curl https://hubertino.com/api/v1/scrapes \
  -H "Authorization: Bearer $HUBERTINO_API_KEY" -H "content-type: application/json" \
  -d '{"categories":["dentist"],"locations":["Austin, TX, United States"],"maxResults":50,
       "seoAudit":true,"findContacts":true}'

The SEO audit checks each place's website. Every place gets a plain-English website_type, so you can spot businesses with no real website. Each own website we could check gets a seo_score from 0 to 10 and up to three seo_issues.

The decision-maker add-on finds up to two current owners, founders, CEOs or other top executives per business on public professional profiles: name, job title, LinkedIn profile and a work email, plus the company's size band. It looks a business up by its own website or LinkedIn page, so a place with neither gets none. The work email is often inferred from the company's email pattern rather than verified, so verify it before you send; it's empty when none is known. It also fills an empty company_linkedin from the company's professional profile, at no charge.

Each add-on's columns come after the 38 (and existing), in results and the export, only on a scrape that ran with it:

What you're charged: each add-on bills the rows you're served that carry its data, per row like the places themselves (a business two of your searches find is two rows, each billed). Misses cost nothing, places on your existing-contacts list never get add-ons, and a failed scrape is refunded in full. The reservation holds the worst case, every place at 1 credit plus each add-on's price, so with a small balance a scrape with add-ons stops at fewer places: read placesReserved for the place cap (without add-ons it equals creditsReserved).

The add-on charge is counted once the scrape has finished writing. Usually that's the moment it's done; after a cancel (or a stalled scrape we stop), the scrape stays addonsPending: true while it winds down, usually a minute or two, with creditsCharged still null and the export not ready yet (409), so poll until addonsPending is gone. Then seoScored is the number of rows billed for a score, contactsFound the number billed for a decision maker, and creditsBreakdown splits the charge into places, seoAudit and findContacts credits, summing to creditsCharged. While the scrape runs, progress.seoScored and progress.contactsFound are live counts, not the bill. When an add-on delivered less than it could, addonNotices.seoAudit or addonNotices.findContacts says why: unavailable (it didn't run, nothing charged), stopped (it stopped partway; you pay only for what it delivered) or partial (some website checks didn't finish before the scrape ended: those rows have no add-on data and cost nothing extra).

If an add-on isn't available, a create that asks for it returns 503 with code: addon_unavailable (retrying won't help; start without it), or addon_degraded while it's paused for a few minutes; nothing is reserved either way. Our integrations start scrapes without add-ons for now; call the API to turn one on. Snake-case fields such as seo_audit or find_contacts are ignored, like any unknown key.

Start a scrape

One scrape runs up to 2,000 searches (categories × locations); split anything larger into several scrapes. Strings are trimmed and unknown keys are ignored. Returns 201 with the created scrape:

{
  "scrape": {
    "id": "6f1c…", "kind": "scrape", "status": "queued",
    "title": "dentist — Austin, TX, United States",
    "categories": ["dentist"], "locations": ["Austin, TX, United States"],
    "maxResults": 50, "country": "us", "enrichLinks": true, "enrichWebsite": true,
    "creditsReserved": 50, "creditsCharged": null, "placesReserved": 50,
    "seoAudit": false, "findContacts": false, "seoScored": null, "contactsFound": null,
    "resultCount": 0,
    "excludedCount": 0, "exclusionsApplied": 0,
    "error": null, "createdAt": "2026-09-24T09:14:03.512Z", "finishedAt": null
  }
}

Don't retry a create blindly after a timeout: there's no idempotency key yet, so a retry can start (and reserve credits for) a second scrape. List your scrapes first.

List scrapes

Your 200 most recent jobs, newest first, as { "scrapes": [...] }. There's no paging or filtering. The list also holds review jobs started in the dashboard (kind: "reviews"). A job's status here is the last one stored; fetch the scrape itself for live status.

Get one scrape

Returns the scrape with live status. status moves from queued to running to done, or to error (with a message in error and every reserved credit refunded). While it's active the response also carries progress, the searches it runs (once the search stage is over) and coverage (filled in when it finishes). There are no webhooks yet: poll every few seconds.

{
  "scrape": {
    "id": "6f1c…", "status": "running", "resultCount": 50,
    "creditsReserved": 50, "creditsCharged": null, "placesReserved": 50,
    "progress": {
      "stage": "emails", "stageLabel": "Collecting emails & socials",
      "pairsDone": 1, "pairsTotal": 1, "found": 50, "extracted": 31,
      "excluded": 0, "updated": 212, "percent": 74
    },
    …
  }
}

Cancel a scrape

Stops the scrape and settles it straight away. You're charged for every new place past the detail stage by then (a _status of extracted, enriched or failed), including places whose website email hunt the cancel cuts short: results already serve those rows in full while the scrape runs. Places on your existing-contacts list (excluded) are never charged. The rest of the reservation is refunded. The scrape comes back done with those rows, or error with every credit refunded when no place had got that far, which is always the case while it's still queued. From then on, results and the export serve only the rows you were charged for plus the scrape's existing-contact rows, which are free, so nothing after error. Paid add-ons are charged for the served places they delivered on, counted once the engine has wound the scrape down (addonsPending until then). Existing contacts the engine finishes while it winds the scrape down are served too, still free: excludedCount and resultCount catch up with them within a couple of minutes, so page the results by count and hasMore. There's no request body.

curl -X POST "https://hubertino.com/api/v1/scrapes/$ID/cancel" \
  -H "Authorization: Bearer $HUBERTINO_API_KEY"

Returns 200 with the scrape, shaped like GET /scrapes/{id}. Cancelling is idempotent: a scrape that has already finished, failed or been cancelled comes back unchanged and nothing is charged again, and one that finished just before your cancel is settled as finished. If the scraping engine can't be reached you get a 503 and nothing changes, so retry.

Fetch results

Paginated. limit defaults to 1,000 and caps at 5,000; offset defaults to 0. Page until hasMore is false. Rows are readable while the scrape is still running: partial is true until it has finished, and updated changes whenever rows do.

{
  "status": "done",
  "partial": false,
  "count": 4820,          // total rows available, not this page
  "updated": 9731,
  "coverage": { "total": 4820, "email": 3102, "phone": 4466, … },
  "columns": ["query", "name", "category", "phone", "email", …],
  "rows": [ { "_status": "enriched", "name": "…", "email": "…", … }, … ],
  "offset": 0,
  "limit": 1000,
  "hasMore": true
}

Every row has every column in columns, null where it has no value, plus a _status of found → extracted → enriched (or failed when the place page couldn't be loaded), so you can tell a fully detailed row from one still being filled in. A place on your existing-contacts list goes from found to excluded instead: its listing is filled in, its website isn't visited, and coverage leaves it out. While a scrape runs you're served at most the places you reserved (placesReserved), and once it has settled, only the places you were charged for, plus those free matches either way (nothing after an error). When a scrape is capped, detailed rows come first. Paging through every row, with the call() helper from the quickstart:

def rows(scrape_id, page_size=1000):
    offset = 0
    while True:
        page = call("GET", f"/scrapes/{scrape_id}/results",
                    params={"limit": page_size, "offset": offset}).json()
        yield from page["rows"]
        if not page["hasMore"] or not page["rows"]:
            return
        offset += len(page["rows"])

async function* rows(id, pageSize = 1000) {
  for (let offset = 0; ; ) {
    const page = await (await call(`/scrapes/${id}/results?limit=${pageSize}&offset=${offset}`)).json();
    yield* page.rows;
    if (!page.hasMore || !page.rows.length) return;
    offset += page.rows.length;
  }
}

Export XLSX or CSV

Returns the file itself, not JSON, named hubertino-<id prefix>.<format>. format is xlsx (the default) or csv. Columns follow the results columns order, without _status. The export only exists once the scrape is done; earlier calls return 409.

curl "https://hubertino.com/api/v1/scrapes/$ID/export?format=csv" \
  -H "Authorization: Bearer $HUBERTINO_API_KEY" -o leads.csv

Limits

A create the API refuses (an invalid body, say) still counts toward the limit, and a 429 carries no Retry-After: wait out the 5-minute window. Reads (status, results, export) aren't rate limited, but a scrape takes minutes, so polling every few seconds is plenty. Your credit balance is the real ceiling on how much one scrape collects.

What the API doesn't do yet

• • No webhooks. Poll GET /scrapes/{id} until the scrape finishes.
• • No delete. You can cancel a scrape over the API, but deleting one is dashboard-only.
• • No credit-balance endpoint. A shortfall shows up as a 402, or as a reservation below the worst case.
• • No review scrapes. Review jobs start in the dashboard; the API can read them but not start them.
• • No server-side filters on results. Filter rows (e.g. only those with an email) on your side.
• • No scoped or read-only keys. An account has one key, and it can spend all the credits.
• • No endpoint for the existing-contacts list. Import, download or clear it in Dashboard → Settings; it applies to every scrape and can't be switched off for one. Existing contacts never get add-ons.

Errors

Every error is JSON, { "error": "…" }, with a human-readable message and a meaningful status code. A refused paid add-on also carries a machine-readable code.

OpenAPI spec

The whole API as an OpenAPI 3.1 document: every endpoint, field, status and error above, plus the full row schema. Import it into an API client or generate a typed client from it. It needs no key, and it includes the paid add-on fields. With an add-on on, creditsCharged counts credits, not rows, and placesReserved is the place cap.

Changelog

Changes an API user would notice, newest first. The dashboard's API page shows the latest ones too.

1. October 7, 2026 · OpenAPI spec 1.1.0

   • • Result rows carry _status plus every column in columns, null when empty: add-on columns used to be missing from rows that had no value for them. Internal keys, such as the listing photo the dashboard shows, are no longer sent.
   • • An unknown path under /api/v1 answers a JSON 404, and exporting a scrape that failed answers 409 “This scrape failed, so there is nothing to export.” instead of “not finished yet”.
   • • OpenAPI spec 1.1.0: request examples with the paid add-ons on, all 11 website_type labels, and corrected notes on country, stages, rate limits and coverage.

2. October 5, 2026

   • • Paid add-ons on the Starter and Pro plans: seoAudit (Website Analysis) labels every place's website for free and scores each own website 0–10 with up to 3 fixes, for 10 credits per site scored; findContacts (Lead Enrichment) adds up to 2 owners or top executives where the business can be matched, for 20 credits per business with one.
   • • New scrape fields placesReserved, seoAudit, findContacts, seoScored, contactsFound, addonPrices, addonsPending, creditsBreakdown and addonNotices, the add-on columns in results and exports, and a machine-readable code on add-on refusals.

3. September 28, 2026

   • • POST /scrapes/{id}/cancel: stop a scrape and pay only for the new places extracted so far.
   • • Your existing-contacts list applies to API scrapes: matches come back with existing: true and _status: "excluded" at no charge, counted in excludedCount, exclusionsApplied and searches[].excluded.

4. September 24, 2026 · OpenAPI spec 1.0.0

   • • The OpenAPI 3.1 spec at /api/v1/openapi.json, for API clients and code generators.