Search Forum



Our Magazines

[GOV] Webservice

1

Monday, June 5th 2017, 9:20am

Webservice

Die Beschreibung bei http://wiki-de.genealogy.net/GOV/Webservice#Lesezugriff ist etwas spartanisch ausgefallen. Bei https://forum.genealogy.net/index.php?pa…&threadID=68350 habe ic z.B. getParentObjectWithTypeAtDate entdeckt, was im Wiki nicht beschrieben ist.

Gibt es irgendwo eine genauere Beschreibung, möglichst mit Praxisbeispielen? Gibt es noch andere interessante Funktionen, die im Wiki nicht aufgelistet sind?

jzedlitz

Administrator

Location: Kiel

Societies: Verein für Computergenealogie

  • Send private message

2

Tuesday, June 6th 2017, 1:41pm

getParentObjectWithTypeAtDate

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:

Source code

1
2
3
4
5
6
7
8
9
10
11
12
13
<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.

jzedlitz

Administrator

Location: Kiel

Societies: Verein für Computergenealogie

  • Send private message

3

Wednesday, June 7th 2017, 7:54am

searchByBoundingBox

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:

Source code

1
2
3
4
5
6
7
8
9
10
11
<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>

jzedlitz

Administrator

Location: Kiel

Societies: Verein für Computergenealogie

  • Send private message

4

Thursday, June 8th 2017, 8:58am

searchByName

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.

Source code

1
2
3
4
5
6
7
<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:

Source code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<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:

Source code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<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>

5

Thursday, June 8th 2017, 11:24am

Herzlichen Dank, das ist Klasse und beantwortet schon einige offene Fragen.

Aber wäre es nicht sinnvoller, das im GenWiki (http://wiki-de.genealogy.net/GOV/Webservice) einzubringen? Da gibt es ja schon den mageren Ansatz, derf laut nach Ergänzung schreit

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

jzedlitz

Administrator

Location: Kiel

Societies: Verein für Computergenealogie

  • Send private message

6

Friday, June 9th 2017, 10:09am

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.

jzedlitz

Administrator

Location: Kiel

Societies: Verein für Computergenealogie

  • Send private message

7

Friday, June 9th 2017, 10:26am

searchByNameAndType

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:

Source code

1
2
3
4
5
6
7
8
<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>

8

Friday, June 9th 2017, 1:11pm

Man könnte also in unseren Beispiel auch nach schonkirchen suchen.
Sogar nach Киев oder Київ, oder Кёнигсберг, was sicherlich für Forscher interessant ist, die Vorfahren im (fernen) Osten haben.

9

Friday, June 9th 2017, 1:21pm

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.
Gut, damit kann man leben. Da ich ich aber verschiedene Dienste abfrage (OSM, Geonames, Google usw.) muss ich mich wohl an unterschiedliche Formate gewöhnen. Kann kein Fehler sein, sich mit SOAP vertraut zu machen.

Unter [GOV] Webservice Funktion gesucht! habe ich schon angedeutet, was für meine Anwendung ideal wäre. Immerhin sind diesbezüglich OSM-Nominatim und Geonames sehr flexibel, jedoch fehlen leider die historischen Ortsnamen.

jzedlitz

Administrator

Location: Kiel

Societies: Verein für Computergenealogie

  • Send private message

10

Saturday, June 10th 2017, 8:23am

searchRelatedByName

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

Source code

1
2
3
4
5
6
7
8
<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>

jzedlitz

Administrator

Location: Kiel

Societies: Verein für Computergenealogie

  • Send private message

11

Monday, June 12th 2017, 8:36am

getObjectByExternalId

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:

Source code

1
2
3
4
5
6
7
8
<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

jzedlitz

Administrator

Location: Kiel

Societies: Verein für Computergenealogie

  • Send private message

12

Tuesday, June 13th 2017, 12:32pm

getNameAtDate

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:

Source code

1
2
3
4
5
6
7
8
9
<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.

Source code

1
2
3
4
5
6
7
8
9
<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:

Source code

1
2
3
4
5
6
7
8
9
<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>

JanX

Trainee

Societies: CompGen, Die Maus

  • Send private message

13

Saturday, February 23rd 2019, 8:27am

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?

jzedlitz

Administrator

Location: Kiel

Societies: Verein für Computergenealogie

  • Send private message

14

Sunday, April 14th 2019, 8:04pm

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