Über diese Seite
Dieses Dokument beschreibt die HTTP-basierte Kiezatlas Orte API zur programmatischen Integration von Kiezatlas Datensätzen in Ihre Website oder eine App. Der Zugriff auf unsere Ortsdatenbank erfolgt in dieser API über die Formulierung einer Volltextsuchanfrage.
Durch Nutzung dieser API können die Betreiber des Familienportals Datensätze aus dem Kiezatlas in das Familienportal einbinden. Zur Verfügung steht eine Volltextsuche mit einem optionalen Bezirksfilter. Die Anzeige von Kiezatlas Detailinformationen erfolgt innerhalb der Kiezatlas Website. Die API stellt Ihrer Anwendung dazu 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
Auf der Seite ihres Benutzerzugangs können Sie den API Zugang einfach beantragen. Dazu müssen Sie lediglich die Nutzungsbedingen der Kiezatlas Orte API gelesen, verstanden und akzeptiert haben.
Bei Fragen schreiben Sie bitte eine E-Mail an Reinhilde Godulla (godulla@sozkult.de) und wir werden uns zeitnah bei ihnen zurückmelden.
In case of questions please write an email to Reinhilde Godulla (godulla@sozkult.de) about your interests in the Kiezatlas Orte 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 Orten
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, den Straß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 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/t-309470',
geolocation: {'lon': 13.322874, 'lat': 52.444654},
anschrift: 'Rubensstraße 125, Haus 30, 4. Etage 12157 Berlin Deutschland',
id: 't-1245691'
},
...
]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: Bitte achten Sie darauf den Wert des query-Parameters als Wert einer URL zu enkodieren. Die Zeilenumbrüche und Einrückungen sind in der tatsächlichen Antwort nicht enthalten.
Bezirksfilter für die Volltextsuche
Die Angabe eines district Query-Parameters ist optional.
Beispiel:
GET /famportal/search?query=ehe&district=ka2.bezirk.mitte
Die Ergebnisse der Volltextsuche in diesem Beispiel werden eingeschränkt auf Orte die im Bezirk Berlin Mitte verortet sind. Das Antwortformat ist wie oben.
Alle zwölf aktuell gültigen Werte für die Nutzung des district Query-Parameters sind wie folgt (Name des Bezirks: URI-Wert des Bezirks).
Mitte: ka2.bezirk.mitte Friedrichshain-Kreuzberg: ka2.bezirk.friedrichshain-kreuzberg Tempelhof-Schöneberg: ka2.bezirk.tempelhof-schoeneberg Treptow-Köpenick: ka2.bezirk.tk Neukölln: ka2.bezirk.neukoelln Pankow: ka2.bezirk.pankow Charlottenburg-Wilmersdorf: ka2.bezirk.charlottenburg-wilmersdorf Spandau: ka2.bezirk.spandau Steglitz-Zehlendorf: ka2.bezirk.familienatlas-sz Lichtenberg: ka2.bezirk.lichtenberg Marzahn-Hellersdorf: ka2.bezirk.marzahn-hellersdorf Reinickendorf: ka2.bezirk.reinickendorf
Orte per ID abrufen
Die Angabe eines ids Parameter mit mindestens einer ID wird unter der folgenden Adresse benötigt.
Beispiel:
GET /famportal/geoobject/detail?ids=t-1245690
Das Antwortformat ist etwas detaillierter als bei den Ergebnissen der Volltextsuche. In diesem Fall enthalten die Orte zusätzlich auch noch ihre aktuelle Adresse (in dem Feld 'anschrift').
Beispiel einer Anfrage von Detailinformation zu einem bestimmten Ort mit mehreren IDs.
GET /famportal/geoobject/detail?ids=t-1245690,t-24514,123515
Sie können einem Request auch mehrere IDs übergeben. In diesem Fall müssen Sie die Werte mit einem Komma (",") trennen. Im Zuge eines Requests können Sie maximal Infos zu 15 Ortsdatensätzen abrufen.
Antwort:
[
{
name: 'Psychologische Beratung für Einzelne und Paare',
bezirk: 'Steglitz-Zehlendorf',
link: 'https://kiezatlas.berlin/website/geo/t-309470',
geolocation: {'lon': 13.322874, 'lat': 52.444654},
strasse_hnr: 'Rubensstraße 125, Haus 30, 4. Etage',
postleitzahl: '12157',
stadt: 'Berlin',
id: 't-1245691'
},
...
]Einsendung von Hinweisen zu Orten
Mit dieser Funktion können Sie uns dabei helfen unsere Ortsinformationen aktuell zu halten. Mit dieser Funktion können Sie einen Dialog in ihre Website integrieren durch den Besucher_innen ihrer Website uns Bearbeitungshinweise zuspielen können.
Diese Bearbeitungshinweise (ffg. auch Notizen genannt) tauchen dann in den Kiezatlas-Redaktionsoberflächen auf und helfen uns unsere Ortsinformation aktuell zu halten. Wir speicher diese Notizen an den Orten nicht öffentlich, diese sind also nur von den beiden Personengruppen (Kiez-Admin, Einrichtungsinhaber_in) einsehbar.
Für die Einsendung von Bearbeitungshinweisen muss die ID des jeweiligen Ortes Teil der Adresse sein. Der Request Body ist ein String-Wert in dem ein einfaches JSON Objekt kodiert ist-
Beispiel:
POST /famportal/comment/t-1245690
Content-Type: application/json
Request Body:
{
'message': 'Inhalt des Bearbeitungshinweises, z.B.: "Ist umgezogen, bitte prüfen"',
'contact': 'Kontakt/Ansprechpartner_in für den Hinweis (Optional)'
}
Damit die Anfrage verarbeitet wird muss das JSON Objekt im Request Body mindestens das Attribut "message" haben.
Im Erfolgsfall antwortet unsere API mit.
HTTP/1.1 204 No Content
Bei fehlender Berechtigung zur Nutzung dieser API-Funktion mit 401.
Fehlerbehandlung
Die Antwort auf eine fehlerhafte Anfrage ist meist ein allgemeiner 500 Internal Server Error.
Fehlerhafte Anfragen sind z.B. das Fehlen des query Parameters (Volltextsuche), die Angabe einer Seitens Kiezatlas unbekannten Bezirks- (district) oder Orte Identifiers (ids).
