Lokation identifizieren

Identifiziert zu einem definierten Stichtag alle zugehörigen Marktlokationen (MaLo)
bzw. Messlokationen (MeLo) anhand übergebener Identifikationsmerkmale.

Fachlicher Zweck

Der Aufrufer kennt die gesuchten Lokationen nicht (oder nicht sicher) über ihre ID, sondern
nur über andere Merkmale — z. B. eine Adresse, eine Zählernummer oder eine Kundenreferenz.
Die Methode löst diese Merkmale im Backend gegen den Datenbestand auf und liefert die
zugeordneten Lokationen im gewünschten Lokationstyp zurück.

Da die übergebenen Merkmale fachlich nicht zwingend eindeutig sind (eine Lokationsadresse
kann z. B. für ein ganzes Gebäude mehrere Messlokationen umfassen), liefert die Methode
grundsätzlich eine Trefferliste. Eine Treffermenge größer 1 ist ein reguläres fachliches
Ergebnis und kein Fehlerfall.x

Identifikationsmerkmale (`stammdaten`)

Es kann ein einzelnes Merkmal oder eine beliebige Kombination übergeben werden. Alle
übergebenen Merkmale werden UND-verknüpft ausgewertet — je mehr Merkmale gesetzt sind,
desto stärker wird die Treffermenge eingegrenzt:

Container	Merkmale
`MARKTLOKATION`	Marktlokations-ID, Energierichtung, Lokationsadresse, Katasterinformation, Geokoordinaten
`MESSLOKATION`	Messlokations-ID, Messadresse
`TRANCHE`	Tranchen-ID
`ZAEHLER`	Zählernummer
`ENERGIELIEFERVERTRAG`	Vertragsart, Vertragspartner inkl. externer Referenzen (Kunden-/Vertragskontonummern)
`NETZNUTZUNGSVERTRAG`	Vertragsart, Sparte, Vertragszeitraum, Vertragskonditionen

Identifikationsmerkmal und gewünschter Rückgabetyp sind unabhängig voneinander: So können
über eine Zählernummer die zugehörigen Marktlokationen oder über eine Marktlokations-ID die
zugehörigen Messlokationen ermittelt werden.

Zeitlicher Bezug (`transaktionsdaten.ausfuehrungsdatum`)

Die Identifikation erfolgt stichtagsbezogen: Ausgewertet wird ausschließlich der
Datenstand, der zum angegebenen Zeitpunkt gültig ist. Anfragen mit identischen Merkmalen,
aber unterschiedlichem Ausführungsdatum können daher bewusst zu unterschiedlichen
Ergebnissen führen (z. B. nach Gerätewechsel, Adressänderung oder Lieferantenwechsel).

Der Zeitpunkt wird in UTC übergeben und muss umgerechnet einem Tagesbeginn (00:00 Uhr)
gesetzlicher deutscher Zeit entsprechen.

Steuerung des Ergebnisses (`zusatzdaten`)

Feld	Pflicht	Wertebereich	Default	Bedeutung
`lokationsTyp`	ja	`MALO` \| `MELO`	—	Typ der zurückzugebenden Lokationen — `MALO` → Marktlokationen, `MELO` → Messlokationen

Die Mengensteuerung liegt nicht im Body, sondern in HTTP-Headern (siehe nächster
Abschnitt). Der Body transportiert ausschließlich Fachdaten.

Begrenzung und Blättern (HTTP-Header)

Die Schnittstelle ist so ausgelegt, dass sie im Normalfall ohne Paginierung auskommt:
Ohne die beiden Anfrage-Header wird die vollständige Treffermenge einer üblichen
Identifikationsanfrage in einem einzigen Aufruf beantwortet. Blättern ist der Ausnahmefall
für ungewöhnlich unscharfe Anfragen — nicht der Regelweg.

Anfrage-Header (beide optional):

Header	Wertebereich	Default	Bedeutung
`Treffer-Max-Anzahl`	1 … 500	20	Maximale Anzahl der in einer Antwort gelieferten Lokationen (Seitengröße)
`Treffer-Offset`	0 … 10000	0	Anzahl der zu überspringenden Treffer — nur für das Nachladen weiterer Seiten

Antwort-Header (immer gesetzt):

Header	Bedeutung
`Treffer-Offset`	Der tatsächlich angewendete Versatz (Echo des Requests bzw. `0`)
`Treffer-Anzahl`	Anzahl der in dieser Antwort gelieferten Lokationen (= Länge des Arrays)
`Treffer-Gesamtanzahl`	Anzahl aller zum Stichtag passenden Lokationen, unabhängig von Offset und Seitengröße
`Treffer-Weitere-Vorhanden`	`true`, wenn hinter dieser Seite weitere Treffer liegen (`Treffer-Offset + Treffer-Anzahl < Treffer-Gesamtanzahl`)

Seitengröße: Treffer-Max-Anzahl begrenzt die Anzahl gelieferter Lokationen. Der
Default von 20 deckt eindeutige und nahezu eindeutige Anfragen (Zählernummer,
Kundenreferenz, vollständige Adresse) vollständig ab; eine Kürzung tritt bei unscharfen
Merkmalen auf, etwa einer Adresse ohne Hausnummer oder einem Mehrfamilienhaus.

Harter Server-Cap: Der Maximalwert von 500 ist serverseitig festgelegt und kann
vom Aufrufer nicht überschritten werden. Werte außerhalb der zulässigen Bereiche sowie
nicht-numerische Header-Werte werden mit 400 Bad Request abgelehnt — sie werden
nicht stillschweigend auf den Cap gekappt.

Versatz: Treffer-Offset überspringt die ersten n Treffer der sortierten
Gesamtmenge. Die nächste Seite wird angefordert mit
Treffer-Offset_neu = Treffer-Offset + Treffer-Anzahl. 0 entspricht dem Weglassen des
Headers.

Immer 200 OK: Auch die gekürzte Antwort wird mit 200 beantwortet, nicht mit
206 Partial Content. Range/Content-Range kommen bewusst nicht zum Einsatz:
Range-Handling ist laut RFC 9110 ausschließlich für GET definiert und muss bei POST
ignoriert werden.

Deterministische Sortierung: Die Gesamtmenge wird vor dem Anwenden von Offset und
Seitengröße stabil aufsteigend nach der Lokations-ID sortiert. Nur dadurch sind Seiten
überschneidungs- und lückenfrei.

Kein Snapshot: Es gibt keinen Cursor und keine serverseitige Ergebniskonservierung.
Seiten sind konsistent, solange sich der zum Stichtag gültige Datenbestand zwischen den
Aufrufen nicht ändert. Bei sehr großen Treffermengen ist die fachlich bessere Reaktion,
die Identifikationsmerkmale zu verfeinern, statt über viele Seiten zu blättern.

Ergebnis

Der Antwort-Body ist ein flaches Array auf Root-Ebene mit 0 … n ermittelten
Lokationen — kein umgebender Container. Die Einträge entsprechen unverändert dem
bisherigen Einzelergebnis (Marktlokation bzw. Messlokation, gesteuert über
lokationsTyp); eine Gruppierung nach Containertypen wie im Request gibt es nicht.
Sämtliche Metadaten liegen in den Antwort-Headern.

Fallunterscheidung:

Kein Treffer → leeres Array [], Treffer-Anzahl: 0,
Treffer-Gesamtanzahl: 0, Treffer-Weitere-Vorhanden: false. Dies ist ein gültiges
fachliches Ergebnis und keine technische Störung (kein Fehler-Response, HTTP 200).

Genau ein Treffer → Array mit einem Element. Es gibt keinen abweichenden Sonderfall
für die eindeutige Zuordnung.

Mehrere Treffer → alle passenden Lokationen bis zur Seitengröße. Mehrdeutigkeit führt
ausdrücklich nicht mehr zu einem leeren Ergebnis; die Auflösung obliegt dem Aufrufer.

Weitere Seiten vorhanden → Treffer-Weitere-Vorhanden: true. Der Aufrufer kann die
Merkmale verfeinern oder die Folgeseite mit
Treffer-Offset = Treffer-Offset + Treffer-Anzahl abrufen. Auch dies ist kein
Fehler-Response.

Treffer-Offset hinter dem Ende der Treffermenge → leeres Array bei gefülltem
Treffer-Gesamtanzahl, Treffer-Weitere-Vorhanden: false, HTTP 200.

Request

Authorization

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Body Params application/json

Example

{
    "stammdaten": {
        "MARKTLOKATION": [
            {
                "boTyp": "MARKTLOKATION",
                "versionStruktur": "1",
                "marktlokationsId": "90131677420",
                "energierichtung": "EINSP",
                "lokationsadresse": {
                    "postleitzahl": "aliquip tempor amet",
                    "ort": "commodo in Excepteur eu dolor",
                    "strasse": "laborum minim proident",
                    "hausnummer": "50",
                    "postfach": "quis aliqua",
                    "adresszusatz": "veniam in ea",
                    "coErgaenzung": "id est adipisicing tempor",
                    "landescode": "UK",
                    "ortsteil": "dolore ad esse",
                    "zusatzInformation": {
                        "zusatz1": "Lorem id Duis anim",
                        "zusatz2": "aliqua laborum minim cillum deserunt",
                        "zusatz3": "proident",
                        "zusatz4": "consectetur sit",
                        "zusatz5": "consequat reprehenderit qui pariatur nulla"
                    }
                }
            },
            {
                "boTyp": "MARKTLOKATION",
                "versionStruktur": "1",
                "marktlokationsId": "03308573585",
                "energierichtung": "AUSSP",
                "lokationsadresse": {
                    "postleitzahl": "Ut ex enim cupidatat aliquip",
                    "ort": "Duis ea ex sed",
                    "strasse": "elit consequat aliquip",
                    "hausnummer": "96",
                    "postfach": "minim Duis fugiat ut",
                    "adresszusatz": "consectetur pariatur officia",
                    "coErgaenzung": "reprehenderit mollit irure",
                    "landescode": "GL",
                    "ortsteil": "eu id",
                    "zusatzInformation": {
                        "zusatz1": "exercitation",
                        "zusatz2": "elit ad dolor veniam",
                        "zusatz3": "Ut ullamco Duis laboris",
                        "zusatz4": "Ut est non ex",
                        "zusatz5": "irure in deserunt culpa"
                    }
                }
            }
        ],
        "TRANCHE": [
            {
                "boTyp": "TRANCHE",
                "versionStruktur": "1",
                "tranchenId": "25753438709"
            }
        ],
        "MESSLOKATION": [
            {
                "boTyp": "MESSLOKATION",
                "versionStruktur": "1",
                "messlokationsId": "DE89771071027XDWTLEH0Q9J3J02PYZXW",
                "messadresse": {
                    "postleitzahl": "<string>",
                    "ort": "<string>",
                    "strasse": "<string>",
                    "hausnummer": "<string>",
                    "postfach": "<string>",
                    "adresszusatz": "<string>",
                    "coErgaenzung": "<string>",
                    "gewerbekennzeichnung": true,
                    "landescode": "DE",
                    "ortsteil": "<string>",
                    "zusatzInformation": {
                        "zusatz1": "<string>",
                        "zusatz2": "<string>",
                        "zusatz3": "<string>",
                        "zusatz4": "<string>",
                        "zusatz5": "<string>"
                    }
                }
            }
        ]
    }
}

Responses

🟢200OK

application/json

Erfolgreiches Lesen der Marktlokation | Successful reading of the market location

Bodyapplication/json

Examples

EIne MarktlokationEine MesslokationMehrere Marktlokationen

[
    {
        "boTyp": "MARKTLOKATION",
        "versionStruktur": "1",
        "marktlokationsId": "50754496000",
        "marktlokationsTyp": [
            {
                "typ": "STANDARD_MARKTLOKATION",
                "gueltigAb": "2023-08-01T22:00:00Z",
                "gueltigBis": "2027-08-01T22:00:00Z"
            }
        ],
        "zukuenftigerMeldepunkt": null,
        "sparte": "STROM",
        "gueltigkeitszeitraum": {
            "zeitraumId": null,
            "startdatum": null,
            "enddatum": null
        },
        "rollencodenummer": "9906464000001",
        "inbetriebnahmedatum": "2023-08-01T22:00:00Z",
        "datenqualitaet": null,
        "energierichtung": "AUSSP",
        "bilanzierungsmethode": "SLP",
        "verbrauchsart": [
            "KL"
        ],
        "unterbrechbar": false,
        "netzebene": "NSP",
        "umspannung": null,
        "netzbetreiberCodeNr": "9900683000008",
        "gebietTyp": "VERSORGUNGSGEBIET",
        "netzgebietNr": "12345",
        "bilanzierungsgebiet": "11YR00000004025V",
        "grundversorgerCodeNr": "9900683000008",
        "endkunde": {
            "boTyp": "GESCHAEFTSPARTNER",
            "versionStruktur": "1",
            "anrede": "Herr",
            "name1": "Haiko",
            "name2": "Fisch",
            "name3": null,
            "gewerbekennzeichnung": false,
            "hrnummer": null,
            "amtsgericht": null,
            "kontaktweg": [
                "TELEFONAT",
                "E_MAIL"
            ],
            "umsatzsteuerId": null,
            "glaeubigerId": null,
            "eMailAdresse": "hai.fisch@web.de",
            "website": null,
            "partneradresse": {
                "postleitzahl": "65189",
                "ort": "Wiesbaden",
                "strasse": "Korallenweg",
                "hausnummer": "10",
                "postfach": null,
                "adresszusatz": "Wohnung 1",
                "coErgaenzung": null,
                "landescode": "DE",
                "ortsteil": "Riff"
            }
        },
        "lokationsadresse": {
            "postleitzahl": "65189",
            "ort": "Wiesbaden",
            "strasse": "Korallenweg",
            "hausnummer": "10",
            "postfach": null,
            "adresszusatz": "Wohnung 1",
            "coErgaenzung": null,
            "landescode": "DE",
            "ortsteil": "Riff",
            "zusatzInformation": {
                "zusatz1": null,
                "zusatz2": null,
                "zusatz3": null,
                "zusatz4": null,
                "zusatz5": null
            }
        },
        "katasteradresse": {
            "gemarkung_flur": "1",
            "flurstueck": "1",
            "flurstueckNummer": "1"
        },
        "geokoordinaten": {
            "breitengrad": "50.0782",
            "laengengrad": "8.2397",
            "ostwert": null,
            "nordwert": null,
            "zone": "UTMZone32",
            "hochwert": null,
            "rechtswert": null
        },
        "marktrollen": [
            {
                "boTyp": "MARKTTEILNEHMER",
                "versionStruktur": "1",
                "gueltigkeitszeitraum": {
                    "zeitraumId": 1,
                    "startdatum": "2022-12-31T23:00:00Z",
                    "enddatum": "2027-07-01T04:00:00Z"
                },
                "marktrolle": "MSB",
                "gewerbekennzeichnung": true,
                "rollencodenummer": "9906464000001",
                "rollencodetyp": "BDEW",
                "weiterverpflichtet": false,
                "messstellenbetreiberEigenschaft": "GRUNDZUSTAENDIGER_MESSSTELLENBETREIBER"
            },
            {
                "boTyp": "MARKTTEILNEHMER",
                "versionStruktur": "1",
                "gueltigkeitszeitraum": {
                    "zeitraumId": 1,
                    "startdatum": "2022-12-31T23:00:00Z",
                    "enddatum": "2027-12-31T23:00:00Z"
                },
                "marktrolle": "NB",
                "gewerbekennzeichnung": true,
                "rollencodenummer": "9900683000008",
                "rollencodetyp": "BDEW"
            },
            {
                "boTyp": "MARKTTEILNEHMER",
                "versionStruktur": "1",
                "gueltigkeitszeitraum": {
                    "zeitraumId": 1,
                    "startdatum": "2022-12-31T23:00:00Z",
                    "enddatum": "2027-12-31T23:00:00Z"
                },
                "marktrolle": "LF",
                "gewerbekennzeichnung": true,
                "rollencodenummer": "9904000000005",
                "rollencodetyp": "BDEW"
            },
            {
                "boTyp": "MARKTTEILNEHMER",
                "versionStruktur": "1",
                "gueltigkeitszeitraum": {
                    "zeitraumId": 1,
                    "startdatum": "2022-12-31T23:00:00Z",
                    "enddatum": "2027-12-31T23:00:00Z"
                },
                "marktrolle": "UENB",
                "gewerbekennzeichnung": true,
                "rollencodenummer": "4033872000058",
                "rollencodetyp": "BDEW"
            },
            {
                "boTyp": "MARKTTEILNEHMER",
                "versionStruktur": "1",
                "gueltigkeitszeitraum": {
                    "zeitraumId": 1,
                    "startdatum": "2022-12-31T23:00:00Z",
                    "enddatum": "2027-12-31T23:00:00Z"
                },
                "marktrolle": "BIKO",
                "gewerbekennzeichnung": true,
                "rollencodenummer": "4033872000027",
                "rollencodetyp": "BDEW"
            },
            {
                "boTyp": "MARKTTEILNEHMER",
                "versionStruktur": "1",
                "gueltigkeitszeitraum": {
                    "zeitraumId": 1,
                    "startdatum": "2022-12-31T23:00:00Z",
                    "enddatum": "2027-12-31T23:00:00Z"
                },
                "marktrolle": "BKV",
                "gewerbekennzeichnung": true,
                "rollencodenummer": "4033872000034",
                "rollencodetyp": "BDEW"
            }
        ],
        "regelzone": "1",
        "marktgebiet": "1234",
        "zeitreihentyp": "SLS",
        "zaehlwerke": [
            {
                "zaehlwerkId": "1",
                "bezeichnung": "HT",
                "richtung": "AUSSP",
                "obisKennzahl": "1-1:1.9.0",
                "wandlerfaktor": 1,
                "einheit": "KWH",
                "schwachlastfaehig": "NICHT_SCHWACHLASTFAEHIG",
                "verwendungszwecke": [
                    {
                        "marktrolle": "NB",
                        "zweck": [
                            "NETZNUTZUNGSABRECHNUNG"
                        ]
                    }
                ],
                "verbrauchsart": [
                    "KL"
                ],
                "unterbrechbarkeit": "NUV",
                "waermenutzung": null,
                "konzessionsabgabe": {
                    "satz": "TA",
                    "kosten": 0,
                    "kategorie": "1"
                },
                "steuerbefreit": false,
                "vorkommastelle": 7,
                "nachkommastelle": 3,
                "abrechnungsrelevant": true,
                "anzahlAblesungen": 1,
                "zaehlzeiten": {
                    "zaehlzeitDefinition": null,
                    "register": null,
                    "schwachlastfaehig": null
                },
                "leistungskurvendefinition": null,
                "konfiguration": null,
                "messprodukt": "9991000000044",
                "wertegranularitaet": "JAEHRLICH",
                "notwendigkeitZweiteMessung": "NICHT_VORHANDEN",
                "werteuebermittlungVerwendungszweck": "NICHT_VORHANDEN",
                "artEMobilitaet": null
            }
        ],
        "zaehlwerkeBeteiligteMarktrolle": [
            "NB"
        ],
        "verbrauchsmenge": [
            {
                "startdatum": "2024-08-01T22:00:00Z",
                "enddatum": "2025-08-01T22:00:00Z",
                "wertermittlungsverfahren": "PROGNOSE",
                "messwertstatus": "PROGNOSEWERT",
                "statuszusatzinformationen": [
                    {
                        "art": "PLAUSIBILISIERUNGSHINWEIS",
                        "status": "KUNDENSELBSTABLESUNG"
                    }
                ],
                "obiskennzahl": "1-1:1.9.0",
                "wert": 2500,
                "einheit": "KWH"
            }
        ],
        "zugehoerigeMesslokationen": [
            {
                "messlokationsId": "DE0009697056900614312080040415111",
                "arithmetik": "ADDITION",
                "gueltigSeit": "2023-08-01T22:00:00Z",
                "gueltigBis": "2027-08-01T22:00:00Z"
            }
        ],
        "messtechnischeEinordnung": "IMS",
        "netznutzungsabrechnungsdaten": [
            {
                "artikelId": "1",
                "artikelIdTyp": "ARTIKELID",
                "anzahl": 1,
                "gemeinderabatt": null,
                "zuschlag": null,
                "abschlag": null,
                "singulaereBetriebsmittel": {
                    "wert": null,
                    "einheit": null
                },
                "preisSingulaereBetriebsmittel": {
                    "wert": null,
                    "einheit": null,
                    "bezugswert": null,
                    "status": null
                },
                "abrechnungBlindarbeit": null,
                "zahlerBlindarbeit": null,
                "zahlerBlindarbeitLf": null,
                "zaehlzeiten": {
                    "zaehlzeitDefinition": null,
                    "register": null
                }
            }
        ],
        "messstellenbetriebsabrechnungsdaten": [
            {
                "messstellenbetriebsabrechnung": true,
                "artikelId": "1",
                "artikelIdTyp": "ARTIKELID",
                "anzahl": 1,
                "zuschlag": null,
                "abschlag": null
            }
        ],
        "sperrstatus": "ENTSPERRT",
        "referenzMarktlokationsId": "50754496000",
        "energieherkunft": [
            {
                "erzeugungsart": null,
                "anteilProzent": null
            }
        ],
        "versorgungsart": null,
        "eigentuemer": {
            "boTyp": "GESCHAEFTSPARTNER",
            "versionStruktur": "1",
            "anrede": "Herr",
            "name1": "Haiko",
            "name2": "Fisch",
            "name3": null,
            "gewerbekennzeichnung": false,
            "geschaeftspartnerrolle": [
                "EIGENTUEMER"
            ],
            "hrnummer": null,
            "amtsgericht": null,
            "kontaktweg": [
                "TELEFONAT",
                "E_MAIL"
            ],
            "umsatzsteuerId": null,
            "glaeubigerId": null,
            "eMailAdresse": "hai.fisch@web.de",
            "website": null,
            "partneradresse": {
                "postleitzahl": "65189",
                "ort": "Wiesbaden",
                "strasse": "Korallenweg",
                "hausnummer": "10",
                "postfach": null,
                "adresszusatz": "Wohnung 1",
                "coErgaenzung": null,
                "landescode": "DE",
                "ortsteil": "Riff"
            }
        },
        "hausverwalter": {
            "boTyp": "GESCHAEFTSPARTNER",
            "versionStruktur": "1",
            "anrede": "Herr",
            "name1": "Haiko",
            "name2": "Fisch",
            "name3": null,
            "gewerbekennzeichnung": false,
            "geschaeftspartnerrolle": [
                "HAUSVERWALTER"
            ],
            "hrnummer": null,
            "amtsgericht": null,
            "kontaktweg": [
                "TELEFONAT",
                "E_MAIL"
            ],
            "umsatzsteuerId": null,
            "glaeubigerId": null,
            "eMailAdresse": "hai.fisch@web.de",
            "website": null,
            "partneradresse": {
                "postleitzahl": "65189",
                "ort": "Wiesbaden",
                "strasse": "Korallenweg",
                "hausnummer": "10",
                "postfach": null,
                "adresszusatz": "Wohnung 1",
                "coErgaenzung": null,
                "landescode": "DE",
                "ortsteil": "Riff"
            }
        },
        "verguetungEmpfaenger": null,
        "statusErzeugendeMalo": null,
        "fernsteuerbarkeit": "TECHNISCH_NICHT_FERNSTEUERBAR",
        "foerderungsLand": null,
        "redispatch": false,
        "lokationszuordnung": null,
        "modulNetzentgelte": null,
        "produktdatenRelevanteRolle": "LF",
        "konfigurationsprodukt": null,
        "leistungskurvendefinition": null,
        "beteiligterMarktpartner": {
            "boTyp": "MARKTTEILNEHMER",
            "versionStruktur": "1",
            "marktrolle": "NB",
            "gewerbekennzeichnung": true,
            "rollencodenummer": "9900683000008",
            "rollencodetyp": "BDEW"
        },
        "erforderlichesProduktpaket": [
            {
                "produktpaketId": 1,
                "produkt": [
                    {
                        "produktCode": "9991000002008",
                        "codeProdukteigenschaft": "9991000002115",
                        "wertedetails": null
                    }
                ],
                "umsetzungsgradvorgabe": "ZUORDNUNG_NUR_WENN_PRODUKTPAKET_UMSETZBAR",
                "priorisierung": "PRIORITAET1"
            }
        ],
        "datenDerBeteiligtenMarktrolle": null,
        "paketId": null
    }
]

🟠400Bad Request

Fachlicher Zweck#

Identifikationsmerkmale (stammdaten)#

Zeitlicher Bezug (transaktionsdaten.ausfuehrungsdatum)#

Steuerung des Ergebnisses (zusatzdaten)#

Begrenzung und Blättern (HTTP-Header)#

Ergebnis#