Stefan’s Blog

Fortsetzung von “API für pfadis.com”

Suche mit Orts- oder Stammesnamen

Nachfolgend ein Beispiel zur Suche mit der pfadis.com API:

http://pfadis.com/app/api/rest/Unit?q= schwerte&short=true

Wie unschwer zu erkennen ist, ist “q” der Suchparameter. Mit “short=true” wird ein übersichtliches Ergebnis ohne weitere Infos zu den gefundenen Stämmen/Bezirken/etc. geliefert:

{
    "result": [
        {
            "id":507,
            "url":"http:\/\/pfadis.com\/app\/api\/rest\/Unit\/507",
            "fullname":"16\/02\/04 | Stamm St. Marien (Schwerte)",
            "type":"Unit"
        }
    ],
    "page":1,
    "rpp":20,
    "total":1,
    "previous_page":null,
    "next_page":null,
    "q":"schwerte"
}

Die Suche hat genau ein Ergebnis geliefert: den Stamm St. Marien Schwerte. Gesucht werden kann nach Stammesnamen und Ortsbezeichnungen.

Suche mit geografischem Bezug

Als Suchparameter “q” eignen sich auch Ortsbezogene Angaben. So können Stämme (bzw, um genau zu sein, Stämme, denen eine Adresse zugeordnet ist) in der Nähe eines bestimmten PLZ-Bereiches gefunden werden:

http://pfadis.com/app/api/rest/Unit?q=58239&dist=10&short=true

Der Parameter “dist” gibt den Radius in Kilometern an, in dem gesucht werden soll.

{
    "result":[
        {
            "id":507,
            "url":"http:\/\/pfadis.com\/app\/api\/rest\/Unit\/507",
            "fullname":"16\/02\/04 | Stamm St. Marien (Schwerte)",
            "type":"Unit",
            "distance":0
        },
        {
            "id":514,
            "url":"http:\/\/pfadis.com\/app\/api\/rest\/Unit\/514",
            "fullname":"16\/01\/21 | Stamm Berghofen (Dortmund-Berghofen)",
            "type":"Unit",
            "distance":5.98
        },
        {
            "id":526,
            "url":"http:\/\/pfadis.com\/app\/api\/rest\/Unit\/526",
            "fullname":"16\/01\/07 | Stamm Dortmund-Soelde (Dortmund-Soelde)",
            "type":"Unit",
            "distance":6.26
        },
        {
            "id":516,
            "url":"http:\/\/pfadis.com\/app\/api\/rest\/Unit\/516",
            "fullname":"16\/01\/19 | Stamm Bonifaten 80 (Dortmund-Lichtendorf\/S\u00f6lderholz)",
            "type":"Unit",
            "distance":6.26
        },
        {
            "id":518,
            "url":"http:\/\/pfadis.com\/app\/api\/rest\/Unit\/518",
            "fullname":"16\/01\/17 | Stamm St. Ewaldi (Dortmund-Aplerbeck)",
            "type":"Unit",
            "distance":6.76
        },
        {
            "id":508,
            "url":"http:\/\/pfadis.com\/app\/api\/rest\/Unit\/508",
            "fullname":"16\/02\/03 | Stamm Hagen-Boele (Hagen-Boele\/Helfe)",
            "type":"Unit",
            "distance":7.3
        },
        {
            "id":509,
            "url":"http:\/\/pfadis.com\/app\/api\/rest\/Unit\/509",
            "fullname":"16\/02\/02 | Stamm St. Bonifatius (Hagen-Hohenlimburg)",
            "type":"Unit",
            "distance":8.24
        },
        {
            "id":522,
            "url":"http:\/\/pfadis.com\/app\/api\/rest\/Unit\/522",
            "fullname":"16\/01\/13 | Stamm Marcel Callo (Dortmund-H\u00f6rde)",
            "type":"Unit",
            "distance":8.35
        },
        {
            "id":498,
            "url":"http:\/\/pfadis.com\/app\/api\/rest\/Unit\/498",
            "fullname":"16\/02\/16 | Stamm Arche (Iserlohn)",
            "type":"Unit",
            "distance":9.06
        },
        {
            "id":506,
            "url":"http:\/\/pfadis.com\/app\/api\/rest\/Unit\/506",
            "fullname":"16\/02\/06 | Stamm St. Elisabeth (Hagen)",
            "type":"Unit",
            "distance":9.59
        }
    ],
    "page":1,
    "rpp":20,
    "total":10,
    "previous_page":null,
    "next_page":null,
    "q":"58239"
}

Der Suchparameter “q” nimmt auch zwei mit Semikolon getrennte Dezimalzahlen entgegen und interpretiert diese dann als geografischen Punkt:

http://pfadis.com/app/api/rest/Unit?q=51.4;7.6&dist=10&short=true

Konkrete Codebeispiele folgen.

Viel Spaß beim Testen – Feedback ist erwünscht.

pfadis.com hat ein API bekommen. Ein REST-API, um genau zu sein. Bisher empfängt und liefert es Daten im JSON-Format.

Zum Erforschen des API empfehle ich die Verwendung von Firefox mit JSONView-AddOn. Damit lässt sich wunderbar im Browser sehen und verfolgen, welche Daten und URIs geliefert werden.

Bevor ich lange erzähle, hier ein Beispiel:

http://pfadis.com/app/api/rest/Unit

{
    result : [],
    page: 1,
    rpp: 20,
    total: 8290,
    previous_page: null,
    next_page: "http://pfadis.com/app/api/rest/Unit?page=2",
    q: null
}

Diese URL zeigt alle Units (Stämme, Bezirke, Diözesen aber auch Arbeitskreise und Stufen) an. Der obige Aufruf liefert 20 Einträge pro Seite im (oben leeren) “result” Array. Mit “previous_page” und “next_page” werden die passenden URLs zum durchforsten aller Ergebnisse mitgeliefert.

Fortsetzung “Suche mit dem REST-API”