Webservice

Die Dokumentation des GOV lässt hier wirklich zu wünschen übrig. Zeit, dies zu ändern! Ich werde in diesem Thread jeden Tag eine Operation des SOAP-Webservices erklären. Gerne mit eigenen Beobachtungen, Nachfragen etc. kommentieren. Am Ende sollten wir dann eine vollständige Dokumentation haben.

Als erstes nehme ich mir die Operation getParentObjectWithTypeAtDate vor. Die Operation dient dazu, übergeordnete Verwaltungseinheiten eines bestimmten Typs zu finden. So kann man z.B. herausfinden, zu welchem Landkreis ein Wohnplatz gehört. Drei Parameter werden benötigt: childId, interestingTypes und julianDate. childId enthält die GOV-Kennung des Ortes. interestingTypes ist eine Liste der Objekttypen, die übergeordnete Verwaltungseinheiten haben müssen. Mit julianDate wird schließlich der Zeitpunkt angegeben, an dem man interessiert ist.

Beispiel: Wir suchen den Kreis, zu dem das Dorf Moldenit am 1. Mai 1975 gehörte. Moldenit hat die GOV-Kennung MOLNIT_W2381. Die Nummer der Objekttypen findet man hier heraus: http://gov.genealogy.net/type/list. Für unsere Anfrage sind 32 (Kreis), 36 (Landkreis) und 53 (Stadtkreis) relevant. Im GOV wird mit der in den Naturwissenschaften gebräuchliche Tageszählung Julianisches Datum (JD) gearbeitet. Dafür gibt es z.B. unter http://aa.usno.navy.mil/data/docs/JulianDate.php einen Umrechner. Das (JD) für den 1. Mai 1975 ist 2442534. Die vollständige Anfrage lautet also:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://gov.genealogy.net/ws">
   <soap:Body>
      <ws:getParentObjectWithTypeAtDate>
         <childId>MOLNIT_W2381</childId>
         <interestingTypes>
            <ws:int>32</ws:int>
            <ws:int>36</ws:int>
            <ws:int>53</ws:int>
         </interestingTypes>
         <julianDate>2442534</julianDate>
      </ws:getParentObjectWithTypeAtDate>
   </soap:Body>
</soap:Envelope>

Als Antwort wird adm_131059 (bzw. das komplette Objekt, wenn man den ComplexService verwendet hat) für Schleswig-Flensburg zurückgeliefert.

Die Operation searchByBoundingBox dient dazu, Einträge innerhalb einer vorgegebenen geographischen Region zu finden. Die Region wird dabei durch die nördliche und südliche Breite sowie die westliche und östliche Länge beschrieben. Geographischen Länge und Breite werden als Gradangabe mit Komma angegeben. Als Beispiel wollen wir uns Einträge in der in etwa hier gezeigten Region http://www.openstreetmap.org/#map=14/54.4151/10.3538 ansehen. Die Grenzen sind

• 54.442°N im Norden,
• 54.3763°N im Süden,
• 10.2745°O im Westen und
• 10.4447°O im Osten.

Die Operation hat vier Parameter: latitude0, latitude1, longitude0 und longitude1. Dabei ist nur wichtig, dass die Breitenangabe in ein latitude- und die Längenangabe in ein longitude-Feld kommt, die Reihenfolge (Nord/Süd bzw. Ost/West) ist egal.

Für unser Beispiel sieht der Aufruf also so aus:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://gov.genealogy.net/ws">
   <soap:Header/>
   <soap:Body>
      <ws:searchByBoundingBox>
         <latitude0>54.4419</latitude0>
         <latitude1>54.3763</latitude1>
         <longitude0>10.4447</longitude0>
         <longitude1>10.2745</longitude1>
      </ws:searchByBoundingBox>
   </soap:Body>
</soap:Envelope>

Die Operation searchByName entspricht der alten einfachen Suche in der GOV-Weboberfläche. Als einziger Parameter wird ein Name bzw. der Teil eines Namens erwartet.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://gov.genealogy.net/ws">
   <soap:Body>
      <ws:searchByName>
         <placename>Schönkirchen</placename>
      </ws:searchByName>
   </soap:Body>
</soap:Envelope>

Es wird noch Ortsnamen gesucht, die mit dem angegebenen Text beginnen. Statt Schönkirchen könnte man auch nach Schönkirch suchen. Groß- und Kleinschreibung wird ignogiert, so dass auch eine Suche nach schönkirchen erfolgreich wäre. Auch diakritische Zeichen werden ignoriert, so dass man ein Ö auch bei der Suche nach O findet. Man könnte also in unseren Beispiel auch nach schonkirchen suchen.

An dieser Stelle kann ich gut den Unterschied zwischen SimpleService und ComplexService erklären. Prinzipiell bieten beide Dienste die gleichen Operationen. Der Unterschied liegt jedoch in der Art der Antwort. Der SimpleService antwortet nur mit einer Liste von GOV-Kennungen. Das sieht in dem Beispiel so aus:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:searchByNameResponse xmlns:ns1="http://gov.genealogy.net/ws">
         <out xmlns:ns2="http://gov.genealogy.net/data" xmlns:ns3="http://gov.genealogy.net/ws">
            <ns3:item>SCHHENJN88II</ns3:item>
            <ns3:item>object_307618</ns3:item>
            <ns3:item>SCHHENJO54CI</ns3:item>
            <ns3:item>object_184995</ns3:item>
            <ns3:item>object_1087649</ns3:item>
            <ns3:item>object_149315</ns3:item>
            <ns3:item>SCHHE1JO54CI</ns3:item>
         </out>
      </ns1:searchByNameResponse>
   </soap:Body>
</soap:Envelope>

Beim ComplexService werden hingegen alle Informationen zu den gefundenen Objekten übertragen. Ein komplettes Beispiel erspare ich uns, hier nur der Beginn der Antwort:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:searchByNameResponse xmlns:ns1="http://gov.genealogy.net/ws">
         <out xmlns:ns2="http://gov.genealogy.net/data" xmlns:ns3="http://gov.genealogy.net/ws">
           <ns2:object last-modification="2008-12-10T21:34:39.000+01:00" id="SCHHENJN88II">
               <ns2:position type="p" height="161" lat="48.3667" lon="16.7"/>
               <ns2:external-reference value="opengeodb:63741"/>
               <ns2:external-reference value="opengeodb:43003577"/>
               <ns2:name value="Schönkirchen" lang="deu"/>
               <ns2:type value="68">
                  <ns2:source ref="source_306239">
                     <ns2:page>103</ns2:page>
                  </ns2:source>
               </ns2:type>
               <ns2:population year="2001" value="1221">
                  <ns2:source ref="source_306239">
                     <ns2:page>103</ns2:page>
                  </ns2:source>
               </ns2:population>

Zitat von Gadacz

Gibt es eigentlich auch andere Ausgabeformate außer wsdl/xml, z.B. JSON?

Nein, das ist der Natur eines SOAP-Webservices geschuldet. Es gibt ein weiteres API, das jedoch bislang nur intern verwendet wird. Daher gibt es dazu auch noch keine Dokumentation. Nach der Beschreibung des SOAP-Webservices würde ich mich an die Beschreibung machen. Die Funktionen sind bisher auch nur sehr begrenzt, nämlich die Ausgabe eines Namens und einer Position. Bevor ich das erweitere, würde ich gerne wissen, welche Funktionen überhaupt gewünscht sind. Das sollten wir aber in einem eigenen Thread diskutieren.

Mit searchByNameAndType kann man im Vergleich zu searchByName genauer steuern, welche Ergebnisse man bekommen möchte. Die Operation hat zwei Parameter:

• placename
• types

Bei placename wird der gesuchte Ortsname eingetragen. Hier gibt es die gleichen Möglichkeiten, wie auch bei der searchByName-Operation. Im Parameter types werden die Nummern der Objekttypen angegeben, nach denen gesucht wird.

Angenommen, wir wollen nach Objekten auf Gemeinde-Ebene suchen. Dazu zählten (in Preußen) die Objekttypen Gemeinde (18), Landgemeinde (85), Stadt Gebietskörperschaft (150), Gutsbezirk (108) und Forstgutsbezirk (109). Die Nummern der Objekttypen kann man hier nachschlagen: http://gov.genealogy.net/type. Sollen - wie in unserem Fall - mehrere Objekttypen gesucht werden, so werden die Nummern hintereinander durch Komma getrennt aufgeschrieben, also "18,85,108,109,150".

Der komplette Aufruf sieht dann so aus:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://gov.genealogy.net/ws">
   <soap:Body>
      <ws:searchByNameAndType>
         <placename>Schönkirchen</placename>
         <types>18,85,108,109,150</types>
      </ws:searchByNameAndType>
   </soap:Body>
</soap:Envelope>

Mit Hilfe der searchRelatedByName Operation kann man nach einem Ort A suchen, der irgendwann zu einem Ort B gehörte. Sie entspricht der "Suche nach zwei Objekten" auf der GOV-Webseite.

Zwei Parameter werden benötigt:

• superordinateName - Name des übergeordneten Objekts
• subordinateName[size=10] - Name des Ortes, der gesucht wird

Als Beispiel wollen wir nach "Schönberg in Holstein" suchen. "Holstein" ist der superordinateName und "Schönberg" der subordinateName.

Die komplette Anfrage sieht so aus:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://gov.genealogy.net/ws">
   <soap:Body>
      <ws:searchRelatedByName>
         <superordinateName>Holstein</superordinateName>
         <subordinateName>schönberg</subordinateName>
      </ws:searchRelatedByName>
   </soap:Body>
</soap:Envelope>

Das GOV ist mit zahlreichen anderen Ortsverzeichnissen verknüpft. Dazu enthalten die GOV-Objekte Verweise auf diese anderen Ortsverzeichnisse. Mit Hilfe der getObjectByExternalId Operation kann man sich ein GOV-Objekt anhand der Kennung in einem externen System geben lassen. Sie erwartet zwei Parameter:

• system - Kürzel für das externe System. Eine Liste der derzeit verwendeten Kürzel ist unten zu finden.
• ref - Identifikator, unter dem der Eintrag im externen System geführt wird.

Ein verknüpftes Verzeichnis ist die Ortsdatenbank der Bayerischen Landesbibliothek Online (BLO). Dort gibt es z.B. einen Eintrag Nummer 125 zur Gemeinde Emmerting. Um diesen Eintrag aus dem GOV abzurufen, kann folgende Anfrage verwendet werden:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://gov.genealogy.net/ws">
   <soap:Body>
      <ws:getObjectByExternalId>
         <system>BLO</system>
         <ref>125</ref>
      </ws:getObjectByExternalId>
   </soap:Body>
</soap:Envelope>

Fordert man eine nicht existierende Kennung an, so bekommt man eine SOAP-Fault als Antwort.

Liste der momentan verknüpften Verzeichnisse:

• BLO - Kennung des Ortes/Gemeinde beim Bayerischen Landesarchiv
• geonames - Wohnplatz bei geonames.org
• GND - Gemeinsame Normdatei der Deutschen Nationalbibliothek
• INSEE - Code Insee
• nima - National Imagery and Mapping Agency unique feature identifier
• NUTS1999 - Nomenclature des unités territoriales statistiques 1999
• NUTS2003 - Nomenclature des unités territoriales statistiques 2003
• opengeodb - Gemeinde bei OpenGeoDB
• osm-boundary - OpenStreetMap Gemeindegrenze
• SCB - Schwedetisches Statistikamt
• SIMC - offizielles polnisches nationale Register der Wohnplätze
• TERYT - offizielles polnisches nationale Register der Gebietseinheiten
• UN/LOCODE - United Nations Code for Trade and Transport Locations
• westpreussen.de - westpreussen.de
• wikidata - Wikidata

Die Operation getNameAtDate dient dazu, einen Namen für ein Objekt im GOV zu bestimmen. Das ist in Fällen interessant, in denen für ein Objekt eine Vielzahl von Namen in verschiedenen Sprachen und zu verschiedenen Zeiten eingetragen wurde. Man muss dann lokal keine Logik zum Bestimmen des Namens haben, sondern kann einfach diese Operation verwenden.

Drei Parameter werden benötigt:

• itemId - die GOV-Kennung des Objektes, von dem man den Namen wissen möchte
• julianDate - das Julianische Datum (JD)
• preferredLanguage - eine bevorzugte Sprache (ISO-639-2 Code)

Die Angabe preferredLanguage kann auch leer sein (das Element darf aber nicht fehlen). Dann wird keine Sprache besonders bevorzugt.

Als Beispiel habe ich ein schlesisches Dorf http://gov.genealogy.net/KETORFJO70XW gewählt, das nach dem 2. Weltkrieg einen polnischen Namen bekommen hat. Fragen wir zunächst den aktuellen Namen (JD heute ist 2457918) ohne spezielle Sprachauswahl ab. Das sieht so aus:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://gov.genealogy.net/ws">
  <soap:Body>
      <ws:getNameAtDate>
         <itemId>KETORFJO70XW</itemId>
         <julianDate>2457918</julianDate>
         <preferredLanguage></preferredLanguage>
      </ws:getNameAtDate>
   </soap:Body>
</soap:Envelope>

Der zuletzt vergebene Name ist der polnische, also bekommen wir "Kaczorów" zurück. Setzen wir als Sprache "pol" ein, so bekommen wir auch diesen Wert zurück.

Verwenden wir jedoch "deu" als Sprachauswahl, so wird der deutsche Namen zurückgegeben.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://gov.genealogy.net/ws">
  <soap:Body>
      <ws:getNameAtDate>
         <itemId>KETORFJO70XW</itemId>
         <julianDate>2457918</julianDate>
         <preferredLanguage>deu</preferredLanguage>
      </ws:getNameAtDate>
   </soap:Body>
</soap:Envelope>

Fragen wir ohne Sprachauswahl den Namen im Jahr 1900 ab (JD=2415184), so bekommen wir den deutschen Namen, da dies der damals gültige war:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://gov.genealogy.net/ws">
  <soap:Body>
      <ws:getNameAtDate>
         <itemId>KETORFJO70XW</itemId>
         <julianDate>2415184</julianDate>
         <preferredLanguage></preferredLanguage>
      </ws:getNameAtDate>
   </soap:Body>
</soap:Envelope>

Moin,

oben war ja schon mal nach alternative Möglichkeiten gefragt worden. Da möchte ich hier mal nachhaken:

1) JSON wäre natürlich super, aber bei SOAP halt etwas ... schwierig

2) Ich bin eher der REST-Typ. SOAP ist nicht so ganz meine Welt. Gibt es die Möglichkeit, auch per REST auf die Daten zuzugreifen?

Zum Thema REST-API habe ich einen neuen Thread aufgemacht.