Kiezatlas Orte API

17. November 2016

Ü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:

http://api.kiezatlas.de/

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: 'http://api.kiezatlas.de/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: 'http://api.kiezatlas.de/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).