Zum Hauptinhalt springen

Doku API + Massenprüfung

Allgemeines

Mit Ihrer kostenlosen Registierung erhalten Sie unter "Mein Konto" Ihre Zugangsdaten, Ihre API-Customer-ID ("apicid") sowie den Api-Key ("apikey"). Diese senden Sie uns in Ihren Requests mit.

Welche Eingabefelder noch benötigt werden, hängt von den Produkten ab, die Sie auswählen. Beim "Telefonverzeichnis"  ist es sinnvoll, neben den absolut notwendigen Pflichtfeldern ein paar Eingaben mehr zu senden. Siehe Tabelle unten.

Im Eingabefeld "product" senden Sie einen oder mehrere Produkt-Schlüssel mit Komma getrennt. 

Produktschlüssel und Pflichtfelder

Product KeyProduktAnrede/
salutation
Titel/
title
Vorname/
firstname
Nachname/
lastname
Strasse/
street
Hnr/
hno
PLZ/
zip
Ort/
city
Land/
country 
Telefon/
phone
EMail/
email
UmsStID/
vatin
SC + SCXAdress-Check DACH     XXXXX   
SC_INT *Adress-Check World    XOXXX   
FKFake-Check  XXOOOOO   
NCNamens-Check B2COOXX    O   
EM + EMXE-Mail-Check          X 
PBTelefonverzeichnis (Preis je Anfrage)  OXXOXXXO  
PBTTelefonverzeichnis (Preis auf Trefferbasis)  OXXOXXXO  
VATIDUst-IdNr-Check           X
VATIDXUst-IdNr-Check extended           X

* Erweiterte Eingabefelder für Product Key "SC_INT", Version 2

Product KeyProduktstatezip_add_onlocationhouse_estatesub_building_nameorganisation
SC_INTAdress-Check WorldUSA: state ist Pflichtfeld,
z.B. "TX" oder Texas
USA: 4stellige PLZ(add on)Strassenzusatz, länderabhängigGebäudebe-
zeichnung, länderabhängig
CA + UK: Block-Bezeichnung
in großen
Gebäuden
optional,
länder-
abhängig

X = Pflichtfeld, O = optionales Eingabefeld zur Ergebnisoptimierung, OX = klare Empfehlung, das Feld mitzuliefern.

Die Hausnummer (hno) kann auch im Feld street enthalten sein. Wir liefern das Ergebnis immer getrennt.

Die Telefonnummer (phone) bitte in einem Feld (Vorwahl- und Rufnummer) liefern. Ohne oder mit beliebigen Trennzeichen. Mit oder ohne Ländervorwahl. Falls nötig, ermitteln wir diese anhand des Länderkennzeichens (country). Für Deutschland muss keine Ländervorwahl angegeben werden (stört aber nicht). Ansonsten bitte die Ländervorwahl im Format +49 oder 0049 mitliefern, falls vorhanden. Ansonsten hängen wird diese an.

Feld Land (country) Ländercode, bitte mit 2- oder 3-stelligem ISO-3166-Code (alpha) versehen: DE, AT, CH, ... oder DEU, AUT, CHE. Info: Wenn Sie das Land leer lassen, versuchen wir es innerhalb der DACH-Region zu ermitteln.  

* Den Adress-Check World (SC_INT) gibt es in 2 Varianten. Version 1 entspricht bei Ein- und Ausgabe dem "Adress-Check Light" (SC, vor 2023-04). Version 2 ermöglicht erweiterte Ein- und Ausgabefelder, die länderabhängig benötigt werden. Außerdem wird hier bei mehrdeutigen Adressen eine Vorschlagsliste mit mehreren Responses ausgegeben (array). Aufruf URL je Version siehe unten.

Eingabefelder


'apicid' => 1000                                     /* API Consumer ID, siehe Mein Konto */
'apikey' => 'ffffffff-ffff-ffff-ffff-ffffffffffff'   /* API Key, siehe Mein Konto */
 
'product' => 'SC,FK,NC,EM,PB,PC',                    /* hier mit Komma getrennt die gewünschten Tests senden */
'salutation' => 'Herr',
'title' => 'Prof. Dr.',
'firstname' => 'Max',
'lastname' => 'Mustermann',
'street' => 'Teststr.',
'hno' => '9',
'zip' => '12345',
'city' => 'Entenhausen',
'country' => 'DE',
'phone' => '01234/56789',
'email' => 'test@test-email.de',
'date_of_birth' => '19701231',
'vatin' => 'IT-006/347/812 34',

Ausgabefelder



/** Basic Version (ehemaliger Adress-Check light, bis März 2023)
 *  https://api.adresslabor.de/v1/de/check
 *
 *	"Adress-Check light" (sc, street-check)
 * 	"Adress-Check World v1" (sc_int, street-check international))
 *	max. eine Response pro Request 														
 */

 "sc": [
        {
            "trafficlight": "gruen",
            "resulttext": "OK, sicher gefunden",
            "resultcode": "13212",
            "points": 99,
            "recordno": 1,
            "zip": "63768",
            "city": "Hösbach",
            "district": "",
            "street": "Kolpingstr.",
            "hno": "14"
        }
    ],
    "credits": 4701.00
}


/* Upgrade-Versionen ab April 2023
 * https://api.adresslabor.de/v3/de/check

 *		"Adress-Check DACH (Basic + Extended)" (sc, scx)
 *		"Adress-Check World v1" (sc_int light Version)
 *		max. eine Response pro Request 
 */ 
 
"sc": [
        {
            "trafficlight": "gruen",
            "resulttext": "OK, sicher gefunden",
            "resultcode": "13212",
            "points": 99,
            "recordno": 1,
            "country": "DE",
            "zip": "63768",
            "city": "Hösbach",
            "place_affix": "",
            "district": "",
            "street": "Kolpingstr.",
            "hno": "14",
            "ziptype": "Zustell-PLZ",
            "state_key": "09",
            "state": "Bayern",
            "municipalitykey": "09671130"
        }
    ],
    "credits": 4710.00
} 

 
 "scx": [
        {
            "trafficlight": "gruen",
            "resulttext": "OK, sicher gefunden",
            "resultcode": "13212",
            "points": 99,
            "recordno": 1,
            "country": "DE",
            "zip": "63768",
            "city": "Hösbach",
            "place_affix": "",
            "district": "",
            "street": "Kolpingstr.",
            "hno": "14",
            "ziptype": "Zustell-PLZ",
            "state_key": "09",
            "state": "Bayern",
            "county": "Aschaffenburg",
            "administrative_district": "Unterfranken",
            "municipality": "Hösbach, Markt",
            "municipalitykey": "09671130",
            "location_size_class": "10.001 - 20.000",
            "geo_x_coord": "9.1954",
            "geo_y_coord": "49.999826",
            "geo_quality": "STR",
            "grand_recipient": ""
        }
    ],
    "credits": 4711.00
 
 
/** "Adress-Check World v2" (sc_int, extended response))
 *  https://api.adresslabor.de/v2/de/check
 *  Array mit Vorschlagsliste bei mehrdeutigen Treffern möglich
 */ 
 
[scint] => Array (
     [0] => (
        points] => 80
        [resulttext] => unsicher (70-89 Pkt.) o. nur PLZ+Ort
        [resulttext_details] =>
        [trafficlight] => gelb
        [resultcode] => 11713
        [recordno] =>  1
        [res_deliverability] => OK
        [zip_type] => Zustell-Adresse
        [street] => Teststr.
        [hno] => 18
        [street_hno] => Teststr. 18
        [zip] => 12345
        [zip_add_on] => 
        [city] => Entenhausen
        [district] => Vorstadt
        [country_iso_2] => DE
        [country_full] => Deutschland
        [region_code] => 09
        [region] => Bayern
        [state_code] => 
        [state] => 
        [city_long] => Entenhausen
        [street_short] => Teststr.
        [pobox_zip] => 
        [pobox_city] => 
        [pobox_no] => 
        [pobox_state] => 
        [special_zip] => 
        [special_city] =>
        [special_country] =>
        [building_name] =>
        [sub_build_name] =>
        [organisation] =>
        [location] =>
 
    )
)
 
/* Die folgenden Responses kommen per Request an beide URLs:
 *  https://api.adresslabor.de/v3/de/check
 *  https://api.adresslabor.de/v1/de/check 
 */ 
 
/*	"Fake-Check" (fk)
 */

 
[fk] => (
   [resulttext] => OK
   [trafficlight] => gruen
)
 
/*	"Namens-Check B2C" (nc)
 */
 
[nc] => (
    [resulttext] => OK (keine Veränderungen)
    [trafficlight] => gruen
    [salutation] => Herr
    [title] => Dr.
    [firstname] => Max
    [lastname] => Mustermann
 
)
 
/*	"E-Mail-Check" (em) und "E-Mail-Check extended" (emx)
 */
 
[em] => (
    [resulttext] => Top-Level-Domain ist ungültig
    [trafficlight] => rot
)
 
/*	"Telefonverzeichnis" (pb, pbt)
 */
 
[pb] => Array (
     [0] =>  (
                [points] => 3
                [zip] => 12345
                [city] => Entenhausen
                [street] => Teststr.
                [hno] => 9
                [phone] => 01234/56789
                [resulttext] => Telefonnr. mit abweichenden/fehlenden Daten gefunden
                [trafficlight] => gelb
                [recordno] => 1
                [name] => Mustermax GmbH & Co.KG
                [country] => DE
      )
)
 
 
 
/* "Ust-Nr.-Check" (vatid, vatidx ) 
 */
    
 [vatid] => 
        (
            [vatNumber] => IT00634781234
            [resulttext] => OK
            [trafficlight] => gruen
            [address] => VIA AURELIO SAFFI 15 25121 BRESCIA BS
            [name] => SO.PAR SRL
        )
 
 
/*	Info: verbleibende Credits jeweils  
 */
 
[credits] => 10099

Ergebnisse Adress-Check

resulttexttrafficlightBedeutung
OKgruenAdresse korrekt, keine Änderungen
OK, sicher gefundengruenAdresse mit geringfügigen Abweichungen gefunden
unsicher gefundengelbAdresse mit größeren Abweichungen gefunden oder Hausnr. unbekannt. Oder Postfach außerhalb des bekannten Nummernbereichs. 
unsicher, PLZ und Ort OKgelbNur PLZ und Ort gefunden, Packstation oder Sonderfälle in Österreich/ Schweiz, wo kleinere Orte manchmal keine Straßennamen haben.
unsicher gefunden, Hausnr./ Postf. prüfengelbPLZ, Ort und Straße gefunden, aber nicht das Gebäude (Hausnr.). Oder das Postfach liegt außerhalb des bekannten Nummernkreises.
ungültig, PLZ und Ort OKrotPLZ und Ort gefunden, Straße nicht
ungültig, mehrdeutigrotFalsche Adresse, es gibt mehrere, nicht eindeutige Möglichkeiten
ungültigrotungültige Adresse (oder noch nicht bekannt, Neubaugebiet)
Bitte Eingabe prüfenrotDubiose Eingabe (request), es findet keine Prüfung statt. Die Adresse sollte manuell geprüft werden. (Firmen-) Namen, E-Mail-Adressen oder sonstige unplausible Einträge in der Anfrage.

Ergebniscode Adress-Check (5stellig)

Stelle im CodeZahlBedeutung
1. Stelle = PLZ0PLZ nicht gefunden
 1PLZ bei request und response stimmt überein
 2Erste 4 Stellen der PLZ stimmen überein
 3Erste 3 Stellen der PLZ stimmen überein
 4Erste 2 Stellen der PLZ stimmen überein
 5Erste Stelle der PLZ stimmt überein
 6Zahlendreher in PLZ
 7PLZ geändert
 8PLZ unvollständig eingegeben oder PLZ nicht geprüft, weil Request dubios ist.
 9PLZ in request leer
2. Stelle = Ort0Ort nicht gefunden
 1Ort bei request und response stimmt überein
 2Ort über Ortsteil gefunden
 3Ort mit leichter Phonetik gefunden
 4Ort mit Phonetik gefunden
 7Ort geändert
 8Ort nicht geprüft, Eingabe dubios.
 9Ort in request leer
3. Stelle = Straße0Strasse nicht gefunden
 1Strasse in request und response identisch
 2Strasse mit leichter Phonetik gefunden
 3Strasse mit Phonetik gefunden
 5Strasse war abgekürzt
 6Strasse nicht geprüft/ Eingabe dubios oder Packstation
 7Strasse geändert
 8Strasse ist optional (Größempfänger-PLZ)
 9Strasse in request leer
4. Stelle = Hausnummer0Hausnummer nicht gefunden oder Postfach
 1Hausnummer korrekt
 2Hausnummernbereich ok
 6Hausnummer nicht geprüft/ Eingabe dubios  oder Packstation
 8Hausnummer ist ein Bereich von ... bis ..
 9Hausnummer war leer/ konnte nicht aus Strasse extrahiert werden.
5. Stelle = result1OK (points = 100)
 2OK, sicher gefunden (points von 90 bis 99)
 3unsicher gefunden (points von 70 bis 89)
 4unsicher, PLZ+Ort OK, aber keine Strasse oder Postfach/ Packstation im request
 5ungültig, PLZ+ Ort OK
 6ungültig, mehrdeutig
 8Bitte Eingabe prüfen. Dubiose Feldinhalte im Request.
 9ungültig (points < 70)

Ergebnisse Fake-Check

resulttexttrafficlightBedeutung
OKgruenOK, kein Fake gefunden.
Fake-Warnung (Vorname)!gelbVorname dubios, in Fake-Liste mit mittlerer Negativbewertung.
Fake-Warnung (Vorname)!rotVorname dubios, in Fake-Liste mit hoher Negativbewertung.
Fake-Warnung (Nachname)!gelbNachname dubios, in Fake-Liste mit mittlerer Negativbewertung.
Fake-Warnung (Nachname)!rotNachname dubios, in Fake-Liste mit hoher Negativbewertung.
Fake-Warnung (Namenszeile)!gelbKombi aus Vor- und Nachname dubios, in Fake-Liste mit mittlerer Negativbewertung.
Fake-Warnung (Namenszeile)!rotKombi aus Vor- und Nachname dubios, in Fake-Liste mit hoher Negativbewertung.

Hinweis für "trafficlight" gelb: Hier sind unter anderem Vor- und Nachnamen von Prominenten hinterlegt. Dabei kann es sich um "Allerweltsnamen" handeln, die im deutschsprachigem Raum häufig vorkommen. "Michael Schumacher" z.B. haben wir deshalb aus der Fake-Liste heraus genommen. Namen, die seltener vorkommen, aber oft auch weniger bekannt sind, sind noch enthalten. Entscheiden Sie selbst, wie Sie mit diesen Fake-Warnungen umgehen möchten. Wir haben keine eindeutige Empfehlung.

Ergebnisse Namens-Check (B2C)

resulttexttrafficlightBedeutung
OKgruenAlles wie Eingabe
Korrektur durchgeführtgelbAbweichungen zwischen Ein- und Ausgabe:
Groß-Kleinschreibweise oder Vor-und Nachnamen getauscht oder Anrede ergänzt/ korrigiert oder Titel extrahiert.
Dubiose EingaberotDie Eingabe der Namensfelder enthält Bestandteile der Adresse, Dopplungen oder eine E-Mail Adresse. Es werden keine Änderungen vorgenommen.

Ergebnisse E-Mail-Check und erweiterter E-Mail-Check

resulttexttrafficlight
OKgruen
E-Mail syntaktisch OK, Mailserver mag jedoch Empfänger nicht (E-Mail-Postfach-Prüfung). *gelb
E-Mail syntaktisch OK. E-Mail-Postfach-Prüfung nicht eindeutig. Blacklisting oder ungültiger Empfänger. *gelb
E-Mail syntaktisch OK. Mailserver lässt die E-Mail-Postfach-Prüfung nicht zu (Spam-Filter). *gelb
Mail-Server antwortet auch nach 30 Sekunden noch nicht (E-Mail-Postfach-Prüfung)gelb
Domain weist auf Wegwerf-Email-Adresse hingelb
E-Mail OK, aber dubiosgelb
E-Mail OK, aber auf Top Level Domain Ebenegelb
E-Mail OK, aber Top Level Domain ist numerischgelb
E-Mail OK, aber enthält Teil in Anführungszeichengelb
E-Mail OK, aber enthält Kommentargelb
E-Mail OK, aber enthält fließendes Leerzeichengelb
E-Mail OK, aber mit numerischer Adresse, keine Domaingelb
E-Mail OK, aber enthält ein :: das nur eine Nullgruppe auslässtgelb
E-Mail ist ungültigrot
E-Mail ist zu langrot
E-Mail hat kein @-Zeichenrot
Ungültiges Zeichen im lokalen Teilrot
E-Mail hat keinen lokalen Teilrot
E-Mail hat keinen Domain-Teilrot
E-Mail beginnt oder endet mit einem Punkt oder hat 2 Punkte hintereinanderrot
E-Mail beinhaltet ungültige Zeichen in einem Kommentarrot
E-Mail beinhaltet ein Zeichen, das escaped werden muss, aber nicht istrot
Der lokale Teil der E-Mail ist zu langrot
Die numerische Adresse hat ein falsches Präfixrot
Der Domain-Teil enhält ein leeres Elementrot
Der Domain-Teil enhält ein Element, das zu lang istrot
Der Domain-Teil enhält ein ungültiges Zeichenrot
Der Domain-Teil ist zu langrot
Die IPv6-Adresse enthält zu viele Gruppenrot
Die IPv6-Adresse enthält die falsche Anzahl von Gruppenrot
Die IPv6-Adresse enthält eine falsche Gruppe von Zeichenrot
Die IPv6-Adresse enthält zuviele :: Sequenzenrot
Die IPv6-Adresse beginnt mit einem einzelnen Punktrot
Die IPv6-Adresse endet mit einem einzelnen Punktrot
Top-Level-Domain ist ungültigrot

Die Prüfung EMX (E-Mail-Check extended = Postfach-Check) nimmt zusätzlich Kontakt zum Mailserver auf und prüft, ob eine E-Mail zugestellt werden kann. Dies dauert einen Augenblick länger als die reine Syntax-Prüfung (EM).

* Info: Kann auch bedeuten, dass der Provider die Prüfung nicht zulässt oder Adresslabor generell blockt (Blacklisting).

Ergebnisse Telefonverzeichnis

resulttextpointstrafficlightBedeutung
OK, Person und Telefonnr. stimmen überein100gruenBestätigung einer Person durch Telefonverzeichnis
OK, Haushalt oder Firma und Telefonnr. stimmen überein90gruenBestätigung des Haushalts oder der Firma mit übereinstimmender Telefonnummer
Person mit abweichender Telefonnr. gefunden80gruenTelefonnummer kann angereichert werden.
Telefonnr. gefunden, Inverssuche von Teilnehmer verweigert80gruenTelefonnummer ist eingetragen, der Teilnehmer hat aber der Rückwärtssuche widersprochen. Adressdaten und Name dürfen nicht zurückgemeldet werden.
Haushalt oder Firma mit abweichender Telefonnr. gefunden70gruenTelefonnummer (Festnetz) kann angereichert werden. Vorsicht bei Mobilnummern
Telefonnr. mit abweichenden/fehlenden Daten gefunden60gruenEintrag über Reverse-Suche gefunden, aber mit abweichender oder unvollständiger Adresse
Person in Strasse gefunden50gruenEindeutige Zuordnung nicht möglich
Unsichere Treffer gefunden40, 30, 20, 10gelbEindeutige Zuordnung nicht möglich
Keinen Eintrag im Telefonverzeichnis gefunden0rotNichts gefunden

Ergebnisse Ust-IdNr-Check

resulttexttrafficlightBedeutung
OKgruenUst-IdNr. syntaktisch korrekt und vom jeweiligen Land als vergeben und gültig eingestuft (nur VATIDX)
Syntaktisch OKgelbPrüfziffer und Format OK
Prüfziffer oder Format falschrotPrüfziffer oder Format falsch
UngültigrotSyntaktisch ok, jedoch wurde die Ust-IdNr. vom vergebenden Land als ungültig eingestuft

Die Prüfung "VATIDX" (Ust-IdNr.-Check extended) fragt zusätzlich beim jeweils zuständigen EU-Land an, ob die Nummer gültig und vergeben ist. In den meisten Ländern erhält man auch den zur Umsatzsteuer-ID zughörigen Firmennamen und Adresse (Ausnahmen sind z.B. Deutschland und Frankreich). Ist der jeweilige Dienst des Landes zur Zeit online nicht erreichbar, wird nur die Prüfung "VATID" ausgeführt. Das beste Ampel-Ergebnis ist in dem Fall "gelb".

Beispielprogramme