Mit Hilfe des Loqate Add-Ons in Synesty lassen sich Adressdaten überprüfen, validieren und standardisieren. Dadurch wird die Datenqualität verbessert, Zustellfehler werden reduziert und Prozesse in E-Commerce-, Warenwirtschafts- oder CRM-Systemen effizienter gestaltet.
API Zugriff einrichten & Verbindungsdaten im Synesty Studio hinterlegen
Um Loqate über Synesty nutzen zu können, muss ein Service Key in Loqate erstellt und in Synesty hinterlegt werden. Dafür gibt es verschiedene Wege:
- Auf dem Loqate Dashboard unter ‘Your services’ über ‘Add a new service’.
- Unter ’+ Add a service’ in der Navigationsleiste.
Danach wird ein Service-Key angezeigt, welcher in Synesty unter ‘Meine Verbindungen > Loqate’ hinterlegt werden muss:
LoqateCheckAddresses Step
Dieser Step prüft die Adressen, korrigiert sie automatisch und filtert, welche Adressen im Nachgang noch einmal überprüft werden sollten. Als Eingabedaten (‘input’) können Bestell- oder Kundendaten aus verschiedensten Systemen genutzt werden.
Einstellungen
Account
Hier wird der gerade erstellte Account ausgewählt.
Mappingdefinition
Die wichtigsten Spalten:
| Spalte | Beschreibung |
|---|---|
| id | Selbstgewählte id, die den jeweiligen Output-Zeilen hinzugefügt wird. Hier sollten z. B. Bestellnummern oder Kundennummern verwendet werden, um die ausgegebenen Adressen den richtigen Bestell- oder Kundendatensätzen zuordnen zu können. (PFLICHTSPALTE) |
| Address | Geben Sie die vollständige Adresse ein oder verwenden Sie die Felder „Adresse 1–8“, “PostalCode” usw., um Teile der Adresse anzugeben (z. B. Straße, Hausnummer, Postleitzahl). |
| Address1-8 | Geben Sie einen Teil der Adresse ein (z. B. Straße, Hausnummer, Postleitzahl) oder verwenden Sie das Feld ‘Address’, um die vollständige Adresse in einem einzigen Feld anzugeben. |
| Country | ISO2- oder ISO3-Ländercode (PFLICHTSPALTE) |
limit
Mit dem Limit können die Datensätze, welche an Loqate übermittelt werden, eingeschränkt werden. Dies ist besonders für Testzwecke nützlich.
Scoring-Parameter (minimum_Matchscore, required_VerificationStatus usw.)
Anhand der Scoring-Parameter filtert der LoqateCheckAddresses Step, welche Adress-Datensätze als verifiziert gelten oder noch einmal überprüft werden sollten. Ein Adress-Datensatz gilt nur als verifiziert, wenn ALLE definierten Scoring-Parameter eingehalten werden.
Einige Scoring-Parameter wurden, entsprechend der Empfehlungen und Best Practises von Loqate, voreingestellt.
Einzelheiten der verschiedenen Parameter können im Abschnitt “LoqateCheckAddresses Ausgabedaten” nachgelesen werden.
| Parameter & Beschreibung | mögliche Werte | Standardwert | Wann anpassen |
|---|---|---|---|
| minimum_Matchscore Mindestwert Matchscore | 0-100 | 92 | - verringern bei sehr unsauberen Daten - erhöhen bei höheren Anforderungen |
| required_VerificationStatus Erforderlicher VerificationStatus | Verified (V) | Verified (V) | Nicht änderbar |
| minimum_ PostProcessedVerificationMatchLevel minimales Matchlevel nach Verarbeitung | 0-5 | 4 = Grundstück (oder Gebäude) | 4 reicht in der Regel in Deutschland aus, da selten Wohnungs- oder Appartementnummern verwendet werden, welche Level 5 entsprechen würden. |
| required_PostcodeStatus Erlaubte Postcode-Status | P1, P2, P3, P4, P5, P6, P7, P8 | P4 bis P8 | Bei Adressen, welche eine sekundäre PLZ verwenden. |
| maximum_ VerificationMatchLevel_Deviation Max. Abweichung der MatchLevel | 0–5 | - | Bei Bedarf, wenn Abweichungen eingeschränkt oder erweitert werden sollen |
Anwendungsbeispiel
Aufbau des Flows
Zunächst benötigen wir Adressdaten, welche wir mit Loqate auf Fehler überprüfen werden. Dazu erstellen wir einen neuen Flow und fügen als ersten Step einen “URLDownload” ein.
Step 1: URLDownload
Für dieses Beispiel haben wir eine CSV-Datei mit Adressdaten, welche verschiedene Fehler enthält, unter folgender URL hinterlegt: https://demodata.synesty.com/Loqate/Loqate-Demo-Addresses.csv
Diese URL wird im URLDownload in das Feld “host” eingefügt. Damit ist der Step schon fertig konfiguriert. Nun können wir uns mit dem blauen Button “Step-Vorschau” ansehen, welche Daten heruntergeladen werden.
Step 2: CSVReader
Um die CSV-Datei einzulesen, verwenden wir den “CSVReader” Step. In diesem Step muss nichts weiter konfiguriert werden und wir können uns direkt die Vorschau ansehen.
In der Vorschau sehen wir jetzt die als Spreadsheet Tabelle eingelesenen Adressdaten mit ihren jeweiligen Fehlern. Wir haben verschiedene Fehler eingebaut, um auszuwerten, wie sich die Ausgabeparameter von Loqate bei den jeweiligen Fehlern verhalten.
Step 3: LoqateCheckAddresses
Als Herzstück des Flows wird jetzt der “LoqateCheckAddresses” Step eingefügt.
Folgende Einstellungen müssen vorgenommen werden:
Account: Hier den erstellten Loqate-Account auswählen.
Mappingdefinition:
- Configure klicken
- Daten aus den vorherigen Steps holen klicken
- In der Spalte “id” als Quelle “OrderNumber” auswählen & Konfiguration abschließen
Alle weiteren Einstellungen bleiben, wie sie voreingestellt sind. Wir können uns nun die Vorschau ansehen.
In der Vorschau sehen wir jetzt mehrere Outputs:
- Die “verifiedAddresses”, welche den eingestellten Scoring-Parametern entsprechen und weiterverarbeitet werden können.
- Die “reviewAddresses”, welche NICHT den eingestellten Scoring-Parametern entsprechen und überprüft werden sollten.
Einzelheiten zu den ausgegebenen Feldern finden Sie im nächsten Abschnitt.
Die Daten des “reviewAddresses” Output wollen wir jetzt in eine CSV-Datei schreiben und uns diese via E-Mail senden. Dazu entfernen wir zunächst mit einem Mapper Step einige Spalten.
Step 4: Mapper
Zur Übersichtlichkeit entfernen wir mit einem Mapper Step einige Spalten.
Einstellungen:
Source: Die automatisch eingefügte Source (“LoqateCheckAddresses -> verifiedAddresses”) entfernen und “LoqateCheckAddresses -> reviewAddresses” auswählen, welcher die zu prüfenden Datensätze enthält!
Mappingdefinition:
- Configure klicken
- Daten aus den vorherigen Steps holen klicken
- Spalten -> alle Spalten entfernen
- Quellspalten hinzufügen: identifier, Input.Address, Address, AVC, Matchscore, Pre-ProcessedVerificationMatchLevel, Post-ProcessedVerificationMatchLevel, VerificationMatchLevel_Deviation, VerificationStatus, PostcodeStatus
- Konfiguration abschließen
Nun sind die Daten fertig, um sie in die CSV zu schreiben.
Step 5: CSVWriter
Mit dem CSVWriter wird die CSV-Datei erstellt, welche wir mit unserer E-Mail als Anhang versenden.
Einstellungen:
Filename: reviewAddresses.csv
Step 6: EmailSend
Unser letzter Step für den Flow versendet die E-Mail: EmailSend
Einstellungen:
to: Eigene E-Mail-Adresse eintragen
subject: Bestellungen: Adressen prüfen
message: ACHTUNG! Bei folgenden Bestellungen sollten die Adressen überprüft werden.
attachments: Sollte automatisch mit der Datei aus dem CSVWriter gefüllt sein. Falls nicht: “Mit Output verknüpfen” klicken & CSVWriter-Step auswählen.
Jetzt ist der Flow fertig konfiguriert und kann ausgeführt werden. Während der Ausführung wird Ihnen eine Mail mit der verarbeiteten Datei zugesendet.
Anstatt des URLDownloads kann auch ein anderer Step aus unserem Portfolio verwendet werden, um z. B. Adressdaten aus verschiedenen Systemen zur Prüfung abzurufen:
- commercetoolsGetOrders
- SellerCentralGetOrders
- billbeeGetOrders
- EbayGetOrders
- HubSpotGetOrders
- KauflandGetOrderUnits
- MagentoSearchOrders
- Magento2GetOrders
- PlentySearchOrders
- PlentyGetCustomers
- shopifyGetOrders
- ShopwareSearchOrders
- TradebyteGetOrders
- weclappGetSalesOrder
- woocommerceGetOrders
LoqateCheckAddresses Ausgabedaten (Output)
Der LoqateCheckAddresses Step hat 4 verschiedene Outputs:
- verifiedAddresses: Datensätze welche den eingestellten Scoring-Parametern entsprechen
- reviewAddresses: Datensätze welche NICHT den eingestellten Scoring-Parametern entsprechen
- invalidInput: Datensätze bei welchen Pflichtspalten nicht gefüllt waren
- failedRequest: Datensätze bei welchen bei der Anfrage an die Loqate API Fehler aufgetreten sind.
Um herauszufinden, was die Best Practises zur Entscheidung sind, ob eine ausgegebene Adresse ein akzeptables Ergebnis ist, schauen Sie in den nächsten Abschnitt.
Die Outputs “verifiedAddresses” & “reviewAddresses” enthalten folgende Spalten:
| Spalte | Beschreibung |
|---|---|
| id | Die durchgeschleifte selbstgewählte id. |
| Input. ... | Spalten mit 'Input.' Präfix sind durchgeschleifte Input Spalten |
| AQI | Der Adressqualitätsindex (AQI) gibt die allgemeine Adressqualität an (z. B. ausgezeichnet, gut, durchschnittlich). Er basiert auf zwei Faktoren: - Nachbearbeiteter Verifizierungsabgleichgrad - Übereinstimmungswert Der AQI spiegelt zwar die Adressqualität wider, wird jedoch NICHT zur Entscheidung über die Annahme einer vorgeschlagenen/korrigierten Adresse herangezogen. Verwenden Sie hierfür den AVC. A = Ausgezeichnet B = Gut C = Durchschnittlich D = Schlecht E oder Leer = Sehr schlecht Weitere Informationen dazu in der Loqate Dokumentation |
| AVC | Der Adressverifizierungscode (AVC) z. B. 'V44-I44-P4-090' besteht aus mehreren Parametern, die in die folgenden Spalten unterteilt sind. Weitere Informationen dazu in der Loqate Dokumentation |
| VerificationStatus | 'V44-I44-P4-090': - V (Verified): Exakte Übereinstimmung mit einem Referenzdatensatz. - P (Partially Verified): Teilweise Übereinstimmung mit einem Referenzdatensatz. - A (Ambiguous): Mehrere nahe Übereinstimmungen gefunden. - R (Reverted): Keine akzeptable Übereinstimmung; Eingabedaten zurückgegeben. - U (Unverified): Kann nicht verifiziert werden; Eingabedaten zurückgegeben. |
| Post-ProcessedVerificationMatchLevel | 'V44-I44-P4-090': Das Post-ProcessedVerificationMatchLevel zeigt, wie genau die endgültige, verifizierte Adresse nach allen Korrekturen und Verbesserungen mit den Referenzdaten übereinstimmt. 5: Zustellpunkt (Briefkasten oder Untergebäude) 4: Grundstück (oder Gebäude) 3: Durchgangsstraße 2: Ortsteil oder Postleitzahl 1: Verwaltungsgebiet 0: Keine Angabe |
| Pre-ProcessedVerificationMatchLevel | 'V44-I44-P4-090': Das Pre-ProcessedVerificationMatchLevel zeigt, wie gut die ursprüngliche Eingabe vor der Verarbeitung mit den Referenzdaten übereinstimmt. 5: Zustellpunkt (Briefkasten oder Untergebäude) 4: Grundstück (oder Gebäude) 3: Durchgangsstraße 2: Ortsteil 1: Verwaltungsgebiet 0: Keine Angabe |
| ParsingStatus | 'V44-I44-P4-090': I: Identifiziert und eingelesen: Alle Eingabedaten (z. B. Address1-8) konnten identifiziert und in Komponenten (Straße, Stadt, Postleitzahl. usw) eingeordnet werden. U: Unable to parse (nicht möglich einzulesen): Nicht alle Eingabedaten konnten identifiziert und eingeordnet werden. |
| LexiconIdentificationMatchLevel | 'V44-I44-P4-090': Das LexiconIdentificationMatchLevel gibt an, wie gut die Ausgabedaten mit bekannten Mustern oder Begriffen übereinstimmen (z. B. „Str.“ = Straße). |
| ContextIdentificationMatchLevel | 'V44-I44-P4-090': Das ContextIdentificationMatchLevel gibt an, wie gut Ausgabedaten anhand ihrer Position und der umgebenden Elemente identifiziert werden. Es handelt sich um die ungenaueste Übereinstimmungsart, die sich auf kontextbezogene Hinweise stützt. 5: Zustellpunkt (Briefkasten oder Untergebäude) 4: Grundstück (oder Gebäude) 3: Durchgangsstraße 2: Ortsteil 1: Verwaltungsgebiet 0: Keine Angabe |
| PostcodeStatus | 'V44-I44-P4-090': Status der Hauptpostleitzahl (PostalCodePrimary) und dem Zusatz zur Postleitzahl (PostalCodeSecondary). Deutschland kennt offiziell nur die fünfstellige Postleitzahl. Falls ein „Secondary“-Eintrag vorkommt, handelt es sich meist um Zusatzinformationen wie Postfächer oder organisatorische Sortierhinweise. P8: PostalCodePrimary und PostalCodeSecondary verifiziert P7: PostalCodePrimary verifiziert, PostalCodeSecondary hinzugefügt oder geändert P6: PostalCodePrimary verifiziert P5: PostalCodePrimary mit geringfügiger Änderung verifiziert P4: PostalCodePrimary mit erheblicher Änderung verifiziert P3: PostalCodePrimary hinzugefügt P2: PostalCodePrimary durch Lexikon identifiziert P1: PostalCodePrimary durch Kontext identifiziert P0: PostalCodePrimary leer |
| Matchscore | 'V44-I44-P4-090': Der Matchscore zeigt an, wie stark die Eingabedaten während der Überprüfung verändert wurden, um das endgültige MatchLevel zu erreichen. 100 % bedeutet, dass keine Änderungen vorgenommen wurden; Werte über 95 weisen auf kleinere Anpassungen hin. Er misst jedoch weder Ergänzungen noch die Qualität der Überprüfung. |
| Address | Vollständige Postanschrift, formatiert gemäß dem Feld 'AddressFormat' mit Zeilenumbrüchen gemäß 'AddressLineSeparator'. |
| AddressFormat | Enthält die Felder, die zum Aufbau des 'Address'-Feldes verwendet werden. Beispiel: „Organization<BR>DeliveryAddress<BR>Locality AdministrativeArea PostalCode“. Die standardmäßigen <BR>-Zeilenumbrüche können mit der 'AddressLineSeparator'-Einstellung angepasst werden. |
Best Practices zur Bewertung, ob eine ausgegebene Adresse ein akzeptables Ergebnis ist:
Allgemein sollten zur Entscheidung, ob eine ausgegebene Adresse ein akzeptables Ergebnis ist, immer mehrere Parameter betrachtet werden. Ein Parameter alleine reicht nicht zu einer fundierten Entscheidung aus.
Matchscore (aus der AVC Spalte)
‘V44-I44-P4-090’
Der Matchscore gibt die Ähnlichkeit zwischen der eingegebenen Adresse und der am besten passenden Referenzdatenübereinstimmung als Prozentsatz zwischen 0 und 100 an.
100 % bedeutet vollständige Übereinstimmung. Wenn der Matchscore nicht 100 beträgt, wurden die Daten verändert. Je niedriger der Matchscore, desto größer war die Änderung. Im Allgemeinen deutet ein Matchscore von 95 oder höher darauf hin, dass nur ein oder zwei Zeichen während des Prozesses verändert wurden. Wenn die Input Daten weniger sauber sind, kann ein Schwellenwert von 80 in Betracht gezogen werden, da dann deutlich größere Änderungen an den Input Data zugelassen werden. Ein akzeptabler Matchscore variiert je nach Anwendung. Für Direct Mail könnte ein Matchscore unter 95 fragwürdig sein. Für andere Anwendungen, bei denen Daten aggregiert werden, kann 80 akzeptabel sein. Der geschäftliche Bedarf bestimmt das Akzeptanzniveau.
Allgemein empfiehlt Loqate einen Matchscore von mindestens 92.
Post-Processed Verification Match Level (Match Level NACH der Verarbeitung)
& Pre-Processed Verification Match Level (Match Level VOR der Verarbeitung)
Post-Processed Verification Match Level: ‘V44-I44-P4-090’
Pre-Processed Verification Match Level: ‘V44-I44-P4-090’
5: Zustellpunkt (Briefkasten oder Untergebäude) 4: Grundstück (oder Gebäude) 3: Durchgangsstraße 2: Ortsteil oder Postleitzahl 1: Verwaltungsgebiet 0: Keine Angabe
Hier im Beispiel haben beide Verification Match Level den Wert 4. Vor sowie nach der Verarbeitung ist die Adresse bis zur Grundstücks-Ebene verifiziert.
Was bedeutet es, wenn die Werte sich unterscheiden, z. B. wenn der AVC V41 ist?
„4“ (Grundstück oder Gebäude) ist das ‘Post-Processed Verification Match Level’ und zeigt das Verifikationsniveau nach der Verarbeitung an. „1“ (Verwaltungsgebiet) ist das ‘Pre-Processed Verification Match Level’ und zeigt das Verifikationsniveau vor dem Engine Processing an.
Dies bedeutet, dass die ausgegebene Adresse möglicherweise erhebliche Änderungen und Ergänzungen durchlaufen hat, um das ‘Post-Processed Verification Match Level’ von 4 zu erreichen.
Loqate empfiehlt ein Post-Processed Verification Match Level von mindestens 4.
Falls benötigt, kann die maximale Abweichung der beiden Werte mit dem Parameter “maximum_VerificationMatchLevel_Deviation” im LoqateCheckAddresses Step definiert werden.
PostcodeStatus
Loqate empfiehlt ein PostcodeStatus von mindestens P4.
AQI
Der AQI soll laut Loqate NICHT zur Bewertung von Addressen einbezogen werden.