Was bietet der Webservice Ortsinformationen?

 

Vorteile des Webservice Ortsinformationen

• Schnelle Ermittlung von Netzbetreibern, Grundversorgern und Netzgebieten anhand von PLZ oder vollständiger Adresse
• Validierung und Korrektur von Adressdaten anhand der vierteljährlich importierten Daten der Deutschen Post durch intelligente Ähnlichkeitsprüfung 
• Unterstützung komplexer energiewirtschaftlicher Prozesse wie Netzgebietsermittlung, Grundversorgersuche und Marktgebietszuordnung
• Reduzierung manueller Recherche- und Pflegeaufwände durch automatisierte Datenbereitstellung
• Zugriff auf aktuelle und historisierte Gebietsdaten inklusive Änderungsinformationen
• Flexible Nutzung über REST- und SOAP-Schnittstellen, inklusive Swagger-Dokumentation
• Einfache Integration in Vertriebsportale, Tarifrechner, CRM- und Abrechnungssysteme
• Unterstützung bei der Ermittlung von Hauptnetzgebieten und Mehrfachzuordnungen in komplexen Versorgungsgebieten
• Effiziente Verarbeitung großer Datenmengen durch standardisierte und automatisierte Schnittstellenkommunikation

 

Anwendungsfälle

Netzbetreiberermittlung für Angebotskalkulation

Beschreibung:

Die API ermittelt anhand von Postleitzahl, Ort, Straße und optional Hausnummer den zuständigen Netzbetreiber für Strom oder Gas. Dabei können auch mehrere Netzgebiete innerhalb einer PLZ automatisch erkannt und weiter eingegrenzt werden.

Nutzen:

• Präzise Tarif- und Netzentgeltkalkulation bereits im Angebotsprozess
• Automatisierte Auswahl des korrekten Netzbetreibers
• Vermeidung fehlerhafter Angebotsberechnungen
• Verbesserte Conversion durch schnelle und automatisierte Datenermittlung

Netzbetreiberermittlung für Abrechnung

Beschreibung:

Für Abrechnungsprozesse kann die API anhand vollständiger Adressdaten den zuständigen Netzbetreiber und die zugehörigen Netzgebiete eindeutig bestimmen.

Nutzen:

• Sichere Zuordnung für Marktkommunikation und Abrechnung
• Reduzierung manueller Prüfprozesse
• Höhere Datenqualität bei Lieferantenwechsel und Billing
• Minimierung von Rückläufern und Klärfällen

Hausnummernscharfe Ermittlung von Netzbetreiber und Grundversorger

Beschreibung:

Der Webservice ermöglicht die Ermittlung von Netzbetreibern, Grundversorgern, Marktgebieten und Regelzonen bis auf Hausnummernebene. Dadurch können auch komplexe Gebietsüberschneidungen innerhalb derselben Straße oder PLZ präzise aufgelöst werden. Auch unterjährige Änderungen an Netzgebieten durch Übernahmen und Zusammenschlüsse von Netzbetreibern werden berücksichtigt.

Nutzen:

• Höchstmögliche Genauigkeit bei der Gebietszuordnung
• Unterstützung komplexer Versorgungsgebiete und Mehrfachzuordnungen
• Korrekte Zuordnung von Tarifen und Grundversorgung
• Optimierte Prozesse für Vertrieb, CRM und Abrechnungssysteme

Adressvalidierung auf Basis der Daten der Deutschen Post

Beschreibung:

Die API validiert Adressen gegen Postdaten und erkennt unterschiedliche Schreibweisen von Orten, Ortsteilen und Straßen mithilfe einer Ähnlichkeitsprüfung (Dice-Algorithmus).

Nutzen:

• Verbesserung der Datenqualität bereits bei der Eingabe
• Reduzierung fehlerhafter oder unvollständiger Adressen
• Automatische Vorschläge bei Tippfehlern oder abweichenden Schreibweisen
• Weniger Abbrüche in Online-Strecken und Portalen

Konzessionsabgabenermittlung pro Netzbetreiber

Beschreibung:

Der Webservice liefert die gültigen Konzessionsabgaben für Strom und Gas je Gemeinde und Netzbetreiber inklusive historischer Gültigkeitszeiträume. Individuelle Konzessionsabgaben, beispielsweise bei den Lechwerken oder den Bayernwerken, werden ebenfalls berücksichtigt.

Nutzen:

• Automatisierte Berücksichtigung korrekter Konzessionsabgaben
• Unterstützung rechtskonformer Tarif- und Preisberechnungen
• Historisierte Daten für rückwirkende Prüfungen und Abrechnungen
• Reduzierung manueller Pflege von Abgabesätzen

Ermittlung von Grundversorgungsgebieten

Beschreibung:

Die API identifiziert den zuständigen Grundversorger für Strom und Gas anhand von PLZ, Ort, Straße und Hausnummer.

Nutzen:

• Korrekte Darstellung von Grundversorgungstarifen
• Unterstützung gesetzlicher Anforderungen im Energievertrieb
• Automatisierte Zuordnung in Tarifrechnern und Vergleichsportalen
• Vermeidung falscher Anbieterzuordnungen

Ermittlung von Marktgebieten und Regelzonen

Beschreibung:

Zusätzlich zu Netzgebieten liefert der Webservice Informationen zu Gasmarktgebieten, Bilanzierungsgebieten und Regelzonen.

Nutzen:

• Unterstützung energiewirtschaftlicher Backend-Prozesse
• Relevante Daten für Bilanzierung und Marktkommunikation
• Einheitliche Datengrundlage für verschiedene Systeme
• Vereinfachung komplexer energiewirtschaftlicher Zuordnungen

Straßen-, Orts- und Postleitzahlensuche

Beschreibung:

Die API ermöglicht die Suche von Straßen zu Orten und PLZ sowie die Rückwärtssuche von Orten oder Postleitzahlen.

Nutzen:

• Unterstützung komfortabler Eingabemasken und Autocomplete-Funktionen
• Vereinfachte Nutzerführung in Portalen
• Schnellere und fehlerfreie Adresserfassung
• Verbesserte Benutzerfreundlichkeit in Online-Anwendungen

 

Technische Dokumentation

Für die Integration der Ortsinfo API empfehlen wir die Nutzung der bereitgestellten OpenAPI-/Swagger-Dokumentation. Über die Swagger-Oberfläche erhalten Entwickler einen zentralen und interaktiven Zugriff auf sämtliche Methoden des Ortsinfo Webservice inklusive aller Parameter, Request- und Response-Strukturen sowie Beispielaufrufe.

Die Swagger-Dokumentation kann nach Freischaltung des Zugangs direkt über die bereitgestellten URLs aufgerufen werden und ermöglicht es, API-Funktionen unmittelbar im Browser zu testen und die Integration effizient umzusetzen.

Produktiver Service:

https://webservice1.ag-server.de/getagWSCore/swagger-ui.html?urls.primaryName=Ortsinfo%20Webservice%201.3.0

Test-Service:

https://webservicetest1.ag-server.de/getagWSCore/swagger-ui.html?urls.primaryName=Ortsinfo%20Webservice%201.3.0 

Es stehen detaillierte Informationen zu Authentifizierung, Datenmodellen, Fehlercodes sowie Test- und Produktivumgebungen zur Verfügung.

Für bestehende Integrationen können zusätzlich klassische SOAP- und REST-Beschreibungen wie WSDL- oder WADL-Dateien genutzt werden. Ebenso stehen Beispielprojekte für Tools wie SoapUI zur Verfügung.

Weitere technische Merkmale und Anforderungen, wie z.B. zu Zertifikaten, Authentifizierung, Freischaltung oder Hinweise zum Anfrageverhalten finden Sie in der Technischen Dokumentation zu den Webservices.

 

Methodenübersicht

getVersion()

-> Liefert die Version des Service als Zeichenkette zurück.

getKonzessionsabgabeNB

Eingabe: <KonzessionsabgabeParameterNB>

Ausgabe: <KonzessionsabgabeNB>

-> Gibt eine Liste von Konzessionsabgaben zurück, die seit dem Stichtag in der Gemeinde gültig waren und sind, nach Netzbetreibern getrennt.

getValidierungByAdresse

Eingabe: <AuthRequest>, <ValidierungByAdresseParameter>

Ausgabe: <Adressinfo>

-> Gibt die Adressdaten der Post zurück. Dabei wird der String einer Ähnlichkeitsprüfung (Dice Algorithmus) unterzogen. Damit ist es möglich, bei unterschiedlichen Schreibweisen von Orten, Ortsteilen oder Straßen die gewünschten Daten zu erhalten.

getOrtsinfoExtended

Eingabe: <AuthRequest>, <OrtsinfoExtendedParameter>

Ausgabe: <OrtsinfoExtended>

-> Gibt eine Liste mit allen erweiterten ortsbezogenen Informationen zurück.

getStrassenByPlzOrt

Eingabe: <AuthRequest>, <StrassenByPlzOrtParameter>

Ausgabe: <Adressinfo>

-> Gibt eine Liste von Straßen aus Postleitzahl und Ort zurück.

getOrteByPlz

Eingabe: <AuthRequest>, <OrteByPlzParameter>

Ausgabe: <Adressinfo>

-> Gibt eine Liste von Orten aus Postleitzahl zurück.

getPlzsByOrt

Eingabe: <AuthRequest>, <PlzsByOrtParameter>

Ausgabe: <Adressinfo>

-> Gibt eine Liste aus Postleitzahlen aus Ort zurück.

getParameter

Eingabe: <AuthRequest>

Ausgabe: <Parameter>

-> Gibt die im Webservice genutzten Parameter mit Ihrer ID und Bezeichnung zurück.

getOrtsinfoDelta

Eingabe: <AuthRequest>, <OrtsinfoDeltaParameter>

Ausgabe: <OrtsinfoDelta>

-> Gibt die Veränderungen des Gebietes auf Lokationsebene zurück.

Wenn zu einem letztenUpdate mehrere status vergeben wurden, dann soll zuerst der status=0 (Lokation löschen) und erst danach status=1 (Lokation hinzufügen) genutzt werden.

getOrtsinfoRangGebiet

Eingabe: <AuthRequest>, <OrtsinfoRangGebietParameter>

Ausgabe: <OrtsinfoRangGebiet>

-> Gibt die Liste von Gebieten zurück, die sich geändert haben.

getOrtsinfoGebietAenderungen

Eingabe: <AuthRequest>, <OrtsinfoGebietAenderungenParameter>

Ausgabe: <OrtsinfoGebietAenderungen>

-> Gibt die Liste von Gebieten zurück, die sich geändert haben.

 

 

Fehlermeldungen

Wenn Fehler auftreten, wird ebenfalls das Ergebnisobjekt zurückgeben. Dieses beinhaltet in der ersten Ebene einen FehlerCode. Die einzelnen Codes werden nachstehend aufgelistet mit der entsprechenden Fehlerbegründung. 

FehlerCode	Beschreibung
1	OK, Berechnung erfolgt.
400	Diese Funktion wird zur Zeit nicht unterstützt.
500	Der Nutzer konnte nicht authentifiziert werden.
501	Nutzer konnte authentifiziert werden, hat aber nicht die erforderlichen Rechte.
600	Zu den übergebenen Parametern konnten keine Daten gefunden werden.
601	Zur übergebenen Kombination aus Datum und Gkz konnten keine Daten gefunden werden.
602	Zur übergebenen Kombination aus Datum und Plz konnten keine Daten gefunden werden.
603	Zur übergebenen Kombination aus Datum und Ort konnten keine Daten gefunden werden.
604	Zur übergebenen Kombination aus Datum und Ortsteil konnten keine Daten gefunden werden.
605	Zur übergebenen Kombination aus Datum und Strasse konnten keine Daten gefunden werden.
606	Zur übergebenen Kombination aus Datum und Hausnummer konnten keine Daten gefunden werden.
607	Zur übergebenen Kombination aus Datum, Gkz und Plz konnten keine Daten gefunden werden.
608	Zur übergebenen Kombination aus Datum, Gkz, Plz und Lasttyp konnten keine Daten gefunden werden.
609	Zur übergebenen Kombination aus Datum, Plz und Lasttyp konnten keine Daten gefunden werden.
610	Es wurde keine Plz übergeben, oder das Format der Plz ist ungültig.
611	Das Format der übergebenen Gkz ist ungültig.
612	Es wurde ein falscher Wert in der Eigenschaft idGebietsTyp übergeben.
613	Es wurde ein falscher Wert in der Eigenschaft Datenbankstand übergeben.
614	Es wurde ein falscher Wert in der Eigenschaft idGebiet übergeben.
615	Zum übergebenen Ort konnten keine Daten gefunden werden.
616	Der übergebene Ort ist ungültig.
617	Die übergebene Kombination aus Medium und idGebietsTyp ist ungültig.
701	Interner Datenfehler!

 

Objektdefinitionen

AuthRequest

Parameter	Typ	Beschreibung
auth_LoginName	String	Benutzername
auth_Passwort	String	Passwort

KonzessionsabgabeParameterNB

Parameter	Typ	Beschreibung
gkz	string	Gemeindekennziffer
nb (optional)	string	13-stellige VDEWID, DVGWID oder ILN eines Netzbetreibers
stichtag (optional)	date	Stichtag, ab wann die Konzessionsabgabe mindestens gültig sein soll

KonzessionsabgabeNB

Parameter	Typ	Beschreibung
fehlerCode	int	StatusID für Fehler
fehlerMeldung (optional)	string	Fehlertext
fehlerMeldungLength	int	Anzahl Objekte fehlerMeldung
itag	string	Interne Kennzeichnung zur Hilfe bei der Fehlersuche (beachte Fehlersuche)
kaGas	object	Siehe Unterobjekt KaGas
kaGasLength	int	Anzahl Objekte kaGas
kaStrom	object	Siehe Unterobjekt KaStrom
kaStromLength	int	Anzahl Objekte kaStrom

 

KonzessionsabgabeNB – Unterobjekte

KaGas und KaStrom

Parameter	Typ	Beschreibung
ka	object	Siehe Unterobjekt Ka
kaLength	int	Anzahl Objekte ka
nb (optional)	string	Verbandsnummer des Netzbetreibers

Ka

Parameter	Typ	Beschreibung
gueltigBis (optional)	date	Gültigkeitsende
gueltigVon (optional)	date	Gültigkeitsbeginn
kaTyp (optional)	string	Art der KA nach UTILMD SA, TA, TS, TK bei gesetzl. Höchstgrenzen SAS, TAS, TSS, TKS bei individuellen Vereinbarungen
wert	double	Höhe der Konzessionsabgabe in ct/kWh

ValidierungByAdresseParameter

Parameter	Typ	Beschreibung
hausnummer (optional)	string	Hausnummer
ort (optional)	string	Ort
ortsteil (optional)	string	Ortsteil
plz	string	Postleitzahl
strasse	string	Straße

Adressinfo

Parameter	Typ	Beschreibung
fehlerCode	int	FehlerCode für Fehler
fehlerMeldung (optional)	string	Textuelle Fehlermeldung
fehlerMeldungLength	int	Anzahl Objekte fehlerMeldung
input (optional)	object	siehe Objekt AdressinfoParameter
itag (optional)	string	Interne Kennzeichnung zur Hilfe bei der Fehlersuche (beachte Fehlersuche)
ort	object	siehe Objekt Ort
ortLength	int	Anzahl Objekte ort
strasse	object	siehe Objekt Strasse
strasseLength	int	Anzahl Objekte strasse
validation	object	siehe Objekt Validation

AdressinfoParameter

Parameter	Typ	Beschreibung
strassenRequest	object	siehe Objekt StrassenRequest
validationsRequest	object	siehe Objekt ValidationsRequest

StrassenRequest

Parameter	Typ	Beschreibung
ort	string	Ort
plz	string	Postleitzahl

OrtsinfoExtendedParameter

Parameter	Typ	Beschreibung
gkz (optional)	string	Gemeindekennziffer
gueltigBis (optional)	date	Gültigkeitsende
gueltigVon (optional)	date	Gültigkeitsbeginn
hausnummer (optional)	string	Hausnummer
idGebietsTyp (optional)	int	Einschränkung Gebietstyp (siehe Methode getParameter)
idGebietsTypLength (optional)	int	Anzahl Objekte idGebietsTyp
medium (optional)	int	0 Strom 1 Erdgas
ort (optional)	string	Ort
ortsteil (optional)	string	Ortsteil
plz	string	Postleitzahl
strasse (optional)	string	Straße

OrtsinfoExtended

Parameter	Typ	Beschreibung
bilanzierungsgebiet	object	siehe Objekt DetailsObj
bilanzierungsgebietLength	int	Anzahl Objekte bilanzierungsgebiet
fehlerCode	int	FehlerCode für Fehler
fehlerMeldung	string	textuelle Fehlermeldung
fehlerMeldungLength	int	Anzahl Objekte fehlerMeldung
gasGrundversorgungsgebiet	object	siehe Objekt DetailsObj
gasGrundversorgungsgebietLength	int	Anzahl Objekte gasGrundversorgungsgebiet
gasMarktgebiet	object	siehe Objekt DetailsObj
gasMarktgebietLength	int	Anzahl Objekte gasMarktgebiet
gasNetzgebiet	object	siehe Objekt DetailsObj
gasNetzgebietLength	int	Anzahl Objekte gasNetzgebiet
input	object	Siehe Objekt OrtsinfoExtendedParameter
itag	string	Interne Kennzeichnung zur Hilfe bei der Fehlersuche (beachte Fehlersuche)
regelzone	object	siehe Objekt DetailsObj
regelzoneLength	int	Anzahl Objekte regelzone
stromGrundversorgungsgebiet	object	siehe Objekt DetailsObj
stromGrundversorgungsgebietLength	int	Anzahl Objekte stromGrundversorgungsgebiet
stromNetzgebiet	object	siehe Objekt DetailsObj
stromNetzgebietLength	int	Anzahl Objekte stromNetzgebiet
uebertragungsNetzgebiet	object	siehe Objekt DetailsObj
uebertragungsNetzgebietLength	int	Anzahl Objekte uebertragungsNetzgebiet

StrassenByPlzOrtParameter

Parameter	Typ	Beschreibung
ort	string	Ort
plz	string	Postleitzahl

DetailsObj

Parameter	Typ	Beschreibung
eic	string	EIC Code Bilanzkreis Strom
grundversorger	object	siehe Objekt DetailsVersorger
grundversorgerLength	int	Anzahl Objekte grundversorger
interneID	int	Interne ID
lokation	object	siehe Objekt Lokation
lokationLength	int	Anzahl Objekte lokation
marktgebietDetails	object	siehe Objekt DetailsMg
name	string	Name
netzbetreiber	object	Siehe Objekt DetailsVersorger
netzbetreiberLength	int	Anzahl Objekte netzbetreiber
refID	int	ReferenzierungsID (ist vorhanden um z.B. einem Netzbetreiber den natürlichen Grundversorger zuzuordnen)
refIDLength	int	Anzahl Objekte refID
refName	string	Name Referenzierung
rzVerantwortlicher	object	siehe Objekt DetailsRz

DetailsMg

Parameter	Typ	Beschreibung
gasArt	string	Gasart
virtuellerHandelspunkt	string	Virtueller Handelspunkt

DetailsVersorger

Parameter	Typ	Beschreibung
gueltigBis	date	Gültigkeitsende
gueltigVon	date	Gültigkeitsbeginn
interneID	int	Interne NetzbetreiberID
name	string	Firmierung Netzbetreiber
verbandsnummer	string	Verbandsnummer Netzbetreiber

Lokation

Parameter	Typ	Beschreibung
gkz	string	Gemeindekennziffer
gueltigBis	date	Gültigkeitsende
gueltigVon	date	Gültigkeitsbeginn
hnrBis	string	Ende Hausnummerintervall
hnrVon	string	Beginn Hausnummerintervall
letztesUpdate	decimal	letztes Änderungsdatum der Lokation
ort	string	Ort
ortsteil	string	Ortsteil
plz	string	Postleitzahl
rangGebiet	int	Platzhalter, um später den Lokationen Ränge vergeben zu können
status	string	gibt für Delta-Betrachtungen an, ob Lokation gelöscht (=0) oder hinzugefügt (=1) werden muss.
strasse	string	Straße

DetailsRz

Parameter	Typ	Beschreibung
eic	string	EIC Code Regelzone
name	string	Name Regelzone

OrteByPlzParameter

Parameter	Typ	Beschreibung
plz	string	Postleitzahl

PlzsByOrtParameter

Parameter	Typ	Beschreibung
ort	string	Ort

Ort

Parameter	Typ	Beschreibung
alort	string	ALORT der Örtlichkeit
gkz	string	Gemeindekennziffer
ortsname	string	Ort
ortsteil	string	Ortsteil
ortsteilLength	int	Anzahl Objekte ortsteil
plz	string	Postleitzahl
plzLength	int	Anzahl Objekte plz

Strasse

Parameter	Typ	Beschreibung
hausnummer	object	siehe Objekt Hausnummer
hausnummerLength	int	Anzahl Objekte hausnummer
name	string	Straßenname

Hausnummer

Parameter	Typ	Beschreibung
bis	string	Hausnummer bis
typ	string	Typ
von	string	Hausnummer von

Validation

Parameter	Typ	Beschreibung
ort	object	siehe Objekt OrtValidation
suggestOrt	object	siehe Objekt OrtValidation
suggestOrtLength	int	Anzahl Objekte suggestOrt
validOrt	boolean	Ist Übergebener Ort in Postdaten vorhanden?
validPlz	boolean	Ist Übergebene Postleitzahl in Postdaten vorhanden?

ValidationsRequest

Parameter	Typ	Beschreibung
hausnummer	string	Hausnummer
ort	string	Ort
ortsteil	string	Ortsteil
plz	string	Postleitzahl
strasse	string	Strasse

OrtValidation

Parameter	Typ	Beschreibung
hasNoOrtsteil	object	siehe Objekt HasNoOrtsteil
hasOrtsteil	object	siehe Objekt HasOrtsteil
name	string	Name des Ortes
noOrtsteilRequested	object	siehe Objekt NoOrtsteilRequested

HasNoOrtsteil

Parameter	Typ	Beschreibung
strasse	object	siehe Objekt StrasseValidation
suggestStrasse	object	siehe Objekt StrasseValidation
suggestStrasseLength	int	Anzahl Objekte suggestStrasse
validStrasse	boolean	Ist Übergebene Strasse in Postdaten vorhanden?

StrasseValidation

Parameter	Typ	Beschreibung
name	string	Name der Strasse
suggestHausnummer	object	siehe Objekt HausnummerValidation
suggestHausnummerLength	int	Anzahl Objekte suggestHausnummer
validHausnummer	boolean	Ist Übergebene Hausnummer in Postdaten vorhanden?

HausnummerValidation

Parameter	Typ	Beschreibung
bis	string	Hausnummer bis
typ	string	Typ
von	string	Hausnummer von

HasOrtsteil

Parameter	Typ	Beschreibung
ortsteil	object	siehe Objekt OrtsteilValidation
suggestOrtsteil	object	siehe Objekt OrtsteilValidation
suggestOrtsteilLength	int	Anzahl Objekte suggestOrtsteil
validOrtsteil	boolean	Ist Übergebener Ortsteil in Postdaten vorhanden?

OrtsteilValidation

Parameter	Typ	Beschreibung
name	string	Name des Ortsteils
strasse	object	siehe Objekt StrasseValidation
suggestStrasse	object	siehe Objekt StrasseValidation
suggestStrasseLength	int	Anzahl Objekte suggestStrasse
validStrasse	boolean	Ist übergebene Straße in Postdaten vorhanden?

NoOrtsteilRequested

Parameter	Typ	Beschreibung
strasse	object	Siehe Objekt StrasseValidation
suggestStrasse	object	Siehe Objekt StrasseValidation
suggestStrasseLength	int	Anzahl Objekte SuggestStrasse
validStrasse	boolean	Ist übergebene Straße in Postdaten vorhanden?

Param

Parameter	Typ	Beschreibung
beschreibung	string	Beschreibung des Parameters
id	int	ID des Parameters

Parameter

Parameter	Typ	Beschreibung
fehlerCode	int	FehlerCode für Fehler
fehlerMeldung	string	Textuelle Fehlermeldung
fehlerMeldungLength	int	Anzahl Objekte fehlerMeldung
gebietsTyp	param	Siehe Objekt GebietsTyp
gebietsTypLength	int	Anzahl Objekte gebietsTyp
itag (optional)	string	Interne Kennzeichnung zur Hilfe bei der Fehlersuche (beachte Fehlersuche)
medium	int	0 Strom 1 Erdgas
mediumLength	int	Anzahl Objekte medium

OrtsinfoRangGebietParameter

Parameter	Typ	Beschreibung
gkz (optional)	string	Gemeindekennziffer
gueltigBis (optional)	date	Gültigkeitsende
gueltigVon (optional)	date	Gültigkeitsbeginn
idGebietsTyp	int	Einschränkung Gebietstyp (siehe Methode getParameter)
plz	Int	Postleitzahl

OrtsinfoRangGebiet

Parameter	Typ	Beschreibung
fehlerCode	int	fehlerCode für Fehler
fehlerMeldung	string	textuelle Fehlermeldung
fehlerMeldungLength	int	Anzahl Objekte fehlerMeldung
gebiet	object	siehe Objekt DetailsObj
gebietLength	int	Anzahl Objekte gebiet
input	object	siehe Objekt OrtsinfoRangGebietParameter
itag	string	Interne Kennzeichnung zur Hilfe bei der Fehlersuche (beachte Fehlersuche)

OrtsinfoDeltaParameter

Parameter	Typ	Beschreibung
datenbankstand	decimal	Version des Datenbankstands
idGebiet	int	ID des Gebiets
idGebietLength	int	Anzahl Objekte idGebiet
idGebietsTyp	int	Einschränkung Gebietstyp (siehe Methode getParameter)

OrtsinfoDelta

Parameter	Typ	Beschreibung
fehlerCode	int	fehlerCode für Fehler
fehlerMeldung	string	textuelle Fehlermeldung
fehlerMeldungLength	int	Anzahl Objekte fehlerMeldung
gebiet	object	siehe Objekt DetailsObj
gebietLength	int	Anzahl Objekte gebiet
input	object	siehe Objekt OrtsinfoDeltaParameter
itag	string	Interne Kennzeichnung zur Hilfe bei der Fehlersuche (beachte Fehlersuche)

OrtsinfoGebietAenderungenParameter

Parameter	Typ	Beschreibung
datenbankstand	decimal	Version des Datenbankstands
idGebietsTyp	int	Einschränkung Gebietstyp (siehe Methode getParameter)

OrtsinfoGebietAenderungen

Parameter	Typ	Beschreibung
fehlerCode	int	fehlerCode für Fehler
fehlerMeldung	string	textuelle Fehlermeldung
fehlerMeldungLength	int	Anzahl Objekte fehlerMeldung
idGebiet	int	ID des Gebiets
idGebietLength	int	Anzahl Objekte idGebiet
input	object	siehe Objekt OrtsinfoGebietAenderungenParameter
itag	string	Interne Kennzeichnung zur Hilfe bei der Fehlersuche (beachte Fehlersuche)

GebietsTyp

Parameter	Typ	Beschreibung
beschreibung	string	Beschreibung des Gebietstyps
id	int	ID des Gebietstyps

Hinweis: Wenn ausschließlich Stromnetze mit Niederspannung ausgegeben und gleichzeitig geschlossene Verteilnetze ausgeschlossen werden sollen, können beide Anforderungen in einem einzigen Request abgebildet werden.

...

"idGebietsTyp": [13, 15]

...

idGebietsTyp	Gebietstyp	Beschreibung
1	StromNetzgebiet	Gebiet eines Stromverteilnetzes, in dem ein Netzbetreiber die Versorgung sicherstellt.
2	GasNetzgebiet	Gebiet eines Gasverteilnetzes, in dem ein Netzbetreiber die Versorgung sicherstellt.
3	StromGrundversorgungsgebiet	Gebiet, in dem ein Grundversorger Haushaltskund:innen gesetzlich mit Strom versorgen muss.
4	GasGrundversorgungsgebiet	Gebiet, in dem ein Grundversorger Haushaltskund:innen gesetzlich mit Gas versorgen muss.
5	GasMarktgebiet	Übergeordnetes Gasmarktgebiet mit einheitlichen Regeln für Bilanzierung, Transport und Handel.
6	Bilanzierungsgebiet	Virtuelles energiewirtschaftliches Gebiet zur bilanziellen Gegenüberstellung von Einspeisung und Entnahme.
7	Regelzone	Gebiet eines Übertragungsnetzbetreibers, der für Netzstabilität, Frequenzhaltung und Systemverantwortung zuständig ist.
8	ÜbertragungsNetzgebiet	Großräumiges Stromnetzgebiet der Höchstspannungsebene für den überregionalen Energieaustausch.
13	StromNetzgebietExklGeschlossenesVerteilnetz	Stromnetzgebiet eines Verteilnetzbetreibers ohne geschlossene Verteilnetze (z. B. Areal- oder Objektnetze in Industrieparks, Flughäfen, Häfen).
14	GasNetzgebietExklGeschlossenesVerteilnetz	Gasnetzgebiet eines Verteilnetzbetreibers ohne geschlossene Verteilnetze, etwa Areal- oder Objektnetze in Industrieparks, Flughäfen oder Hafenanlagen.
15	StromNetzgebietNurNiederspannung	Gebiet eines Stromverteilnetzes indem nur Netzentgelte mit Niederspannung berücksichtigt werden.
16	GasNetzgebietNurNiederdruck	Gebiet eines Gasverteilnetzes indem nur Netzentgelte mit Niederdruck berücksichtigt werden.

 

Weitere Informationen

Allgemeine Hinweise

Parameter	Hinweis
Datum	Alle Datumsangaben (Typ date) sind im Format jjjj-mm-tt.
gueltigBis	Gültigkeit einschließlich dieses Tages, d.h. bis 23:59:59 Uhr. Wenn kein Enddatum bekannt ist, wird der Wert auf „9999-12-31“ gesetzt.
gueltigVon	Gültigkeit einschließlich dieses Tages, d.h. ab 00:00:00 Uhr. Wenn kein Startdatum bekannt ist, wird der Wert auf „1900-01-01“ gesetzt.
Preise/Kosten	Alle Preise/Kosten sind netto angegeben.

Optionale Komponente

Für einzelne der beschriebenen Ausgaben liegen nicht in allen Fällen entsprechende Informationen vor. Welche Parameter bzw. Objekte optional sind, ist im Absatz Objektdefinitionen dieser Dokumentation dargestellt.

Optionale Objekte sind in der JSON-Struktur anhand der jeweiligen Objekt- bzw. Arrayfelder erkennbar. Parameter, deren Angabe nicht zwingend erforderlich ist oder für die keine verwertbare Information vorliegt, sind als „optional“ dokumentiert. Enthält ein Ausgabeparameter keine verwertbare Information, wird er in der JSON-Antwort mit dem Wert `null` geliefert.

Als Standardwert für den Stichtag wird automatisch das aktuelle Datum verwendet.

Fehlersuche

Bei FehlerCode 1 wurde die Anfrage an die API erfolgreich verarbeitet.

Bei FehlerCode 500 bis 600 überprüfen Sie bitte die verwendeten Authentifizierungsdaten und wenden Sie sich gegebenenfalls unter Angabe Ihres Benutzernamens an den Support der GET AG.

Bei FehlerCode 2 oder 700 wenden Sie sich bitte unter Angabe sämtlicher übergebener Input-Parameter an den Support der GET AG.

Bei FehlerCode 700 ff. prüfen Sie zunächst Ihre Eingaben. Der zurückgegebene Fehlertext enthält einen Hinweis darauf, an welcher Stelle der Fehler aufgetreten ist.

Bitte ergänzen Sie bei Anfragen an den Support der GET AG stets folgende Angaben:

• Bezeichnung und Versionsnummer der API
• verwendete Methode
• FehlerCode
• iTag

 

Prozessbeschreibung

Netzbetreibersuche Kalkulation und Angebot

Ausgangssituation: In vielen Portalen wird Endkunden zunächst ausschließlich die Eingabe der Postleitzahl (PLZ) abverlangt. Auf dieser Basis kann schrittweise der zuständige Netzbetreiber bzw. Grundversorger ermittelt werden. Im Folgenden wird der empfohlene Ablauf beschrieben.

1. Rufen Sie mit der PLZ die Methode `getOrtsinfoExtended` auf.

2. Prüfen Sie im Ergebnis die Anzahl der zurückgegebenen Netzgebiete (z. B. `stromNetzgebietLength`).

   1. Liefert der Output genau ein Netzgebiet, ist die Ermittlung abgeschlossen.

   2. Werden mehrere Netzgebiete gefunden, stellen Sie den Anwendern zunächst die im gleichen Output enthaltenen Orte zur Auswahl.

      1. Rufen Sie anschließend mit PLZ und ausgewähltem Ort erneut `getOrtsinfoExtended` auf.

         1. Ergibt die Kombination aus PLZ und Ort genau ein Netzgebiet, ist die Ermittlung abgeschlossen.

         2. Werden weiterhin mehrere Netzgebiete gefunden, verwenden Sie die Methode `getStrassenByPlzOrt`, um zu PLZ und Ort die verfügbaren Straßen zu ermitteln und den Anwendern zur Auswahl anzubieten.

            1. Rufen Sie danach mit PLZ, Ort und Straße erneut `getOrtsinfoExtended` auf.

               1. Liefert die Kombination aus PLZ, Ort und Straße genau ein Netzgebiet, ist die Suche beendet.

               2. Werden weiterhin mehrere Netzgebiete zurückgegeben, wählen Sie ein geeignetes Ausfallszenario, z. B.:

                  • Netzbetreiber-Auswahl durch die Anwender:innen,

                  • Auswahl des zugehörigen Grundversorgers,

                  • Auswahl des Netzgebiets mit dem höchsten Netzentgelt,

                  • Ermittlung des Hauptnetzbetreibers über `getOrtsinfoRangGebiet`.
                    

Netzbetreibersuche Abrechnung

Ausgangssituation: Im Abrechnungsprozess liegt die vollständige Adresse der Kundschaft bereits vor.

1. Rufen Sie mit PLZ, Ort und Straße die Methode `getOrtsinfoExtended` auf.

2. Prüfen Sie im Ergebnis die Anzahl der zurückgegebenen Netzgebiete.

   1. Liefert der Output genau ein Netzgebiet (z. B. `stromNetzgebietLength = 1`), ist die Ermittlung abgeschlossen.

   2. Werden mehrere Netzgebiete zurückgegeben, stellen Sie der anwendenden Person die Netze bzw. die zugehörigen Netzbetreiber zur Auswahl.

      1. Gibt die API die Warnung 900 zurück, wurden Ort oder Straße im Input nicht in der offiziellen Post-Schreibweise übermittelt. In diesem Fall werden dennoch alle Netze zur übergebenen PLZ ausgegeben, sodass ohne weitere Anfrage an den Webservice weitergearbeitet werden kann. Werden dabei mehrere Netze geliefert, verfahren Sie wie unter Punkt 2. b. beschrieben.

3. Optional: Anbindung Netzentgelt-API  

   Nutzen Sie die in Schritt 2 ermittelte(n) `verbandsnummer` des Netzbetreibers gemeinsam mit der PLZ, um die entsprechenden Netzentgelte über den Netzentgelt-API abzurufen.

Grundversorgersuche  

Damit in mehrfach grundversorgten Postleitzahlengebieten der korrekte Grundversorger ermittelt werden kann, ist der beschriebene Prozess in Kombination mit dem Ortsinfoservice erforderlich. 

Typischer Anwendungsfall: Bewegt sich eine Endkundin bzw. ein Endkunde in einem Portal, wird in der Regel zunächst ausschließlich die Postleitzahl (PLZ) als Eingabe abgefragt.

1. Prüfen Sie zunächst den Output der Methode `getOrtsinfoExtended` zur übergebenen PLZ:

   1. Wird genau ein Grundversorger ermittelt, ist die Suche abgeschlossen.

   2. Werden mehrere Grundversorger ermittelt, stellen Sie zunächst die im Output enthaltenen Orte zur Auswahl.

      1. Rufen Sie anschließend mit PLZ und ausgewähltem Ort erneut `getOrtsinfoExtended` auf:

         1. Liefert diese Kombination genau einen Grundversorger, ist die Ermittlung abgeschlossen.

         2. Werden mehrere Grundversorger zurückgegeben, ermitteln Sie mit `getStrassenByPlzOrt` zu PLZ und Ort die verfügbaren Straßen und bieten diese zur Auswahl an.

         3. Rufen Sie danach mit PLZ, Ort und Straße erneut `getOrtsinfoExtended` auf:

            1. Liefert die Kombination aus PLZ, Ort und Straße genau einen Grundversorger, ist der Prozess beendet.

            2. Werden mehrere Grundversorger zurückgegeben, nutzen Sie – sofern verfügbar – zusätzlich die Hausnummer, um die Auswahl weiter zu verfeinern. Eine weitere Unterteilung ist nicht möglich, es werden dann alle Tarife ausgegeben.

2. Hinweis:  Der ermittelte Grundversorger kann im Anschluss an nachgelagerte Systeme, z. B. Tarif-Webservices, zur weiteren Verarbeitung (z. B. Tarifermittlung) übergeben werden.

3. Übergabe Grundversorger an die Tarif API
   1. Methode „getBerechneteTarife“
      1. Die Postleitzahl und die Verbandsnummer des Grundversorgers werden an den Tarif-Webservice in der Methode „getBerechneteTarife“ übergeben.
   2. Methode "getBerechneteGrundversorgungsTarifebyPLZundVerbrauchKundenart“
      1. Die Postleitzahl wird an die Methode „getBerechneteGrundversorgungsTarifebyPLZundVerbrauchKundenart“ übergeben; anschließend erfolgt im Ergebnis eine Nachfilterung auf die zuvor ermittelte interne Versorger-ID.

Ermittlung des Hauptnetzgebietes

Über die Methode `getOrtsinfoRangGebiet` kann für eine Lokation (z. B. eine Postleitzahl) das jeweilige Hauptnetzgebiet ermittelt werden. 

Das Hauptnetzgebiet wird dabei über die Anzahl der innerhalb der Lokation vom jeweiligen Netzgebiet versorgten Lokationselemente (z. B. Hausnummern oder Straßen) definiert. Liegen in einer Postleitzahl mehrere Netzgebiete vor, gilt das Netzgebiet als Hauptnetzgebiet, dem die meisten Lokationselemente zugeordnet sind.

Sind einer Postleitzahl mehrere Gemeindekennziffern (GKZ) zugeordnet, werden die Hauptnetzgebiete für jede PLZ/GKZ-Kombination separat ausgegeben.

Konkretes Beispiel: Ermittlung des Haupt-Stromnetzgebietes für die PLZ 52525

Für die Bestimmung des Haupt-Stromnetzgebietes wird die Postleitzahl 52525 gemeinsam mit dem `idGebietsTyp` „1“ an die Methode `getOrtsinfoRangGebiet` übergeben. In der Antwort werden drei Objekte des Typs `gebiet` zurückgeliefert:

• Netzgebiet 727200 zur PLZ 52525 und GKZ 05370016 mit Rang „1“ – die Alliander Netz ist damit Haupt-Netzbetreiber in dieser Gemeindekennziffer (GKZ).

• Netzgebiet 1068991 zur PLZ 52525 und GKZ 05370016 mit Rang „2“ – die Veolia Industriepark Deutschland ist ebenfalls Netzbetreiber in dieser GKZ, jedoch nicht Haupt-Netzbetreiber.

• Netzgebiet 42600 zur PLZ 52525 und GKZ 05370032 mit Rang „1“ – die NEW Netz GmbH ist Haupt-Netzbetreiber in dieser GKZ.

 

Haben Sie Fragen zur API oder möchten eine Dokumentation erhalten oder einen Testzugang beantragen, dann nutzen sie bitte unser Kontaktformular: