4 Posts getaggt mit "Suchdienst API"

Mit dem Release 9.8 haben wir den neu überarbeiteten Endpunkt v6beta3/servicedescription vorgestellt, den Stakeholdern zum Testen bereitgestellt und um Feedback gebeten.

Nach erfolgreicher Testphase und mit den Rückmeldungen zur v6beta3/servicedescription (vielen Dank dafür!) wurde der Endpunkt überarbeitet und mit dem PVOG Release 9.17. als v6/servicedescriptions/{lbid}/detail produktiv gesetzt.

Folgende Anpassungen wurden im Vergleich zu suchdienst/api/v5/servicedescriptions/:ars/detail vorgenommen:

• Die Antwort wurde deutlich verschlankt und um Zugangskanäle erweitert.
• Der Such-Parameter validDate entfällt, es wird automatisch mit dem aktuellen Zeitstempel gesucht.
• Der Such-Parameter applyDynamicParams entfällt, es werden automatisch die dynamischen Parameter angewandt.

Als Ergebnis einer Abfrage werden alle Informationen und alle zuständigen Organisationseinheiten in einem bestimmten Gebiet (ARS) ausgegeben. Die Onlinedienst-Links in der Antwortmenge enthalten dynamische Parameter. Der Endpunkt liefert zum Zeitpunkt der Anfrage die aktuellsten Daten nach Gültigkeitszeitraum zurück.

Um zu Änderungen an den öffentlichen Suchdienst Endpunkten informiert zu werden, nutzen Sie gern eine Client ID (vormals API Key).

Mit der Umstellung auf XZuFi 2.3.1 wurde in den JZuFi Endpunkten implementiert, dass die XZuFi-Version beim Abruf im http-Header angefordert werden musste.

Zwischenzeitlich erreichte uns eine Kundenanforderung, zu JZuFi Endpunkten, die mit dem Codegenerator die gewünschte XZuFi-Version nicht korrekt abrufen konnte.

Da eine entsprechende Konfiguration des Codegenerators nicht möglich war, erfolgte im Release 9.16 eine Erweiterung der Endpunkte durch die Einführung von zwei Methoden pro Endpunkt, um die Kompatibilität mit dem Codegenerator zu gewährleisten.

Im Detail wurden ab Version 9.16 verschiedene Endpunkte als deprecated markiert, während parallel neue Versionen mit differenzierten Pfaden eingeführt wurden, die explizit die jeweilige XZuFi-Version in der URL abbilden.

	Ab PVOG Release 9.16. (Deployment Produktion am 5.5.2026)
/v1/organisationunits/jzufi	deprecated
/v2/servicedescriptions/jzufi	deprecated
/v2/relations/{ars}/jzufi	deprecated
/v3/organisationunits/jzufi - deprecated	/v1/organisationunits/:id/jzufi-2-2
	/v1/organisationunits/:id/jzufi-2-3
/v3/relations/:ars/jzufi - deprecated	/v1/relations/jzufi-2-2
	/v1/relations/jzufi-2-3
/v2/servicedescriptions/jzufi - deprecated	/v1/servicedescriptions/:id/jzufi-2-2
	/v1/servicedescriptions/:id/jzufi-2-3

Das zugrundeliegende Schema der Endpunkte blieb unverändert, sodass lediglich die URL angepasst werden muss, um die gewünschte Version anzusprechen.

Details zu den Endpunkten sind auf dem Produktportal oder in der OpenAPI Dokumentation einzusehen.

Insgesamt stellt diese Anpassung sicher, dass trotz der Einschränkungen des Codegenerators eine korrekte und flexible Nutzung der JZuFi-Endpunkte mit unterschiedlichen XZuFi-Versionen möglich ist. Mit Release 9.16. werden die Endpunkte ohne XZuFi-Version ebenfalls auf „deprecated“ gesetzt. Die Termine können dem Produktportal/Ressourcen/Deprecations entnommen werden.

Für Nutzer der PVOG Suchdienst REST APIs wird die Verwendung von API Keys empfohlen, um die Weiterentwicklung der Schnittstellen zu unterstützen. Informationen zur Beantragung und Nutzung der API Keys sind auf dem PVOG Produktportal verfügbar.

Mit dem PVOG Release 9.15. wurde für den Suchdienst der neue Endpunkt /v1beta2/onlineservices veröffentlicht.

Der Endpunkt liefert Onlinedienste innerhalb des angefragten ARS-Bereichs. Die Filterung erfolgt entlang der ARS-Hierarchie sowohl nach oben als auch nach unten.

Filterung nach oben: Bei der Suche nach der ARS 091 (Oberbayern) werden Onlinedienste mit Zuständigkeit für 091 sowie für übergeordnete Ebenen geliefert, z.B. Bayern (09) oder Bund (00).

Filterung nach unten: Bei der Suche nach 091 werden zusätzlich Onlinedienste für untergeordnete Ebenen bis hinunter zur Gemeindeebene geliefert, z.B. München (091620000000).

Beispiele zu den Ergebnissen der Abfrage

1. Abfrage mit <= 1000 Ergebnisse Beispiel: https://stage.pvog.fitko.net/suchdienst/api/v1beta2/onlineservices?ars=100

Für die ARS 100 werden im ersten Schritt alle Ergebnisse der Abfrage (725 hits) der insgesamt 725 Ergebnisse (totalHits) angezeigt.

2. Abfrage mit > 1000 Ergebnissen Beispiel: https://stage.pvog.fitko.net/suchdienst/api/v1beta2/onlineservices?ars=090

Für die ARS 090 werden im ersten Schritt der Abfrage 1000 Ergebnisse (hits) der insgesamt 1590 Ergebnisse (totalHits) angezeigt.

Die weiteren Onlinedienste können durch das Setzen des „nextPageToken“ abgefragt werden.

Beispiel:

https://stage.pvog.fitko.net/suchdienst/api/v1beta2/onlineservices?ars=090&nextPageToken=L100042.OD.12184_43865

Einschränkung über Leika

Als weiterer Parameter kann in der Abfrage die Ergebnismenge auf eine Leistung aus dem Leistungskatalog eingeschränkt werden. Das Ergebnis sind die Onlinedienste, die für eine Leistung mit dem konkreten Leistungsschlüssel, zuständig sind.

https://stage.pvog.fitko.net/suchdienst/api/v1beta2/onlineservices?ars=090&leikaIds=99050012104000

Response

Antwortschema

Das Schema der Antwort ist auf dem Produktportal abgebildet und ermöglich die gezielte Weiterverarbeitung der Ergebnisse.

Parallel zum Produktportal kann auch die Swagger Dokumentation zum Ausprobieren verwendet werden.

Geben Sie gern Feedback zur vorgestellten beta API, z. b. in der User Group oder über das Helpdesk-Formular auf dem PVOG Produktportal!

Mit dem PVOG Release 9.15. wurde für den Suchdienst der neue Endpunkt /v1beta1/onlineservices veröffentlicht.

Der Endpunkt gibt die Organisationseinheiten zurück, die einem Onlinedienst zugeordnet sind. Der Test des Endpunktes kann über das Produktportal oder die Swagger Dokumentation erfolgen.

Beispiel: https://stage.pvog.fitko.net/suchdienst/api/v1beta1/onlineservices/L100012.OD.277549726/organisations

Ergebnis: Es werden alle zugeordneten Organisationseinheiten und die zugehörige Leistung ausgegeben.

Schema der Antwort

Die Beschreibungen der Rollen der Organisationseinheiten für den Onlinedienst sind an zwei Codelisten angelehnt:

• urn:xoev-de:fim:codeliste:xzufi.organisationseinheitsrollefueronlinedienst (ZSOD OE referenziert in 2.3.1)
• urn:xoev-de:fim:codeliste:xzufi.zustaendigkeitsrolle (XZuFi 2.2)

Bitte geben Sie gern Feedback zum neu veröffentlichten Endpunkt, z.B. in der User Group oder über das Helpdesk-Formular auf dem PVOG Produktportal!