Kunden-API: Suche, Anreicherung und Export

Authentifizierung und Limits

Erstellen Sie einen Schlüssel in den API-Schlüsseleinstellungen. Das Geheimnis wird nur einmal angezeigt. Verwenden Sie leads:read für Standorte, Status, Ergebnisse und Exporte; leads:write für die Aufgabenerstellung und Aktionen. Ein Workflow, der beides tut, benötigt beide Bereiche. Alte Schlüssel erhalten nicht automatisch Bereiche.

Senden Sie Authorization: Bearer sk_YOUR_KEY. Bewahren Sie das Geheimnis in einem Credential-Store auf, niemals in einem öffentlichen Workflow oder einer URL. Die Kontoisolierung bleibt durchgesetzt. Die Produktions-D1-API erlaubt bis zu 60 Anfragen pro Minute pro Konto und erfordert mindestens 200 ms zwischen Anfragen. Bis zu drei aktive Such-/Kampagnen-/Anreicherungsaufgaben teilen sich das Parallelitätsbudget des Kontos.

Jede Aufgabenerstellung benötigt einen Idempotency-Key mit 8–100 Buchstaben, Ziffern, Unterstrichen oder Bindestrichen. Wiederholen Sie eine unveränderte Anfrage mit demselben Schlüssel. Verwenden Sie einen neuen Schlüssel für eine neue Aufgabe. Erfolg gibt HTTP 202 zurück, nicht abgeschlossene Daten.

Einen unterstützten Standort ermitteln

curl "https://ownerclue.com/api/v1/leads/locations?country=US&type=City&q=Phoenix"   -H "Authorization: Bearer $OWNERCLUE_API_KEY"

Verwenden Sie einen zurückgegebenen Code; erfinden Sie keinen locationCode. Registrierte Ländercodes umfassen US, CA, GB (Vereinigtes Königreich), AU, IE, NZ, SG, DE, FR, ES, IT, NL, MX, BR, PT, AT, CH, BE, ZA und AE (20 Länder). Jedes Land muss aktiviert und für das Konto verfügbar sein. GET /api/v1/leads/countries gibt das Array der verfügbaren Codes zurück; fügen Sie ?metadata=true für Ländernamen, Sprachen und unterstützte Standorttypen hinzu. Der Workspace zeigt dieselben verfügbaren Optionen. Englisch (en) wird in diesen Ländern unterstützt; Kanada unterstützt auch fr. Die lokalen Suchsprachen sind de für Deutschland und Österreich, fr für Frankreich, es für Spanien und Mexiko, it für Italien, nl für die Niederlande und pt für Brasilien und Portugal. Die Schweiz unterstützt de/fr/it/en und Belgien unterstützt nl/fr/de/en. Südafrika und die VAE unterstützen derzeit englische Suchen; arabische und andere Suchanfragen in lokalen Sprachen sind noch nicht aktiviert. Die Stichwortsuche in lokaler Sprache ist unabhängig von der exakten Kategoriezuordnung verfügbar, die eine länderspezifische und sprachspezifische Validierung erfordert. Die Länderverfügbarkeit belegt keine Kontaktqualität.

Standorte können nach Typ, level=region oder level=city und parentCode eingegrenzt werden. level=city durchsucht die Unterebenen einer ausgewählten Region, einschließlich Städten unter Zwischen-Landkreisen oder Bezirken. Es umfasst auch unterstützte lokale Gebiete wie britische Boroughs und Singapurer Nachbarschaften. Für Singapur liefert type=Country einen direkt durchsuchbaren Ländercode; eine Regionsauswahl ist optional.

Das Verzeichnis gibt ein Array innerhalb von data zurück, kein paginiertes Job-Envelope. Verwenden Sie limit=1–100 (Standard 50) und offset=0, erhöhen Sie dann offset um die zurückgegebene Länge; stoppen Sie, wenn eine Seite weniger Zeilen als limit enthält. Beispiel: /api/v1/leads/locations?country=GB&level=city&limit=50&offset=50. Ersetzen Sie den Ursprung in den Beispielen durch den öffentlichen App-Ursprung, den Sie verwenden.

Eine Suche erstellen und dann abfragen

{
  "keyword": "plumber",
  "locationCode": 123456,
  "languageCode": "en",
  "depth": 20
}

Senden Sie diesen Body per POST an /api/v1/leads/searches mit beiden Headern. Der obige Standortcode ist ein Platzhalter. Eine erfolgreiche Antwort hat code: 0 und data.id. Rufen Sie GET /api/v1/leads/searches/{id} auf, bis data.status completed ist. queued/running erfordern eine weitere Abfrage; failed erfordert die Prüfung des Fehlers. Exportieren Sie keine unvollständige Aufgabe.

Routen

Methode und Pfad unter /api/v1/leads	Zweck
GET /countries	Verfügbare Ländercodes; metadata=true enthält Namen, Sprachen und Standorttypen
GET /locations	Unterstütztes Standortverzeichnis; country, q, type, level, parentCode, limit, offset
GET /searches, /campaigns, /enrichments	Eigene Jobs auflisten
POST /searches	keyword, locationCode, languageCode, depth; optional exactCategory
POST /campaigns/preview	Vorschau ausgewählter Standortcodes und geschätzter maximaler Leads
POST /campaigns	keyword, locations (Codes), languageCode, depth, maxLeads
POST /enrichments	rows: [{domain, name?}] oder CSV-String; höchstens 1,000 Zeilen
GET /searches/{id}, /campaigns/{id}, /enrichments/{id}	Status und Aufgabendetails
GET /…/{id}/results?limit=100&cursor=…	Ergebnisse und nextCursor
GET /…/{id}/export?format=full	CSV nach Abschluss
POST /campaigns/{id}/pause, /resume, /stop	Kampagnensteuerung
POST /enrichments/{id}/resume	Eine pausierte Anreicherung fortsetzen

Die Suchtiefe ist 1–700. Die Kampagnentiefe akzeptiert 20, 50, 100, 300, 500 oder 700; wählen Sie 1–100 Standortcodes und prüfen Sie die erweiterten Suchstandorte vor der Erstellung in der Vorschau. Regionen werden in unterstützte lokale Suchknoten erweitert; Singapurs Länderwurzel bleibt ein durchsuchbarer Standort. Der Multi-City-Leitfaden erläutert Abbruch und Deduplizierung.

Paginierung und Filter

Job-Listen und Ergebnisse legen items und nextCursor innerhalb von data ab. Halten Sie limit über alle Seiten konstant, übergeben Sie den zurückgegebenen cursor unverändert und stoppen Sie, wenn nextCursor null ist. Ergebnisse können sich während der Verarbeitung verschieben, da die Paginierung derzeit Offsets verwendet; lesen Sie die finalen Daten nach Abschluss. Standorte sind eine Ausnahme mit einem einfachen Array.

Maps-Ergebnisse und Exporte teilen die Filter q, email=true, owner=true, websiteStatus, signal, phoneType und includeExcluded=true. Die unterstützten Signale sind no_website, website_unreachable, booking_not_found und reviews_below_20. Exportformate sind basic, full, gohighlevel, instantly und 1cw. Anreicherungsergebnisse liefern Zeilenergebnisse statt Maps-Lead-Filter.

Fehler und Wiederholungsrichtlinie

HTTP-Status	Aktion
202	data.id speichern und abfragen
400	Eingabe, Idempotenzschlüssel, Standort, Guthaben oder Nebenläufigkeitsbedingung korrigieren; message prüfen
401	Bearer-Header angeben
403	Schlüsselgültigkeit, Scopes, Eigentum und Exportverfügbarkeit prüfen
404	Aufgaben-ID und Konto prüfen
429	Vor dem erneuten Versuch zurückhalten
503	Funktion nicht verfügbar; erst nach Änderung ihrer Verfügbarkeit erneut versuchen

JSON-Antworten verwenden {code, message, data}; CSV-Exporte liefern text/csv. Erfassen Sie sowohl HTTP-Status als auch code. Derzeit ist kein Webhook für Aufgabenabschluss verfügbar; verwenden Sie den n8n-Polling-Leitfaden. Abrechnungsregeln gelten gleichermaßen für API- und Workspace-Aufgaben.

Bewertungen, Rezensionen und Listen

Oberfläche, API-Ergebnisse und CSV-Exporte unterstützen minRating/maxRating (0–5) und minReviews/maxReviews (nichtnegative ganze Zahlen). Grenzen eingeschlossen; fehlende Werte sind nicht null. Beispiel: ?minRating=3.5&maxRating=4.5&minReviews=10&maxReviews=50. Ungültige oder umgekehrte Bereiche werden abgelehnt. Vollständige CSV enthält jetzt business_id und belegte Buchungs-/Bestelllinks. Listen vergleichen.