Über diese Seite
Dieses Dokument beschreibt die HTTP-basierte Kiezatlas API für das Berliner Familienportal. Sofern sie Kiezatlas Datensätze in Ihre Website oder App integieren möchten Sie aber nicht vom Berliner Familienportal sind möchten wir Sie an dieser Stelle auf die Dokumentation unserer Kiezatlas Orte API verweisen.
Durch Nutzung dieser API können die Betreiber des Familienportals Datensätze aus dem Kiezatlas in das Familienportal einbinden. Zur Verfügung stehen eine Kategorie-basierte Suche und eine Umkreissuche (kombinierbar). Die Anzeige von Kiezatlas Detailinformationen erfolgt innerhalb der Kiezatlas Website. Die API stellt die entsprechenden Links bereit. Der Zugriff auf die Kiezatlas API ist passwortgeschützt.
Hinweis: Die über die API abgerufenen Kiezatlas Daten dürfen von den Empfängern auf ihrer Website nur "on-demand" angezeigt werden aber nicht zwischengespeichert werden.
Zugang / Access
Bitte schreiben Sie eine E-Mail an Reinhilde Godulla (godulla@sozkult.de) mit ein paar Zeilen über ihr Interesse an oder ihr Nutzungskonzept für die Kiezatlas 2 API und wir werden uns zeitnah bei ihnen zurückmelden.
Please write a mail to Reinhilde Godulla (godulla@sozkult.de) about your interests in the Kiezatlas 2 API and we will be happy to provide you access.
Kiezatlas Service
Endpunkt für alle Anfragen ist momentan:
https://kiezatlas.berlin/
Antworten werden im JSON Format geliefert.
Autorisierung
Um Kiezatlas Datensätze anfragen zu können, muß zuvor eine HTTP Session augebaut werden. Dazu muß eine Autorisierungsanfrage geschickt werden.
Beispiel:
POST /accesscontrol/login Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Es muß also ein POST Request mit einem Authorization Header geschickt werden. Der Header-Wert ist "Basic " (Leerzeichen ist wichtig) gefolgt von der Base64-Kodierung des Strings "username:passwort", also Nutzernamen und Passwort zusammengesetzt mit einem Doppelpunkt.
Wenn der Login erfolgreich ist, wird 204 No Content zurückgeschickt, inklusive einem Set-Cookie Header aus dem die Session ID hervorgeht:
HTTP/1.1 204 No Content Set-Cookie: JSESSIONID=1dm1trkmxsbjy1jofa1y90y43v;Path=/
Wenn der Login scheitert (Username oder Passwort falsch) wird 401 Unauthorized zurückgeschickt.
Ein realer Nutzername und das Passwort wird ihren Mitarbeitern separat mitgeteilt.
Anfragen von Kiezatlas Objekten
Kategorie-basierte Suche nach Einrichtungen
Beispiel:
GET /famportal/geoobject?category=category-9abc6032-62c9-48a3-af9b-e9cd3931330b-de_DE-1
Hierbei ist category-9abc6032-62c9-48a3-af9b-e9cd3931330b-de_DE-1 die XML ID einer Familienportal Kategorie, in diesem Beispiel die Kategorie “Notfall”.
Antwort:
[
{
name: "Alkohol- u. Drogenberatung Mitte",
bezirk: "Mitte",
geolocation: {
lon: 13.3429000, lat: 52.5294200
},
link: "https://kiezatlas.berlin/website/geo/51064",
id: "t-124567"
},
{
name: "Finanzielle Hilfen für Familien in Notlagen",
bezirk: "...",
geolocation: {
lon: ..., lat: ...
},
link: "...",
id: "..."
},
...
]Die Antwort ist ein JSON Array aus Kiezatlas Objekten. Das Array kann leer sein. Die Reihenfolge der Kiezatlas Objekte ist undefiniert. (Die Zeilenumbrüche und Einrückungen sind in der tatsächlichen Antwort nicht enthalten.)
Ein Kiezatlas Objekt ist ein JSON Objekt mit genau 4 Properties:
- name (string) — Name des Objekts (oft eine soziale Einrichtung)
- bezirk (string) — Bezirk des Objekts
- geolocation (object) — Standort des Objekts
- lon (float) — Längengrad
- lat (float) — Breitengrad
- link (string) — Link zu einer Kiezatlas-Karte in der das Objekt und Detailinformationen zum Objekt angezeigt werden.
- id (string) — Technische ID des Kiezatlas Ortes
Die Angabe des category Query Parameters ist obligatorisch.
Mehrere Kategorien kombinieren
Beim Anfragen von Kiezatlas Objekten können mehrere Familienportal Kategorien kombiniert werden, z.B. “Sprachförderung” UND (“Kinder” ODER “Jugendliche”). Die Anfrage ist im Prinzip wie oben, wobei der Query Parameter category mehrere (beliebig viele) Werte erhalten kann, mit Kommas getrennt, und der gesamte Query String mehrere (beliebig viele) category Query Parameter enthalten kann.
Beispiel:
GET /famportal/geoobject?category=cat-12,cat-23&category=cat-45
Die Semantik so einer Anfrage ist:
- Die Ergebnismengen aller Kategorien eines category Parameters werden verODERt.
- Die Ergebnismengen aller category Parameter werden verUNDet.
Das Antwortformat ist wie oben.
Umkreissuche
Zusätzlich zur Kategorie-basierten Suche kann das Ergebnis anhand eines Standorts und Radius eingegrenzt werden (“Umkreissuche”). Dazu wird der Anfrage (siehe oben) ein weiterer Query Parameter mitgegeben: proximity.
Beispiel:
GET /famportal/geoobject?category=...&proximity=13.4027376,52.5347775,2.5
Der Wert des proximity Paramters besteht aus genau 3 Einzelwerten, durch Kommas getrennt:
- Längengrad (float)
- Breitengrad (float)
- Radius in km (float)
Der proximity Parameter ist optional. Wird er nicht angegeben, wird ausschließlich anhand der Kategorien gesucht. Der Kategorien-Filter hingegen ist obligatorisch. Eine Umkreissuche ohne Angabe eines Kategorien-Filters ist nicht möglich.
Volltextsuche nach Einrichtungen
Die Angabe des query Query Parameters ist obligatorisch. Bitte achten Sie darauf den Wert des query-Parameters als Wert einer URL zu enkodieren.
Beispiel:
GET /famportal/search?query=ehe
Der Wert "ehe" ist die Suchphrase und dieser findet Orte die "ehe" in ihrem Namen oder aber in ihrer Selbstbeschreibung, Stichworten, denStraßennamen der Anschrift oder aber dem Namen der Bezirksregion des Ortes enthalten ist.
Im Standardfall verwendet diese Suche eine sog. Wildcard am Ende der gesamten Suchphrase. Optional können Sie eine sog. Leading-Wildcard ("*") Ihrer Suchphrase voranstellen. Mit einer Leading Wildcard finden wir auch Ergebnisse in denen das gesuchte Wort in der Wortmitte oder am Wortende enthalten ist.
Antwort:
[
{
name: 'Psychologische Beratung für Einzelne und Paare',
bezirk: 'Steglitz-Zehlendorf',
link: 'https://kiezatlas.berlin/website/geo/487570',
geolocation: {'lon': 13.322874, 'lat': 52.444654},
anschrift: 'Rubensstraße 125, Haus 30, 4. Etage 12157 Berlin Deutschland',
id: '...'
},
...
]Die Antworten werden im selben Format ausgeliefert wie bei der Kategorie-basierten Suche und sind demnach ein JSON Array aus Kiezatlas Objekten. Das Array kann leer sein. Die Reihenfolge der Kiezatlas Objekte ist undefiniert.
Hinweis: Die Zeilenumbrüche und Einrückungen sind in der tatsächlichen Antwort nicht enthalten.
Multi-Kategorienfilter für die Volltextsuche
Die Angabe eines category Query Parameters ist optional.
Beim Anfragen von Kiezatlas Objekten können mehrere Familienportal Kategorien kombiniert werden, z.B. “Sprachförderung” UND (“Kinder” ODER “Jugendliche”). Die Anfrage ist im Prinzip wie oben, wobei der Query Parameter category mehrere (beliebig viele) Werte erhalten kann, mit Kommas getrennt, und der gesamte Query String mehrere (beliebig viele) category Query Parameter enthalten kann.
Beispiel:
GET /famportal/search?query=ehe&category=cat-12,cat-23&category=cat-45
Die Semantik so einer Anfrage ist:
- Die Ergebnismengen aller Kategorien eines category Parameters werden verODERt.
- Die Ergebnismengen aller category Parameter werden verUNDet.
Das Antwortformat ist wie oben.
Bezirksfilter für die Volltextsuche
Die Angabe eines district Query Parameters ist optional. Die zwölf aktuell gültigen Werte für den district Parameter entnehmen Sie bitte dem letzten Abschnitt der Kiezatlas Orte API Doku. Aktuell ist nur die Angabe eines Bezirks-Parameter unterstützt.
Beispiel:
GET /famportal/search?query=ehe&district=ka2.bezirk.mitte
Diese Anfrage schränkt die Ergebnisse der jeweiligen Volltextsuche auf Orte aus dem Bezirk Berlin-Mitte ein. Der Bezirksfilter kann auch zusätzlich zu dem Multi-Kategorienfilter eingesetzt werden.
Das Antwortformat ist wie oben.
Gezielte Abfrage Ortsinformation
Zur gezielten Abfrage einzelner Ortsinformationen verweisen wir Sie in an dieser Stelle auf den entspechenden Abschnitt in der Kiezatlas Orte API Dokumentation.
Einsendung von Notizen für Orte
Zur Integration der "Bearbeitungshinweise"-Funktion für Besucher_innen ihrer Website finden Sie alle relevanten Informationen in dem letzten Abschnitt der Kiezatlas Orte API Dokumentation.
Fehlerbehandlung
Die Antwort auf eine fehlerhafte Anfrage ist meist ein allgemeiner 500 Internal Server Error.
Fehlerhafte Anfragen sind z.B. das Fehlen des category Parameters oder die Angabe einer Familienportal Kategorie XML ID, die seitens Kiezatlas nicht bekannt ist.
