API#

Übersicht#

Die Webmetic Data Hub API bietet einen sicheren und effizienten Weg, um auf Besuchersitzungsdaten für Ihre Domains zuzugreifen. Diese API ermöglicht es Ihnen, detaillierte Informationen über Unternehmen, die Ihre Website besuchen, deren Sitzungsdaten und Benutzerinteraktionen abzurufen. Die API wurde unter Berücksichtigung von Datenschutz und Leistung entwickelt, um sicherzustellen, dass Sie auf die benötigten Daten zugreifen können, während die Einhaltung der Datenschutzbestimmungen gewährleistet wird.

Basis-URL#

Zu finden im Dashboard unter: API Details

Authentifizierung#

Alle API-Anfragen erfordern eine Authentifizierung mit einem API-Schlüssel. Der API-Schlüssel sollte wie folgt im Anfrage-Header enthalten sein:

Authorization: Bearer IHR_API_SCHLÜSSEL

Sie können Ihren API-Schlüssel im Webmetic Dashboard im Bereich API erhalten. Jeder API-Schlüssel ist einzigartig für Ihr Konto und sollte sicher aufbewahrt werden.

Rate-Limiting#

Um eine optimale Leistung für alle Benutzer zu gewährleisten, implementiert die API ein Rate-Limiting. Das aktuelle Limit beträgt:

1 Anfrage pro Sekunde pro API-Schlüssel

Wenn Sie dieses Limit überschreiten, gibt die API eine

429 Too Many Requests

-Antwort zurück. Es wird empfohlen, in Ihren Anwendungen eine geeignete Retry-Logik mit exponentiellem Backoff zu implementieren.

Allgemeine Parameter#

Viele Endpunkte akzeptieren die folgenden allgemeinen Parameter:

Parameter	Typ	Standard	Beschreibung
domain	string	Erforderlich	Der Domainname, für den Sie Daten abrufen möchten
from_date	string	"-30 days"	Das Startdatum für den Datenbereich. Kann ein ISO 8601-formatiertes Datum oder ein relatives Datum wie "-30 days" sein
to_date	string	"now"	Das Enddatum für den Datenbereich. Kann ein ISO 8601-formatiertes Datum oder "now" sein
page	integer	1	Die Seitennummer für paginierte Ergebnisse
page_size	integer	10000	Die Anzahl der Einträge pro Seite (maximal 10000)

Endpunkte#

Unternehmenssitzungen abrufen#

GET /company-sessions

Ruft detaillierte Unternehmensinformationen und zugehörige Besuchersitzungsdaten für eine bestimmte Domain innerhalb eines bestimmten Zeitraums ab. Dieser Endpunkt bietet einen umfassenden Export aller Sitzungen in Kombination mit allen zugehörigen Unternehmensdaten.

Parameter:

Alle allgemeinen Parameter gelten für diesen Endpunkt.

Antwort:

Ein JSON-Objekt mit paginierten Besuchersitzungsdaten und Unternehmensinformationen, einschließlich:

Paginierungsdetails (Gesamteinträge, aktuelle Seite, usw.)
Unternehmensinformationen (Name, Adresse, Kontaktdaten, usw.)
Sitzungsdetails (Zeitstempel, Dauer, besuchte Seiten, usw.)
Benutzerinteraktionsdaten (Scrolltiefe, auf der Seite verbrachte Zeit, usw.)

Beispielantwort:

{
  "pagination": {
    "total": 120,
    "page_total": 12,
    "isFirst": true,
    "current": 1,
    "isLast": false,
    "page_size": 10
  },
  "results": [
    {
      "company_id": "abc123",
      "company_name": "Beispiel GmbH",
      "address": "Hauptstraße 123",
      "city": "Berlin",
      "postal_code": "10115",
      "country": "Deutschland",
      "lead_score": 75,
      "sessions": [
        {
          "session_id": "sess_xyz789",
          "timestamp": "2023-04-15T14:32:18+02:00",
          "user_agent_category": "desktop",
          "session_duration": 245,
          "user_data": [
            {
              "document_location": "https://beispiel.de/produkte",
              "document_title": "Produkte | Beispiel GmbH",
              "scroll_depth": 65,
              "time_spent": 120,
              "timestamp": "2023-04-15T14:32:18+02:00"
            }
          ]
        }
      ]
    }
  ]
}

Unternehmensinformationen abrufen#

GET /company

Ruft detaillierte Unternehmensinformationen für eine bestimmte Domain innerhalb eines bestimmten Zeitraums ab. Dieser Endpunkt liefert umfassende Daten über Unternehmen, die Ihre Website besucht haben, einschließlich Kontaktinformationen, Beschreibungen und Social-Media-Links.

Parameter:

Alle allgemeinen Parameter gelten für diesen Endpunkt.

Antwort:

Ein JSON-Objekt mit paginierten Unternehmensinformationen, einschließlich:

Paginierungsdetails
Unternehmensprofile mit Details wie:
- Unternehmens-ID
- Unternehmensname
- Adresse und Kontaktinformationen
- Unternehmensbeschreibung
- Social-Media-Links
- USt-IdNr. und Registrierungsinformationen

Beispielantwort:

{
  "pagination": {
    "total": 45,
    "page_total": 5,
    "isFirst": true,
    "current": 1,
    "isLast": false,
    "page_size": 10
  },
  "results": [
    {
      "company_id": "abc123",
      "company_name": "Beispiel GmbH",
      "company_url": "beispiel.de",
      "company_logo_url": "https://logo.clearbit.com/beispiel.de",
      "address": "Hauptstraße 123",
      "city": "Berlin",
      "postal_code": "10115",
      "country": "Deutschland",
      "phone_number": "+49 30 12345678",
      "email_address": "kontakt@beispiel.de",
      "lead_score": 75,
      "short_description_de": "Ein führendes Technologieunternehmen",
      "full_description_de": "Beispiel GmbH ist ein führendes Technologieunternehmen...",
      "directors": ["Maria Musterfrau", "Max Mustermann"],
      "linkedin": "https://linkedin.com/company/beispiel-gmbh",
      "twitter": "https://twitter.com/beispiel_gmbh"
    }
  ]
}

NACE-Codes der Unternehmen abrufen#

GET /company_nace

Ruft NACE-Codes (Statistische Systematik der Wirtschaftszweige in der Europäischen Gemeinschaft) für Unternehmen ab, die mit einer bestimmten Domain verknüpft sind. NACE-Codes sind die europäische Standardklassifikation der Wirtschaftstätigkeiten und bieten wertvolle Einblicke in die Branchen, in denen Ihre Website-Besucher tätig sind.

Parameter:

Alle allgemeinen Parameter gelten für diesen Endpunkt.

Antwort:

Ein JSON-Objekt mit paginierten NACE-Code-Informationen für Unternehmen, einschließlich:

Paginierungsdetails
Unternehmens-ID
NACE-Code-Details einschließlich Abschnitt, Abteilung und Beschreibungen auf Deutsch und Englisch

Beispielantwort:

{
  "pagination": {
    "total": 30,
    "page_total": 3,
    "isFirst": true,
    "current": 1,
    "isLast": false,
    "page_size": 10
  },
  "results": [
    {
      "company_id": "abc123",
      "code": "62.01",
      "full_code": "J62.01",
      "section_code": "J",
      "section_description_de": "Information und Kommunikation",
      "section_description_en": "Information and Communication",
      "division_code": "62",
      "division_description_de": "Erbringung von Dienstleistungen der Informationstechnologie",
      "division_description_en": "Computer programming, consultancy and related activities",
      "description_de": "Programmierungstätigkeiten",
      "description_en": "Computer programming activities"
    }
  ]
}

Sitzungsinformationen abrufen#

GET /session

Ruft detaillierte Sitzungsinformationen für eine bestimmte Domain innerhalb eines bestimmten Zeitraums ab. Dieser Endpunkt liefert umfassende Daten über Benutzersitzungen, einschließlich technischer Details über das Gerät des Benutzers, den Browser und die Interaktion mit der Website.

Parameter:

Alle allgemeinen Parameter gelten für diesen Endpunkt.

Antwort:

Ein JSON-Objekt mit paginierten Sitzungsinformationen, einschließlich:

Paginierungsdetails
Sitzungsdetails wie:
- Sitzungs-ID
- Unternehmens-ID und -name
- Zeitstempel
- User-Agent-Informationen
- Geräteinformationen
- Sitzungsdauer
- UTM-Parameter

Beispielantwort:

{
  "pagination": {
    "total": 85,
    "page_total": 9,
    "isFirst": true,
    "current": 1,
    "isLast": false,
    "page_size": 10
  },
  "results": [
    {
      "session_id": "sess_xyz789",
      "company_id": "abc123",
      "company_name": "Beispiel GmbH",
      "timestamp": "2023-04-15T14:32:18+02:00",
      "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)...",
      "platform": "Windows",
      "screen_resolution": "1920x1080",
      "viewport": "1850x950",
      "user_agent_category": "desktop",
      "user_agent_browser": {
        "family": "Chrome",
        "version": "91.0.4472.124"
      },
      "user_agent_os": {
        "family": "Windows",
        "version": "10"
      },
      "session_duration": 245,
      "session_time": 180,
      "utm_source": "google",
      "utm_medium": "cpc"
    }
  ]
}

Sitzungsbenutzerdaten abrufen#

GET /session_user_data

Ruft detaillierte Benutzerdaten für Sitzungen ab, die mit einer bestimmten Domain verknüpft sind. Dieser Endpunkt liefert granulare Informationen über Benutzerinteraktionen während jeder Sitzung, einschließlich Seitenaufrufe, Scrolltiefe und auf jeder Seite verbrachte Zeit.

Parameter:

Alle allgemeinen Parameter gelten für diesen Endpunkt.

Antwort:

Ein JSON-Objekt mit paginierten Benutzerinteraktionsdaten, einschließlich:

Paginierungsdetails
Sitzungs-ID
Zeitstempel jeder Interaktion
Seiten-URL und -titel
Scrolltiefe
Auf der Seite verbrachte Zeit
Verweiserinformationen
Anzahl der Benutzerereignisse

Beispielantwort:

{
  "pagination": {
    "total": 150,
    "page_total": 15,
    "isFirst": true,
    "current": 1,
    "isLast": false,
    "page_size": 10
  },
  "results": [
    {
      "session_id": "sess_xyz789",
      "timestamp": "2023-04-15T14:32:18+02:00",
      "document_location": "https://beispiel.de/produkte",
      "document_title": "Produkte | Beispiel GmbH",
      "scroll_depth": 65,
      "referrer": "https://beispiel.de/",
      "time_spent": 120,
      "user_events_count": 3
    }
  ]
}

Intensive Besuche abrufen#

GET /intensive-visits

Ruft eine Liste von Unternehmen ab, die intensive Besuche auf der angegebenen Domain hatten. Dieser Endpunkt identifiziert Unternehmen, die ein signifikantes Engagement mit Ihrer Website gezeigt haben, was durch Metriken wie hohe Sitzungsdauer, mehrere Seitenaufrufe oder tiefe Scrolltiefe angezeigt wird.

Parameter:

```
domain
```
(string, erforderlich): Der Domainname, für den Sie intensive Besuchsdaten abrufen möchten.

Antwort:

Ein JSON-Objekt mit Informationen über Unternehmen mit intensiven Besuchsmustern, einschließlich Details über das Unternehmen und deren Engagement-Metriken.

Beispielantwort:

{
  "results": [
    {
      "company_id": "abc123",
      "company_name": "Beispiel GmbH",
      "lead_score": 92,
      "total_visits": 8,
      "avg_session_duration": 420,
      "last_visit_date": "2023-04-18T16:45:22+02:00",
      "pages_viewed": 15
    }
  ]
}

Wiederkehrende Besuche abrufen#

GET /returning-visits

Ruft eine Liste von Unternehmen ab, die die angegebene Domain mehrmals besucht haben. Dieser Endpunkt liefert Informationen über Unternehmen, die mindestens zwei Sitzungen auf Ihrer Website hatten, was auf wiederholtes Interesse oder Engagement hinweist.

Parameter:

```
domain
```
(string, erforderlich): Der Domainname, für den Sie Daten zu wiederkehrenden Besuchern abrufen möchten.

Antwort:

Ein JSON-Objekt mit Informationen über Unternehmen mit mehreren Besuchen, einschließlich Besuchshäufigkeit und Timing-Daten.

Beispielantwort:

{
  "results": [
    {
      "company_id": "abc123",
      "company_name": "Beispiel GmbH",
      "lead_score": 78,
      "visit_count": 5,
      "first_visit_date": "2023-03-10T09:12:45+01:00",
      "last_visit_date": "2023-04-18T16:45:22+02:00",
      "days_between_visits": 39
    }
  ]
}

Neue Besuche abrufen#

GET /new-visits

Retrieves a list of companies that have visited the specified domain for the first time. This endpoint identifies companies whose first recorded session is recent, effectively capturing new visitors to your website.

Parameters:

```
domain
```
(string, required): The domain name for which you want to retrieve new company visit data.

Response:

A JSON object containing information about companies visiting your site for the first time, including company details and visit information.

Example Response:

{
  "results": [
    {
      "company_id": "def456",
      "company_name": "New Prospect Inc",
      "lead_score": 65,
      "first_visit_date": "2023-04-20T11:28:33+02:00",
      "pages_viewed": 3,
      "session_duration": 185
    }
  ]
}

Fehlerbehandlung#

Die API verwendet Standard-HTTP-Statuscodes, um den Erfolg oder Misserfolg von Anfragen anzuzeigen:

```
200 OK
```
: Die Anfrage war erfolgreich.
```
400 Bad Request
```
: Die Anfrage war ungültig oder konnte nicht verstanden werden.
```
401 Unauthorized
```
: Die Authentifizierung ist fehlgeschlagen oder wurde nicht bereitgestellt.
```
403 Forbidden
```
: Der authentifizierte Benutzer hat keine Berechtigung, auf die angeforderte Ressource zuzugreifen.
```
404 Not Found
```
: Die angeforderte Ressource wurde nicht gefunden.
```
422 Unprocessable Entity
```
: Die Anfrage war wohlgeformt, enthielt aber semantische Fehler.
```
429 Too Many Requests
```
: Rate-Limit überschritten.
```
500 Internal Server Error
```
: Auf dem Server ist ein Fehler aufgetreten.

Fehlerantworten enthalten ein

detail

-Feld mit Informationen über den Fehler:

{
  "detail": [
    {
      "loc": ["query", "domain"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Best Practices#

Paginierung verwenden: Bei der Abfrage großer Datensätze sollten Sie die Paginierungsparameter verwenden, um die Menge der in einer einzelnen Anfrage zurückgegebenen Daten zu begrenzen.
Abfrageparameter optimieren: Geben Sie den genauen Datumsbereich an, den Sie benötigen, um das Datenvolumen zu minimieren und die Antwortzeiten zu verbessern.
Caching implementieren: Zwischenspeichern Sie API-Antworten, wenn dies angebracht ist, um die Anzahl der Anfragen zu reduzieren und die Anwendungsleistung zu verbessern.
Rate-Limits handhaben: Implementieren Sie eine ordnungsgemäße Wiederholungslogik mit exponentiellem Backoff, wenn Rate-Limit-Fehler auftreten.
API-Schlüssel sichern: Speichern Sie Ihren API-Schlüssel sicher und legen Sie ihn niemals in clientseitigem Code offen.

Support#

Für zusätzliche Unterstützung oder Fragen zur API wenden Sie sich bitte an unser Support-Team unter oder nutzen Sie die integrierte Support-Funktion in Ihrem Webmetic Dashboard.