REST-Jdbc — Webmetic

Webmetic identifiziert B2B-Website-Besucher und stellt Firmendaten über eine REST-API bereit. Dieses Beispiel zeigt das Auslesen von Firmenstammdaten über /company (wem_company) mit Datensätzen unter result sowie Seiten-Paginierung (page, page_size).

Schnellstart mit dem JDBC-Client

java -jar /pfad/zu/restjdbc.jar webmetic.sql

Die Datei webmetic.sql enthält Verbindung und Beispiel-Abfragen. Vorgehen:

Treiber-JAR bereitstellen (absoluter Pfad zur restjdbc.jar)
API-Schlüssel im Webmetic-Dashboard unter API kopieren
In webmetic.sql apiKey=XXXX durch Ihren API-Schlüssel ersetzen
Befehl im Ordner starten, in dem webmetic.sql und webmetic-spec.json liegen

connect 'jdbc:rest:https://hub.webmetic.de|spec=webmetic-spec.json,auth=apikey,apiKey=Ihr_API_Schlüssel,apiKeyLocation=header,apiKeyParam=Authorization,requestIntervalMs=1000'

1. JDBC-URL

jdbc:rest:https://hub.webmetic.de

Die Basis-URL der API steht in der JDBC-URL.

Bestandteil	Wert
Treiber-Präfix	`jdbc:rest:`
API-Basis-URL	`https://hub.webmetic.de`
Schema (SQL)	`public` (Standard)

Beispiel-Verbindung (Java):

Properties props = new Properties();
props.setProperty("spec", "/pfad/zu/webmetic-spec.json");
props.setProperty("auth", "apikey");
props.setProperty("apiKey", System.getenv("WEBMETIC_API_KEY"));
props.setProperty("apiKeyLocation", "header");
props.setProperty("apiKeyParam", "Authorization");
props.setProperty("requestIntervalMs", "1000");

Connection conn = DriverManager.getConnection(
    "jdbc:rest:https://hub.webmetic.de", props);

2. Connection Properties

Property	Wert für Webmetic	Erforderlich
`spec`	Pfad zur Spec (siehe unten)	Ja
`auth`	`apikey`	Ja
`apiKey`	API-Schlüssel aus dem Webmetic-Dashboard	Ja
`apiKeyLocation`	`header`	Ja
`apiKeyParam`	`Authorization`	Ja
`requestIntervalMs`	Mindestabstand zwischen HTTP-Requests in Millisekunden (`1000` für Webmetic)	Empfohlen
`retryOn429`	Bei HTTP 429 automatisch erneut versuchen (Standard: `true`)	Nein
`maxRetries`	Maximale Wiederholungen bei HTTP 429 (Standard: `5`)	Nein
`stdoutlog`	Debug-Ausgabe: `cursor`, `http`, `rows` oder `all` (z. B. `cursor+http+rows`)	Nein

Minimal:

props.setProperty("spec", "/pfad/zu/webmetic-spec.json");
props.setProperty("auth", "apikey");
props.setProperty("apiKey", "Ihr_API_Schlüssel");
props.setProperty("apiKeyLocation", "header");
props.setProperty("apiKeyParam", "Authorization");
props.setProperty("requestIntervalMs", "1000");

Property-Namen sind case-insensitive (z. B. funktionieren auch apikey, apikeylocation, apikeyparam).

Spec-Pfad: absoluter Pfad zu Ihrer lokalen Kopie der Spec-Datei.

Spec-Datei: webmetic-spec.json

3. Spec-Datei

Datei: webmetic-spec.json

Die Spalten und Datentypen der Spec orientieren sich an der Zieltabelle analysis.trs_wem_company:

CREATE TABLE analysis.trs_wem_company (
   company_id VARCHAR(255) NOT NULL
 , company_name VARCHAR(500)
 , address VARCHAR(1000)
 , postal_code VARCHAR(255)
 , city VARCHAR(255)
 , country VARCHAR(8000)
 , country_code VARCHAR(8000)
 , directors VARCHAR(8000)
 , phone_number VARCHAR(255)
 , fax_number VARCHAR(255)
 , email_address VARCHAR(255)
 , email_pattern VARCHAR(50)
 , email_pattern_confidence DECIMAL(15,6)
 , vat_id VARCHAR(255)
 , tax_number VARCHAR(255)
 , registration_number VARCHAR(1000)
 , registration_court VARCHAR(255)
 , company_url VARCHAR(255)
 , company_logo_url VARCHAR(255)
 , primary_color VARCHAR(50)
 , secondary_color VARCHAR(50)
 , linkedin VARCHAR(255)
 , facebook VARCHAR(255)
 , instagram VARCHAR(255)
 , youtube VARCHAR(255)
 , twitter VARCHAR(255)
 , organization_type VARCHAR(255)
 , short_description_en VARCHAR(1000)
 , short_description_de VARCHAR(1000)
 , full_description_en VARCHAR(5000)
 , full_description_de VARCHAR(5000)
 , what_they_do_de VARCHAR(5000)
 , what_they_do_en VARCHAR(5000)
 , how_they_make_money_de VARCHAR(5000)
 , how_they_make_money_en VARCHAR(5000)
 , target_audience_de VARCHAR(5000)
 , target_audience_en VARCHAR(5000)
 , employee_count VARCHAR(255)
 , revenue VARCHAR(255)
);

In der Spec werden dieselben Spaltennamen und SQL-ähnlichen Typen (VARCHAR(n), DECIMAL(p,s)) auf die REST-Entity wem_company abgebildet. Vollständige Datei: webmetic-spec.json.

Auszug:

{
  "entities": [
    {
      "name": "wem_company",
      "path": "/company",
      "dataPath": "/result",
      "write": false,
      "columns": [
        { "name": "company_id", "type": "VARCHAR(255)", "primaryKey": true },
        { "name": "company_name", "type": "VARCHAR(500)" },
        { "name": "email_pattern_confidence", "type": "DECIMAL(15,6)" }
      ],
      "pagination": {
        "type": "page",
        "pageParam": "page",
        "limitParam": "page_size",
        "defaultLimit": 10000
      }
    }
  ]
}

Tabelle `wem_company`

SQL-Tabelle	REST-Pfad	JSON-Zeilen	Paginierung
`wem_company`	`/company`	`/result`	`page` mit `page_size` / `page` (Standard: 10000 pro Seite)

Der Treiber setzt page und page_size automatisch und lädt alle Seiten, bis eine leere Antwort kommt.

Anpassungen: Endpunkt-Pfad (path), JSON-Struktur (dataPath) und Spalten müssen mit Ihrer Webmetic-API-Dokumentation übereinstimmen. Verschachtelte Objekte in der API-Antwort erfordern ggf. jsonPath auf einzelnen Spalten.

4. Authentifizierung

Webmetic stellt einen API-Schlüssel im Dashboard bereit (Bereich API). Die API erwartet den Schlüssel im Header Authorization ohne Bearer-Präfix:

Authorization: Ihr_API_Schlüssel

Verwenden Sie auth=apikey mit dem Header-Namen Authorization — nicht auth=bearer, das würde Authorization: Bearer … senden:

props.setProperty("auth", "apikey");
props.setProperty("apiKey", "Ihr_API_Schlüssel");
props.setProperty("apiKeyLocation", "header");
props.setProperty("apiKeyParam", "Authorization");
props.setProperty("requestIntervalMs", "1000");

Der Treiber sendet: Authorization: Ihr_API_Schlüssel

Siehe auch die Hauptdokumentation.

5. Rate Limits

Webmetic erlaubt typisch 1 Request pro Sekunde. Die Drosselung wird über Connection Properties konfiguriert:

Property	Wert für Webmetic
`requestIntervalMs`	`1000`
`retryOn429`	`true` (Standard)
`maxRetries`	`5` (Standard)

Der Treiber wartet nicht pauschal 1 Sekunde nach jedem Aufruf. Er merkt sich den Startzeitpunkt des letzten Requests und wartet nur die verbleibende Zeit bis zum Intervall. Bei HTTP 429 wird der Request automatisch wiederholt; die Wartezeit kommt aus dem Header Retry-After oder aus requestIntervalMs.

props.setProperty("requestIntervalMs", "1000");
props.setProperty("retryOn429", "true");

Siehe auch die Hauptdokumentation.

6. SQL-Beispiele

SELECT Firmenstammdaten

SELECT company_id, company_name, city, country, company_url, employee_count, revenue
FROM wem_company
;

SQL	HTTP (vereinfacht)
`SELECT … FROM wem_company`	`GET …/company?page_size=10000&page=1`

Erwartet die API Query-Parameter, werden sie mit AND in FILTER kombiniert:

SELECT company_id, company_name, city, country
FROM wem_company
FILTER company_id='12345'
;

page und page_size kommen aus der Paginierung in der Spec — nicht in die FILTER-Klausel.

String-Werte in einfachen Anführungszeichen setzen. AND ist case-insensitive (and funktioniert ebenfalls).

INSERT, UPDATE, DELETE

Nicht unterstützt ("write": false).

7. System-Tabellen

SELECT table_name, remarks FROM system.table_list;

SELECT column_name, type_name, column_size, decimal_digits
FROM system.column_list
WHERE table_name = 'wem_company'
;

SELECT column_name FROM system.pk_list WHERE table_name = 'wem_company';

8. Hinweise

API-Dokumentation: Endpunkt-Namen, Auth-Format und JSON-Struktur in Ihrem Webmetic Developer Hub prüfen und die Spec bei Bedarf anpassen.
Rate Limits: Webmetic erlaubt typisch 1 Request pro Sekunde. Setzen Sie requestIntervalMs=1000 — der Treiber wartet dann nur die verbleibende Zeit seit dem letzten Request, nicht pauschal 1 Sekunde pro Aufruf. Bei HTTP 429 wird automatisch erneut versucht (retryOn429, Standard true); die Wartezeit kommt aus dem Header Retry-After oder aus requestIntervalMs.
FILTER-Fehler: Bei ungültiger FILTER-Syntax zeigt die Fehlermeldung den empfangenen FILTER-Text. Mit stdoutlog=cursor+http sehen Sie FILTER und die erzeugte HTTP-URL.
Weitere Endpunkte: Webmetic bietet u. a. /company-sessions, /intensive-visits, /new-visits und /returning-visits — als weitere Entities in derselben Spec anlegbar.
Verschachtelte Felder: Liefert die API verschachtelte Objekte (z. B. strukturierte Adressdaten), per jsonPath auf einzelnen Spalten abbilden.