Google Maps Scraper-Dokumentation. Von der Abfrage bis zum Export.

Beginnen Sie mit einer realen Aufgabe.#

1. Erstellen Sie einen Arbeitsbereich und öffnen Sie „Unternehmen entdecken“.
2. Geben Sie eine Abfrage mit dem Standort ein, z. B. „Zahnärzte in Austin, TX“.
3. Wählen Sie Ihr Datensatzlimit und optionale Filter. Filter werden nach dem Abruf angewendet.
4. Überprüfen Sie die maximale Einheitennutzung. Die Anreicherung erhöht das reservierte Limit.
5. Ausführen, Quellen prüfen, Unternehmen auswählen und in einer Liste speichern oder als CSV exportieren.

Anreicherung in eine gespeicherte Liste zurückschreiben.#

Wählen Sie in „Gespeicherte Listen“ Datensätze mit einer Quell-ID aus und autorisieren Sie „Ausgewählte anreichern“ mit dem maximalen Einheitenbudget. „Rückschreiben überprüfen“ öffnet den neuen Stapel; ausstehende Aufgaben bleiben bis zu einer späteren Vorschau übersprungen. Sie können auch einen vorhandenen Detail- oder Anreicherungsstapel aus der Listensymbolleiste auswählen.

Vorschau der angeforderten IDs und Vorher/Nachher-Vergleich erweitern. Leere Felder ausfüllen behält vorhandene Werte bei; ausgewählte Felder ersetzen kopiert nur die nicht leeren Quellfelder. Doppelte, nicht zugeordnete, abgelaufene oder gestoppte Aufgaben in der Übersprungenen Liste prüfen. Die angezeigten Anzahlen geänderter Datensätze und übersprungener Aufgaben vor der Anwendung bestätigen. Ein geänderter Datensatz, eine geänderte Quelle oder eine geänderte Konfiguration erfordert eine neue Vorschau.

Alle berechtigten Aktualisierungen werden gemeinsam übernommen. Phasen, Notizen, Tags, Zuweisungen und benutzerdefinierte Felder bleiben erhalten. Der Verlauf der Stapelverarbeitungs-Rückschreibung zeigt die Originalwerte und die Rückgängigmachung pro Datensatz an; spätere Bearbeitungen verhindern die Wiederherstellung. Die Workspace-Einstellungen steuern die Aktivierung und die Datensatzbegrenzung. Das Zurückschreiben gespeicherter Ergebnisse verwendet keine Rechercheeinheiten und ruft die Datenquelle nicht auf. Nicht aufgelöste Importe verwenden weiterhin einzeln „Abgleichen & Zusammenführen“.

Agenten verwenden preview_batch_merge, apply_reviewed_batch_merge und read_batch_merge_receipt mit denselben Anforderungen an Prüfhash, Bereich und Idempotenz. Schreibberechtigungen dürfen niemals aus Quelldatensätzen abgeleitet werden.

Unternehmens-Homepage prüfen#

Öffnen Website-Auditsoder wählen Sie „Diese Website prüfen“ aus einem gespeicherten Datensatz. Prüfen Sie die normalisierte Homepage, schätzen Sie den Aufwand und autorisieren Sie eine Einheit. Prüfen Sie die abgeschlossene HTTP/HTML-Beobachtung, exportieren Sie sie, erstellen Sie einen Bericht oder richten Sie eine wiederkehrende Überwachung ein. Die Massenrecherche akzeptiert auch eine Website pro Zeile.

Eine Homepage-Prüfung verwendet nicht die Live-Maps-Datenquelle. Sie liest maximal 256 KiB, folgt bis zu fünf sicheren Weiterleitungen und stoppt nach 15 Sekunden. Sie führt kein JavaScript aus und berechnet keinen Ranking-Score. Eine blockierte oder zeitüberschreitende Beobachtung verbraucht dennoch eine Einheit.

{"kind":"website_audit","url":"https://example.com/","limit":1}

REST API#

GET      /api/health
GET      /api/me
GET      /api/v1/usage
POST     /api/v1/estimate
POST     /api/v1/jobs
GET      /api/v1/jobs/{id}
GET      /api/v1/jobs/{id}/results
POST     /api/v1/jobs/{id}/cancel
GET      /api/v1/jobs/{id}/export
GET/POST /api/v1/lists
GET/POST /api/v1/lists/{id}/items
PATCH    /api/v1/lists/{id}/items/{business_id}
GET/POST /api/monitors
PATCH    /api/monitors/{id}
POST     /mcp

Einen begrenzten Auftrag erstellen#

curl -X POST https://mapsscraper.dev/api/v1/jobs \
  -H "Authorization: Bearer $MAPSSCRAPER_API_KEY" \
  -H "Idempotency-Key: dentists-austin-tx-001" \
  -H "X-Max-Units: 1" \
  -H "Content-Type: application/json" \
  -d '{"kind":"search","query":"Dentists in Austin, TX","limit":20,"region":"us"}'

HTTP/1.1 202 Accepted
{"id":"6f1c2b3a-0000-4000-8000-000000000000","status":"queued","reserved":1}

Wiederholen Sie dieselbe Geschäftsoperation mit demselben Idempotenzschlüssel. Eine geänderte Anfrage mit diesem Schlüssel gibt 409 zurück. Aufträge durchlaufen die Status „In Warteschlange“, „Wird ausgeführt“, „Abgeschlossen“, „Teilweise“, „Fehlgeschlagen“, „Abgebrochen“ oder „Unsicher“. Eine unsichere Anfrage an die Datenquelle erfordert einen Abgleich statt einer automatischen kostenpflichtigen Wiederholung.

Die meisten Aufgaben verbrauchen eine Einheit. Kontaktanreicherung bei einer Suche oder einem Ranking-Snapshot reserviert eine weitere Einheit pro angefordertem Datensatz und berechnet nur gelieferte Datensätze. Unternehmensdetails verbrauchen eine Einheit, mit Kontakten zwei; Anreicherung verbraucht zwei. Setzen Sie X-Max-Units mindestens auf die Schätzung.

Schätzen Sie in Python die Aufgabe ab, erstellen Sie den Job mit der Bibliothek requests, warten Sie auf einen Endstatus und lesen Sie die gespeicherten Ergebnisse:

import os
import time
import uuid

import requests

API = "https://mapsscraper.dev/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['MAPSSCRAPER_API_KEY']}"}
task = {"kind": "search", "query": "Dentists in Austin, TX", "limit": 20, "region": "us"}

# An estimate reserves nothing.
units = requests.post(f"{API}/estimate", json=task, headers=HEADERS, timeout=30).json()["units"]

# Keep the key: a retry of the same task must send it again.
key = str(uuid.uuid4())
job = requests.post(
    f"{API}/jobs",
    json=task,
    headers={**HEADERS, "Idempotency-Key": key, "X-Max-Units": str(units)},
    timeout=30,
)
job.raise_for_status()
job_id = job.json()["id"]

while True:
    status = requests.get(f"{API}/jobs/{job_id}", headers=HEADERS, timeout=30).json()["status"]
    if status not in ("queued", "running"):
        break
    time.sleep(5)

if status in ("completed", "partial"):
    page = requests.get(
        f"{API}/jobs/{job_id}/results",
        params={"offset": 0, "limit": 100},
        headers=HEADERS,
        timeout=30,
    ).json()
    for business in page["items"]:  # follow page["next_offset"] for more
        print(business.get("name"), business.get("phone_number"), business.get("website"))

Häufige Fehler#

Jede Fehlerantwort ist JSON mit einem stabilen Code, manche enthalten zusätzliche Details. Verzweigen Sie anhand des Codes; mehrere Codes können denselben HTTP-Status haben.

{"error":{"code":"TASK_BUDGET_TOO_LOW","details":{"needed":11,"max_units":5}}}

KI-Suchantwort prüfen#

Die Sichtbarkeit der KI-Suche behält eine Google AI Overview-Beobachtung bei: die Frage, das Land, die Sprache, optional die Stadtpräferenz, den Antworttext und sichere Zitationslinks. Fügen Sie bis zu fünf Markennamen und Domains hinzu, überprüfen Sie das Maximum von einer Einheit und autorisieren Sie die Aufgabe anschließend explizit. Ihr Administrator muss den Arbeitsbereich aktivieren und eine lizenzierte Quelle verbinden.

Überprüfen Sie den Verlauf oder exportieren Sie Nachweise ohne erneuten Aufruf der Datenquelle. Vergleichen Sie Baselines nur, wenn die Suchanfrage, das Gebietsschema und die Ziele übereinstimmen. Eine fehlende Übersicht bedeutet unbekannte Sichtbarkeit; die Zitationsreihenfolge entspricht nicht dem Suchrang. Unvollständige Nachweise können keine negative Übereinstimmung herstellen. Multi-Engine-Tracking ist nicht verfügbar.

Um einen festen Satz von Fragen zu verfolgen, kann ein verifizierter Eigentümer oder Administrator eine wiederkehrende Serie planen: bis zu 10 Prompts, alle 24 bis 720 Stunden, für höchstens 30 Beobachtungen innerhalb von 90 Tagen. Prüfen Sie die maximalen Einheiten für die gesamte Serie und bestätigen Sie sie ausdrücklich. Eine Serie pausiert, wenn sich ihre Autorisierung oder Konfiguration ändert oder eine Beobachtung fehlschlägt oder unsicher ist; das Fortsetzen erfordert eine neue Vorschau.

Sichtbarkeit der OpenAI-Suche

Suchen Sie einen Bereich und rufen Sie weitere Seiten ab#

Wählen Sie in Explore eine Textposition, eine Punktpräferenz, einen Radius oder einen Begrenzungsrahmen. Die Punktpräferenz ist keine Begrenzung. Ergebnisse mit Radius und Rahmen schließen außerhalb oder unbrauchbar liegende Koordinaten aus und behalten die Ausschlussanzahl bei. Die Arbeitsbereichseinstellungen steuern Radius und Rahmengröße. Teilen Sie einen Bereich, der die Antimeridiane schneidet; eine begrenzte Stichprobe beweist keine vollständige Abdeckung.

Rezensionen und Fotometadaten erlauben bis zu 100 Datensätze pro Quellseite. Öffnen Sie nach Abschluss eines Ergebnisses die Ergebnisseiten in „Erkunden“ oder im Aufgabenverlauf. Überprüfen Sie die genauen Quelloptionen, aktivieren Sie das Kontrollkästchen für die Autorisierung und legen Sie ein Budget für den Abruf einer weiteren Seite fest. Sortierung, Sprache, Übersetzung und Filter bleiben für die Kette unverändert. Fehlende oder wiederholte Cursor, Ablauf, konfigurierte Limits und unsichere Ergebnisse stoppen die Fortsetzung.

Das Lesen der nächsten gespeicherten Datensatzseite und das Exportieren einer vorhandenen Seite rufen die Datenquelle nicht auf. Das Abrufen einer neuen Quellseite ist ein separater kostenpflichtiger Vorgang. Lesen Sie für SDK und Agenten die Fortsetzungsvorschau und übermitteln Sie dann die genaue Aufgabe mit einem stabilen Idempotenzschlüssel und einem expliziten Budget. Planen oder stapeln Sie keine Cursorfortsetzungen.

Recherche innerhalb eines Polygons planen#

Wählen Sie in „Erkunden“ die Option „Polygonbegrenzung“ für eine Anfrage mit begrenztem Rechteck und exakter Polygonfilterung. Wählen Sie in der Massenrecherche die Option „Polygonbegrenzung“, um ein GeoJSON-Polygon zu importieren oder einzufügen, seine Form zu überprüfen und Zeilen, Spalten und Datensätze pro Zelle auszuwählen. Die schematische Darstellung zeigt Koordinaten und geplante Zellen; es handelt sich nicht um eine Straßenkarte.

Positionen verwenden [Längengrad, Breitengrad]. Schließen Sie jeden Ring, indem Sie seine erste Position wiederholen; der erste Ring ist der äußere Rand, und bis zu vier zusätzliche Ringe sind ausgeschlossene Löcher. Selbstüberschneidungen, sich berührende oder überlappende Löcher und Antimeridiankreuzungen werden abgelehnt. Verwenden Sie separate Polygone über die Datumsgrenze hinweg. Arbeitsbereichseinstellungen begrenzen Positionen, Spannweite und geplante Zellen.

„Zellen überprüfen & Gesamtbudget“ ruft die Datenquelle nicht auf. Überprüfen Sie jede beibehaltene Zelle, legen Sie die maximale Anzahl an Einheiten fest und bestätigen Sie explizit vor der Ausführung. Alle Aufgaben werden zusammen reserviert oder keine wird zugelassen. Belege bewahren den ursprünglichen Plan und die Konfigurationsversion. Ein Quellenergebnis wird sowohl nach Polygon als auch nach Zelle gefiltert; gemeinsame Kanten können zu doppelten Unternehmenseinträgen führen. Die angeforderte Datensatzanzahl ist ein Maximalwert, keine vollständige Erfassung.

Agenten verwenden preview_polygon_plan, gefolgt von create_reviewed_polygon_batch, mit exakt demselben Kompaktplan, Vorschau-Hash, Bestätigungs-, Stabilitätsschlüssel- und Gesamtbudget. Verwenden Sie die vorhandenen Steuerelemente für Batchverlauf, Stornierung und Ergebnis-/Export pro Vorgang. Unsichere Ergebnisse werden niemals automatisch erneut gescannt.

Exportieren Sie die gespeicherte Seitenkette.#

Öffnen Sie auf den Ergebnisseiten „Mehrseitige Exporte“ und wählen Sie „Vollständigen Export der Prüfkette prüfen“. Überprüfen Sie die Seiten anhand der ausgewählten Aufgabe, wählen Sie, ob der erste Datensatz für jede exakte ID oder alle Datensätze beibehalten werden sollen, und bestätigen Sie anschließend den privaten Export. Dabei werden keine neuen Daten abgerufen oder Rechercheeinheiten verwendet. Exporte werden auch in den Datensteuerungen mit Fortschritts-, Stornierungs- und Integritätsbestätigungen angezeigt.

Nach Abschluss des Vorgangs können Sie JSONL, JSON, CSV oder Excel herunterladen. Doppelte IDs mit geändertem Inhalt werden als Konflikte gewertet; der erste Datensatz bleibt erhalten. Datensätze ohne IDs bleiben separat. Jede Quellseite verfügt über einen eigenen verifizierten JSONL-Abschnitt, sodass eine fehlgeschlagene Übertragung abschnittsweise fortgesetzt werden kann. Excel unterstützt bis zu 5 MB an gespeicherten Abschnitten; größere Exporte verwenden die Streaming-Formate. CSV speichert zusätzliche Spalten in extra_fields_json.

Eigentümer und Administratoren konfigurieren in den Einstellungen tägliche Anfragen, ausstehende Exporte, Seiten- und Quellbyte-Limits sowie die Aufbewahrungsdauer. Es gilt immer das früheste Ablaufdatum der Quelle. Behalten Sie die vollständige Markierung beim Konsum von JSON oder JSONL bei und überprüfen Sie heruntergeladene Teile anhand ihrer SHA-256-Prüfbelege. Eine eingefrorene Kette ist eine gespeicherte Stichprobe, kein Nachweis für eine vollständige Marktabdeckung.

Analysieren Sie Rezensionsthemen mit zitierten Belegen.#

Beginnen Sie mit einem Rezensionsstatistikbericht unter „Berichte“. Ein Eigentümer oder Administrator aktiviert die KI-Rezensionsanalyse unter „Einstellungen & Nutzung“ und legt tägliche Versuche, ausstehende Aufgaben, die Anzahl der Auszüge und die Lebensdauer der Warteschlange fest. Diese Funktion ist standardmäßig deaktiviert.

Wählen Sie „Eingabe der Analyse prüfen“, um die genauen Auszüge und das Modell zu überprüfen, bevor Sie eine Generierung autorisieren. Bis zu 40 verschiedene Auszüge und 10 KB Auszugstext werden in Berichtsreihenfolge ausgewählt. Eine Generierung hat eigene Obergrenzen für die KI-Analyse und verwendet keine Maps-Wallet-Einheiten. Fehlgeschlagene oder abgebrochene Versuche werden weiterhin gezählt.

Jedes gespeicherte Thema enthält geprüfte Zitate und Quellenangaben. Die Zählungen basieren auf eindeutigen zitierten Auszügen, Themen können sich überschneiden und KI-Interpretationen können fehlerhaft sein. Das Ergebnis wird als separater Bericht geöffnet: Prüfen Sie ihn unter Berichte und wählen Sie dann aus, was Sie teilen oder als PDF exportieren möchten. Wenn Sie die Spalte „Rezensionsauszug“ ausblenden, wird auch die KI-Analyse ausgeblendet.

Auszüge ohne unterstützte Kundenerfahrung können eine Bestätigung mit unzureichenden Nachweisen ohne Bericht zurückgeben. Der Versuch wird dennoch auf die Limits angerechnet. Prüfen Sie die Eingabe, bevor Sie eine andere Analyse autorisieren. Ein Funktions-Upgrade stoppt ältere Genehmigungen in der Warteschlange vor der Auswertung; prüfen Sie eine neue Vorschau. Bestehende Berichte behalten ihr ursprüngliches Modell und ihre ursprüngliche Prompt-Version.

Belege zeigen Ergebnisse in der Warteschlange, laufende, abgeschlossene, fehlgeschlagene, unsichere, abgebrochene oder abgelaufene Ergebnisse an. Ein Abbruch verhindert die Berichtserstellung, obwohl eine ausgelöste Analyse weiterhin auf die Limits angerechnet wird. Unsichere Aufrufe werden nie automatisch wiederholt. API, SDK und MCP verwenden denselben Vorschau-Hash, dieselbe explizite Bestätigung und denselben Idempotenzschlüssel.

Kundenbericht erstellen und freigeben#

Erstellen Sie in „Berichte“ einen Bericht aus abgeschlossenen Recherchen. Bearbeiten Sie Titel, Marke, Abschnittsreihenfolge und Spalten für Nachweise und speichern Sie die Präsentation. Die Workspace-Einstellungen bieten Standard-Markenfarben, ein eingebettetes PNG-Logo, die Website des Herausgebers und eine Fußzeile. Vorhandene gespeicherte Präsentationen ändern sich nur, wenn Sie sie bearbeiten oder die Workspace-Standardeinstellungen anwenden.

Der freigegebene geprüfte Bericht zeigt die exakte öffentliche Projektion. Nicht ausgewählte Nachweisfelder und ausgeblendete Abschnitte werden vom gespeicherten Snapshot ausgeschlossen. Quellabfragen sind standardmäßig privat; die Methodik bleibt sichtbar. Wählen Sie alle Empfänger mit dem Link oder bis zu 25 verifizierte E-Mail-Konten aus, legen Sie ein Ablaufdatum fest und bestätigen Sie explizit Inhalt und Zielgruppe. Sie können auch ein Freigabepasswort festlegen und dieses separat vom Link senden. Die Workspace-Richtlinie kann Passwörter für jede Ergebnis-/Berichtsfreigabe vorschreiben. Es wird keine Einladung oder E-Mail versendet.

Kopieren Sie den vollständigen Link einmal. Das Geheimnis bleibt in seinem Fragment erhalten und wird nicht im Browserspeicher abgelegt. Ein Empfänger mit eingeschränktem Zugriff meldet sich mit einem verifizierten Konto an, öffnet den ursprünglichen Link und gibt das Freigabepasswort ein, wenn er dazu aufgefordert wird. Passwörter können nicht wiederhergestellt werden; bei Verlust eines Passworts muss dieses widerrufen und ein Ersatzlink erstellt werden. Die Gültigkeitsdauer ist durch die Aufbewahrungsfrist der Quelle begrenzt. Datenkontrollen können zukünftigen Zugriff verhindern; gelöschte Berichte, abgelaufene Quellen und pausierte Arbeitsbereiche verhindern neue Lesevorgänge. Heruntergeladene Kopien können nicht wiederhergestellt werden. JSON und die Browserfunktionen „PDF drucken/speichern“ verwenden die angezeigte Darstellung. „Gespeichertes PDF generieren“ erstellt eine private Datei aus der gespeicherten Version im A4- oder Letter-Format und im Hoch- oder Querformat. Fertige Dateien können einer passenden, geprüften Freigabe hinzugefügt werden und übernehmen deren Zugriffsregeln.

Agenten verwenden preview_report_delivery, update_report_presentation, create_reviewed_report_share, list_report_shares und revoke_report_share. Für die Veröffentlichung sind die geprüfte Version, der Snapshot-Hash, ein stabiler Idempotenzschlüssel und eine explizite Freigabeberechtigung erforderlich. Externe Forschungstexte können diese Berechtigung nicht erteilen.

Erstellen einer gespeicherten PDF-Datei#

Speichern Sie die Präsentation, wählen Sie Papier und Ausrichtung beim PDF-Export und generieren Sie anschließend. Der Verlauf zeigt Anfragen in der Warteschlange, Rendering-Prozesse, abgeschlossene und abgebrochene Anfragen mit Download- oder Abbruchoptionen an. Die Arbeitsbereichseinstellungen steuern die Aktivierung, tägliche Anfragen, ausstehende Anfragen und die Aufbewahrungsdauer. Dateien verfallen mit ihren Quellen oder nach Ablauf der konfigurierten Aufbewahrungsfrist, je nachdem, was zuerst eintritt. Das Rendering verbraucht keine Forschungseinheiten. Fehlgeschlagene oder unsichere Renderings erfordern eine neue explizite Anfrage; sie werden nicht automatisch wiederholt.

Agenten verwenden generate_report_pdf mit der geprüften Version, dem Snapshot-Hash, confirmed_render und einem Idempotenzschlüssel. list_report_pdfs und get_report_pdf prüfen Empfangsbestätigungen; cancel_report_pdf stoppt die ausstehende Veröffentlichung. Generieren erstellt keine Freigabe und sendet keine Nachricht. Routen für private Downloads und Empfängeranhänge sind in OpenAPI verfügbar.

Empfangen Sie signierte Auftragsbelege.#

Fügen Sie in den Integrationen einen öffentlichen HTTPS-Empfänger hinzu. Speichern Sie dessen einmaliges Signaturgeheimnis sicher, aktivieren Sie die Zustellung unter Einstellungen & Nutzung und aktivieren Sie anschließend explizit das Ziel. Wählen Sie abgeschlossene, teilweise abgeschlossene, fehlgeschlagene, unsichere oder abgebrochene Jobereignisse aus. Tests senden lediglich ein Testflag und Metadaten.

Jede Zustellung enthält zwei Signaturverfahren. Bei Standard Webhooks besteht webhook-signature aus v1, gefolgt vom base64-kodierten HMAC-SHA256 über webhook-id, webhook-timestamp und den exakten Roh-Body der Anfrage, jeweils durch Punkte verbunden. Der Schlüssel ist die base64-Dekodierung des Texts nach whsec_.

Das ursprüngliche Verfahren bleibt unverändert: X-LocalOS-Signature ist v1= gefolgt vom hexadezimalen HMAC-SHA256 über X-LocalOS-Timestamp, einen Punkt und den Roh-Body, mit dem gesamten whsec_-Geheimnis als Text als Schlüssel. Wählen Sie das Geheimnis anhand von X-LocalOS-Key-ID.

Verlangen Sie bei beiden Verfahren einen Zeitstempel innerhalb von fünf Minuten und vergleichen Sie Signaturen in konstanter Zeit. Die Ereignis-ID in webhook-id und X-LocalOS-Event-ID bleibt über Wiederholungen gleich: Speichern Sie sie eindeutig, bevor Sie Änderungen anwenden, und bestätigen Sie Duplikate mit einer 2xx-Antwort.

Standard-Webhooks-Signatur in Node.js prüfen:

// Verifies a webhook delivery with Web Crypto only, so it runs on
// Node.js 20+, Deno, Bun and Cloudflare Workers without dependencies.
//   const event = await verifyWebhook({ secret, headers, body });
// secret: "whsec_..." or, while rotating, ["whsec_new", "whsec_old"].
// headers: a Headers object or a plain map such as req.headers.
// body: the raw body as text or bytes, before any JSON parsing.
// Returns the parsed event. Otherwise throws an error whose code says
// why the delivery must not be trusted.
export class WebhookVerificationError extends Error {
  constructor(code) {
    super(code);
    this.name = "WebhookVerificationError";
    this.code = code;
  }
}

const encoder = new TextEncoder();

function header(headers, name) {
  if (typeof headers.get === "function") {
    return headers.get(name) ?? undefined;
  }
  for (const [key, value] of Object.entries(headers)) {
    if (key.toLowerCase() === name) {
      return Array.isArray(value) ? value[0] : value;
    }
  }
  return undefined;
}

function base64(value) {
  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(value) || value.length % 4) {
    return null;
  }
  try {
    return Uint8Array.from(atob(value), (c) => c.charCodeAt(0));
  } catch {
    return null;
  }
}

// Checks every byte, so the time taken does not reveal a mismatch.
function sameBytes(a, b) {
  if (a.length !== b.length) return false;
  let difference = 0;
  for (let i = 0; i < a.length; i++) difference |= a[i] ^ b[i];
  return difference === 0;
}

export async function verifyWebhook({
  secret,
  headers,
  body,
  toleranceSeconds = 300,
}) {
  if (!Number.isFinite(toleranceSeconds) || toleranceSeconds < 0) {
    throw new RangeError("toleranceSeconds must be 0 or more");
  }
  const fail = (code) => new WebhookVerificationError(code);
  const keys = [secret]
    .flat()
    .map((value) =>
      typeof value === "string" ? base64(value.replace(/^whsec_/, "")) : null,
    );
  if (!keys.length || keys.some((key) => !key?.length)) {
    throw fail("WEBHOOK_SECRET_INVALID");
  }
  const id = header(headers, "webhook-id");
  const timestamp = header(headers, "webhook-timestamp");
  const signatures = header(headers, "webhook-signature");
  if (!id || !timestamp || !signatures) {
    throw fail("WEBHOOK_HEADER_MISSING");
  }
  if (!/^\d{1,12}$/.test(timestamp)) {
    throw fail("WEBHOOK_TIMESTAMP_INVALID");
  }
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSeconds) {
    throw fail("WEBHOOK_TIMESTAMP_OUT_OF_RANGE");
  }
  const subtle = globalThis.crypto?.subtle;
  if (!subtle) throw fail("WEBHOOK_CRYPTO_UNAVAILABLE");
  const raw =
    typeof body === "string" ? encoder.encode(body) : new Uint8Array(body);
  const prefix = encoder.encode(`${id}.${timestamp}.`);
  const signed = new Uint8Array(prefix.length + raw.length);
  signed.set(prefix);
  signed.set(raw, prefix.length);
  const expected = await Promise.all(
    keys.map(async (key) => {
      const hmac = await subtle.importKey(
        "raw",
        key,
        { name: "HMAC", hash: "SHA-256" },
        false,
        ["sign"],
      );
      return new Uint8Array(await subtle.sign("HMAC", hmac, signed));
    }),
  );
  // Any listed v1 signature may match; at most 16 are checked.
  const verified = signatures
    .split(" ")
    .filter(Boolean)
    .slice(0, 16)
    .some((entry) => {
      const [version, value] = entry.split(",", 2);
      const given = version === "v1" && value ? base64(value) : null;
      return given !== null && expected.some((d) => sameBytes(given, d));
    });
  if (!verified) throw fail("WEBHOOK_SIGNATURE_INVALID");
  try {
    return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(raw));
  } catch {
    throw fail("WEBHOOK_PAYLOAD_INVALID");
  }
}

Die Zustellung erfolgt mindestens einmal. Netzwerkfehler, Zeitüberschreitungen und jede Antwort außerhalb von 2xx werden wiederholt, auch Weiterleitungen, denen nie gefolgt wird. Bis zu acht Versuche verteilen sich auf etwa 28 Stunden: nach 5 Sekunden, 5 Minuten, 30 Minuten, 2 Stunden, 5 Stunden, dann zweimal nach 10 Stunden, oder später, wenn der Empfänger Retry-After sendet (bis zu einem Tag). Eine 410-Gone-Antwort pausiert das Ziel und bricht seine ausstehenden Zustellungen ab, bis Sie es fortsetzen. Versuche und Fehler erscheinen unter Integrationen. Das Pausieren oder Entfernen eines Ziels bricht ausstehende Belege ab; bereits zugelassene Anfragen können innerhalb von zehn Sekunden abgeschlossen werden. Gespeicherte Zustellbelege enthalten keine Unternehmensdatensätze, Suchbegriffe, Kontozugangsdaten oder Antwortinhalte des Empfängers.

Ergebnisse an Google Tabellen, Zapier, Make oder n8n senden#

const crypto = require("crypto");
const { body, id, timestamp, signature, secret } = inputData;
const fresh =
  /^\d+$/.test(timestamp || "") &&
  Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300;
const key = Buffer.from(
  String(secret).replace(/^whsec_/, ""),
  "base64",
);
const expected = crypto
  .createHmac("sha256", key)
  .update(`${id}.${timestamp}.${body}`)
  .digest();
const signed = String(signature || "")
  .split(" ")
  .some((entry) => {
    const [version, value = ""] = entry.split(",");
    const given = Buffer.from(value, "base64");
    return (
      version === "v1" &&
      given.length === expected.length &&
      crypto.timingSafeEqual(given, expected)
    );
  });
const valid = Boolean(id) && fresh && signed;
if (!valid) return { valid };
return { valid, job_id: JSON.parse(body).data.job_id };

const API = "https://mapsscraper.dev/api/v1";

function getJson(path) {
  const key = PropertiesService.getScriptProperties()
    .getProperty("MAPSSCRAPER_API_KEY");
  if (!key) throw new Error("Add the MAPSSCRAPER_API_KEY script property.");
  const response = UrlFetchApp.fetch(API + path, {
    headers: { Authorization: "Bearer " + key },
    muteHttpExceptions: true,
  });
  const status = response.getResponseCode();
  const text = response.getContentText();
  if (status !== 200) {
    throw new Error("HTTP " + status + ": " + text.slice(0, 200));
  }
  return JSON.parse(text);
}

// Text that starts with =, +, - or @ gets an apostrophe,
// so Sheets keeps it as text instead of running a formula.
function cell(value) {
  if (value === null || value === undefined) return "";
  if (typeof value === "object") value = JSON.stringify(value);
  const formula = typeof value === "string" && /^[=+\-@]/.test(value);
  return formula ? "'" + value : value;
}

function importLatestSearch() {
  const jobs = getJson("/jobs?page_size=25&kind=search").items;
  const job = jobs.find(
    (item) => item.status === "completed" || item.status === "partial",
  );
  if (!job) return;
  const path = "/jobs/" + job.id + "/export?format=json";
  const rows = getJson(path).items || [];
  if (!rows.length) return;
  const columns = [];
  rows.forEach((row) => Object.keys(row).forEach((name) => {
    if (!columns.includes(name)) columns.push(name);
  }));
  const values = [columns].concat(
    rows.map((row) => columns.map((name) => cell(row[name]))),
  );
  const book = SpreadsheetApp.getActive();
  const sheet =
    book.getSheetByName("MapsScraper") || book.insertSheet("MapsScraper");
  sheet.clearContents();
  sheet.getRange(1, 1, values.length, columns.length).setValues(values);
}

Wichtige Abgrenzungen#

Fehlende Website bedeutet, dass die Datenquelle keine Website geliefert hat. Dies beweist nicht, dass ein Unternehmen keine Website besitzt. Ranking-Snapshots zeigen die Ergebnisreihenfolge einer Datenquelle, nicht die vollständige lokale SEO-Übersicht. Die Rezensionserfassung ist kein KI-generierter Stimmungsbericht. Fotos sind Metadaten, keine lizenzierten Bild-Downloads. Wiederkehrende Suchen speichern Snapshots, vergleichen stabile Identitäten und erstellen Benachrichtigungen im Workspace-Posteingang. Signierte Webhook-Empfangsbestätigungen sind optional und enthalten nur Aufgabenmetadaten; die CRM-spezifische Feldsynchronisierung bleibt separat.