Help:De:API-Dokumentation

Search WikiTree's help pages:

Categories: WikiTree-Hilfe | Entwicklerhilfe | WikiTree Apps Project (DE)

Sprache: en | de | nl
Haftungsausschluss: Dies ist eine inoffizielle Übersetzung. Die englischsprachigen Versionen sind die offiziellen Hilfeseiten.
Übersetzt: D. Lewerenz, Geprüft: I. Caruso, 22 Jan 2021

Es gibt eine grundlegende API, die für jedes WikiTree-Mitglied verfügbar ist, das durch seine Programmierkenntnisse zur Gemeinschaft beitragen möchte. Sie unterstützt Abfragen für verschiedene Datenelemente, die in WikiTree-Profilen enthalten sind.

Wenn Du irgendwelche Fragen hast, füge Dich bitte selbst zur WikiTree Apps Google Group hinzu und frage dort nach. Danke!.

Contents

Wie man auf die WikiTree-API zugreift

Auf die WikiTree-API kann über HTTP-Aufrufe zu Port 80 zugegriffen werden. Aufrufe sollten an https://api.wikitree.com/api.php erfolgen.

Dies ist keine voll funktionsfähige öffentliche API. Die API ist schreibgeschützt. Sie unterstützt die folgenden Funktionen:

  • getProfile : Die Funktion getProfile liefert einen Standardsatz von Feldern für eine bestimmte Schlüssel-(WikiTree-ID oder Seiten-ID-Nummer). Dieser Standardsatz umfasst die verschiedenen Namensfelder, Geburts-/Todesdaten, Geschlecht und die Mutter- und Vater-ID-Werte. Zusätzlich zu diesen Standardeinstellungen gibt es optionale Felder, die Du über den Parameter "fields" (Felder) anfordern kannst. Zu diesen zusätzlichen Feldern gehören: Eltern, Kinder, Geschwister und Ehepartner. Wenn Du diese Felder anforderst, dann enthält die zurückgegebene JSON Personenprofildaten für die relevanten Personen.
  • getPerson : Die getPerson-Funktion wurde zugunsten des flexibleren getProfile weitgehend vernachlässigt. Sie funktioniert jedoch immer noch und kann nützlich sein, wenn Deine App ein Profil unter Verwendung einer Benutzer-ID-Nummer und nicht der Seiten-ID-Nummer, die getProfile verwendet, anfordern muss (z.B. um eine Mutter/Vater-ID zu verwenden und die Profildaten dieses Elternteils zu erhalten). Es akzeptiert einen "fields"-Parameter und gibt Daten genau wie getProfile zurück. Der einzige Unterschied ist die Akzeptanz einer Benutzer-ID für den Schlüssel.
  • getAncestors : Ruft Vorfahren für eine bestimmte Person ab.
  • getRelatives: Ruft Familienmitglieder in alle Richtungen ab, nicht nur die Vorfahren.
  • searchPerson : Gibt eine Liste von Personenprofilen zurück, die den angegebenen Kriterien entsprechen.

Um ein Verzeichnis auf dem Apps-Server für Dich erstellen zu lassen - egal ob Du eine echte Anwendung hochladen oder nur experimentieren möchtest - tritt dem WikiTree Apps Project bei.

Bibliotheken werden derzeit entwickelt, um die API-Nutzung sowohl in Python als auch in Javascript zu demonstrieren.

Wenn Du nicht weisst, wo Du anfangen sollst, mach Dir keine Sorgen. Schicke eine E-Mail an <WikiTreeApps@googlegroups.com> und die Community wird dir helfen.

Daten auf dem Apps-Server

Die API ruft Daten vom WikiTree-Apps-Server ab. Dadurch wird sichergestellt, dass Apps den normalen Betrieb von WikiTree nicht stören können.

Die Apps-Daten sollten im Wesentlichen mit den Live-Daten übereinstimmen. Es wird eine schreibgeschützte Kopie der primären WikiTree-Datenbank verwendet. Es gibt Zeiten, in denen starke Änderungen auf dem Live-Server vorgenommen werden, so dass die Apps-Kopie für kurze Zeit hinterherhängt (es handelt sich um einen weniger leistungsfähigen Rechner), aber in der Regel ist sie innerhalb von Sekunden oder weniger vollständig mit den Live-Daten auf dem neuesten Stand.

Sicherheit

Die WikiTree-API erweitert das bestehende Vertrauenslisten-Sicherheitsmodell der WikiTree-Webseite. Die von der API zurückgegebenen Informationen werden auf das beschränkt, was dem aktuell angemeldeten Benutzer zur Verfügung steht.

Jedes WikiTree-Mitglied kann sich in eine auf apps.wikitree.com laufende App einloggen, es sei denn, Du verbirgst Deine Anwendung.

Parameter

Die WikiTree-API erfordert bestimmte Parameter, um die gewünschten Ergebnisse zurückzugeben. Zwei Parameter sind bei allen Funktionen gleich. Diese sind:

  • action : Die Aktion/ Funktion zum Ausführen (z.B. "getProfile").
  • Format : Das Format der zurückgegebenen Daten. Dies ist entweder "json", für JSON (JavaScript Object Notation) oder "xml" für XML (Extensible Markup Language). Die Vorgabe ist, dass die Daten in JSON zurückgegeben werden.

Zusätzlich zu "action" und "format" akzeptieren einige der API-Funktionen weitere Parameter.

Authentifizierung

Viele Operationen mit der API können ohne jegliche Authentifizierung verwendet werden. Öffentliche Profile können einfach mit der Aktion getProfile abgerufen werden. Um jedoch Daten für private Profile abzurufen, muss sich der Benutzer bei einem Benutzer-Account authentifizieren, der sich auf der Vertrauensliste für diese Profile befindet.

Die Authentifizierung ist ein mehrstufiger Prozess. Der Benutzer geht zu api.wikitree.com, wo er sich mit seinen WikiTree-Anmeldedaten anmeldet. Bei der Anmeldung erhält der Benutzer ein Sitzungs-Cookie für zukünftige Anfragen an die API und wird dann mit einem Token zur Anwendung zurückgeschickt. Die Anwendung kann dann das Token mit der API validieren und die ID des Benutzers speichern. Etwas ausführlicher...

Der erste Schritt besteht darin, den Benutzer zur Authentifizierung zu schicken. Dadurch kann er sich bei WikiTree anmelden, ohne Anmeldedaten für eine Drittanbieter-Anwendung angeben zu müssen. Du solltest die Benutzer nicht direkt nach ihren Anmeldedaten fragen.

https://api.wikitree.com/api.php?action=clientLogin&returnURL=[kodierte URL der Anwendung]

Die API sendet den Benutzer mit einem "authcode"-Parameter an returnURL zurück. Die Anwendung sollte dann an die API-URL mit action gleich "clientLogin" und authcode gleich dem empfangenen Wert posten. Die zurückgegebenen Daten werden "result = Success" enthalten, wenn der Autorisierungscode bestätigt wird. Du kannst dann in deiner Anwendung vermerken, dass der Benutzer angemeldet ist. Das Ergebnis der Client-Anmeldung enthält auch die user_id und den user_name des Benutzers (d.h. die WikiTree-ID), die die Anwendung zur späteren Verwendung speichern kann.

Beachte, dass Du beim Posten an die API-URL sicherstellen solltest, dass die Sitzungs-Cookies des Benutzers mitgeschickt werden. In JavaScript wird dies durch Setzen von XMLHttpRequest.withCredentials = true erreicht. Mit jQuery setzt man "xhrFields: { withCredentials: true }" im $.ajax-Aufruf.

Der ClientLogin-Prozess wird ausführlich auf der API-Demoseite demonstriert.

getProfile

Die Funktion getProfile funktioniert für Personenprofile und Free-Space Profile.

key' : Dies ist entweder die Person.Name (WikiTree-ID, z.B. "Adams-35"), die Space page_name (z.B. "Space:Allied_POW_camps") oder das ganzzahlige Profil PageId.

fields : Dieser Parameter beschreibt, welche Felder aus dem Personenprofil von der API zurückgegeben werden sollen. Zu den verfügbaren Feldern gehören:

Id, Name, FirstName, MiddleName, MiddleInitial, LastNameAtBirth, LastNameCurrent, Nicknames, LastNameOther, RealName, Prefix, Suffix (ID, Vorname, Mittelname, Mittelinitiale, Geburtsname, Aktueller Nachname, Spitznamen, Andere Nachnamen, Tatsächlicher Name, Präfix, Suffix)
Gender, BirthDate, DeathDate, BirthLocation, DeathLocation, BirthDateDecade, DeathDateDecade, Photo (Geburtsdatum, Sterbedatum, Geburtsort, Sterbeort, Geburtsdekade, Sterbedekade, Foto)
Mother, Father, Parents, Children, Siblings, Spouses (Mutter, Vater, Eltern, Kinder, Geschwister, Ehepartner)
HasChildren, NoChildren, Touched, IsLiving, Privacy, DataStatus (Hat Kinder, Keine Kinder, Berührt, Datenschutz, Datenstatus)
Derived.ShortName, Derived.BirthNamePrivate, Derived.LongNamePrivate, Derived.LongName, Derived.BirthName (Abgeleiteter Kurzer Name, Abgeleiteter kurzer Name im Status Privat, Abgeleiteter vollständiger Name im Status Privat, Abgeleiteter vollständiger Name, Abgeleiteter Geburtsname)
Manager

Das BirthDate (Geburtsdatum) und das DeathDate (Sterbedatum) sind JJJJJ-MM-TT und können Nullen für das Jahr oder den Monat haben, wenn das Datum unvollständig ist. Die Felder BirthDateDecade (Geburtsdekade) und DeathDateDecade (Sterbedekade) sind Zeichenfolgen wie "1960's".

Die Felder Mother (Mutter) und Father (Vater) sind die Id-Werte für die Eltern des angeforderten Profils. Diese können verwendet werden, um weitere Profildaten abzurufen, z.B. mit einem weiteren Anruf bei getPerson. Wenn der Feldwert "Parents" (Eltern) enthält, dann werden die Profildaten für die Mutter und den Vater zusammen mit dem ursprünglichen Profil zurückgegeben. Auf ähnliche Weise kannst Du die Kinder, Geschwister und Ehepartner eines Profils anfordern. Die Felder, die für die Profile dieser zusätzlichen Verwandten zurückgegeben werden, sind die gleichen wie die Felder, die für das angeforderte Profil zurückgegeben werden.

Das Feld HasChildren (Hat Kinder) bedeutet, dass das Profil Kinder hat. Das Feld NoChildren (Keine Kinder) ist das Ankreuzfeld "no more children" (keine weiteren Kinder) auf der Bearbeitungsseite.

DataStatus enthält die Datenkennzeichen für die folgenden Felder: FirstName, LastNameCurrent, RealName, BirthDate, DeathDate, BirthLocation, DeathLocation, Father, Mother, Spouse, MiddleName, LastNameAtBirth, ColloquialName, Nicknames, Gender, Prefix, Suffix, LastNameOther (Vorname, Aktueller Nachname, Tatsächlicher Nachname, Geburtsdatum, Sterbedatum, Geburtsort, Sterbeort, Vater, Mutter, Ehepartner, Mittelname, Geburtsname, umgangssprachlicher Name, Spitznamen, Geschlecht, Präfix, Suffix, Andere Nachnamen). Vater und Mutter haben einen numerischen Code: 30 = mit DNA bestätigt, 20 = vertrauenswürdig, 10 = unsicher, 5 = nicht biologisch.

Beachte, dass nicht alle Felder für alle Profile verfügbar sind. Der Zugriff hängt von der Datenschutz-Einstellung ab und davon, ob sich der angemeldete Benutzer auf der Vertrauensliste des Profils befindet.

Das Verhalten bezüglich fehlender und als Privat eingestufter Familienmitglieder für alle API-Funktionen ist wie folgt:

  1. Wenn das Startprofil keinen öffentlichen Stammbaum hat (Datenschutzstatus < 35) und der Benutzer nicht auf der Vertrauensliste steht, werden die Felder/Objekte für Verwandte vollständig ausgeschlossen.
  2. Wenn das Startprofil einen öffentlichen Stammbaum hat (Status >= 35), aber ein Verwandter fehlt, wird ein Nullwert ("0") zurückgegeben.
  3. Wenn der Verwandte existiert, er aber keinen öffentlichen Stammbaum hat (< 35) und der Benutzer nicht auf der Vertrauensliste des Verwandten steht, wird eine null/ein leerer Wert für den Verwandten zurückgegeben.

Wenn Du "Felder" leer lässt, enthalten die zurückgegebenen Daten nicht die Verwandten.

Wenn Du "*" für den Parameter-"Felder" verwendest, dann werden alle verfügbaren Daten zurückgegeben (d.h. alle oben aufgeführten Felder, einschließlich der Profildaten für die Verwandten).

getBio

Die Funktion getBio ruft den Biografietext für ein einzelnes Personenprofil ab.

key : Dies ist entweder die Person.Name (WikiTree-ID) oder die ganzzahlige Profil-Personen-ID (Id).

Die zurückgegebenen Felder sind:

page_name (WikiTree-ID), user_id, bio

getWatchlist

Die Funktion getWatchlist gibt Profile auf der Beobachtungsliste des angemeldeten Benutzers zurück und erfordert daher die vorherige Anmeldung des Benutzers. Die zurückgegebene Liste der Profile enthält Felder, die mit denen von getProfile übereinstimmen.

getPerson' : Wenn Du (1) setzt, dann werden Personenprofile, die auf der Beobachtungsliste stehen, zurückgegeben. Wenn Null angegeben wird, werden Personenprofile ausgeschlossen. Die Standardeinstellung (wenn Du den Parameter nicht übermittelst) ist das Einbeziehen von Personenprofilen.

getSpace' : Wenn Du (1) setzt, dann werden Space-Profile, die auf der Beobachtungsliste stehen, zurückgegeben. Wenn Null angegeben wird, dann werden Space-Profile ausgeschlossen. Die Standardeinstellung (wenn Du den Parameter nicht übermittelst) ist das Einbeziehen von Space-Profilen.

onlyLiving : Wenn Du (1) setzt, dann werden nur Personenprofile von lebenden Menschen (diejenigen mit IsLiving = true) zurückgegeben.

excludeLiving : Wenn Du (1) setzt, dann werden Personenprofile, bei denen IsLiving = true ist, von den Ergebnissen ausgeschlossen.

fields : Die spezifischen Felder, die zurückgegeben werden sollen (siehe getPerson).

limit : Beschränkt die Anzahl der zurückgegebenen Profile; der Standardwert ist 100.

offset : Verschiebung zum ersten zurückgegebenen Datensatz; der Standard ist 0.

order : Sortierreihenfolge für die Profile auf der Beobachtungsliste. Der Wert kann user_id, user_name, user_last_name_current, user_birth_date, user_death_date oder page_touched sein. Die Standard-Sortierreihenfolge erfolgt nach user_id (Person.Id).

getAncestors

key : Die WikiTree-ID oder Person.Id des Profils, für das Vorfahren zurückgegeben werden sollen.

depth : Wie viele Generationen abgerufen werden sollen. Der Standardwert ist 5, gültige Werte sind 1-10.

fields : Welche Felder zurückgegeben werden sollen.


getDescendants

key : Die WikiTree-ID oder Person.Id des Profils, für die Nachkommen zurückgegeben werden sollen.

depth : Wie viele Generationen vorwärts abgerufen werden sollen. Der Standardwert ist 2. Gültige Werte sind 1-5.

fields : Welche Felder zurückgegeben werden sollen.

getRelatives

keys : Eine durch Komma getrennte Liste von WikiTree-ID- oder Person.Id-Werten für die Profile, für die Verwandte zurückgegeben werden sollen.

getParents : Wenn wahr, werden für jedes Personenprofil die Eltern zurückgegeben.

getChildren : Wenn wahr, werden für jedes Personenprofil die Kinder zurückgegeben.

getSpouses : Wenn wahr, werden für jedes Personenprofil die Ehepartner zurückgegeben.

getSiblings : Wenn wahr, werden für jedes Personenprofil die Geschwister zurückgegeben.

getDNATestsByTestTaker

Die Funktion getDNATestsByTestTaker gibt die Liste der von einem bestimmten Profil durchgeführten DNA-Tests zurück.

key : Dies ist entweder die Person.Name (WikiTree-ID) oder die ganzzahlige Profil-Personen-ID (Id).

getConnectedProfilesByDNATest

Die Funktion getConnectedProfilesByDNATest gibt eine Liste von Profilen zurück, die mit einem bestimmten Test verbunden sind.

key : Dies ist entweder die WikiTree-ID oder die ganzzahlige Profil-Personen-ID (Id) des DNA-Testers.

dna_id : Dies ist eine ganze Zahl, die einen bestimmten DNA-Testtyp angibt. Die Optionen sind:

123andMe
2AncestryDNA
3AncestryDNA Paternal Lineage
4AncestryDNA Maternal Lineage
6Family Tree DNA Family Finder
7Family Tree DNA mtDNA
8Family Tree DNA yDNA
9Other auDNA
10Other mtDNA
11Other yDNA
12MyHeritage DNA
13Living DNA

getConnectedDNATestsByProfile

Die Funktion getConnectedDNATestsByProfile gibt die Liste der Tests zurück, die unter dem Abschnitt "DNA Tested" (DNA getestet) auf einem Profil erscheinen.

key : Dies ist entweder die WikiTree-ID oder die ganzzahlige Profil-ID (Id) des Profils.

searchPerson

Diese entsprechen meist den Feldern unter Personensuche.

FirstName : Vorname

LastName : Nachname

BirthDate : Geburtsdatum (JJJJ-MM-TT)

DeathDate : Sterbedatum (JJJJ-MM-TT)

RealName : Bevorzugter Name

LastNameCurrent : Aktueller Nachname

BirthLocation : Geburtsort Schlüsselwort(-wörter)

DeathLocation : Sterbeort Schlüsselwort(-wörter)

Gender : Geschlecht (männlich, weiblich)


fatherFirstName : Vorname des Vaters

fatherLastName : Nachname des Vaters

motherFirstName : Vorname der Mutter

motherLastName : Nachname der Mutter


watchList : Profile im Zusammenhang mit der Beobachtungsliste des Antragstellers (rein, raus, alle)

dateInclude : Falls (both) gesetzt ist, dann sind Daten für Übereinstimmungen erforderlich. Wenn (neither) gesetzt ist, dann werden Übereinstimmungen ohne Daten berücksichtigt.

dateSpread : Jahresspanne für die Übereinstimmungen (1 - 20)

centuryTypo : Wenn (1) gesetzt ist, dann sind mögliche Jahrhundert-Tippfehler bei den Daten in den Ergebnissen enthalten.

isLiving : Wenn (1) gesetzt ist, dann sind die Übereinstimmungen auf die Profile lebender Personen beschränkt.

skipVariants : Wenn (1) gesetzt ist, dann werden Nachnamensvarianten nicht berücksichtigt und es werden nur exakte Nachnamens-Übereinstimmungen zurückgegeben.

lastNameMatch : Optionen zum Abgleich des Nachnamens (alle, aktuell, Geburt, genau).


sort : Sortierreihenfolge (erste, letzte, Geburt, Tod, Manager)

secondarySort : Sekundäre Sortierreihenfolge (erste, letzte, Geburt, Tod, Manager)

limit : Anzahl der zurückzugebenden Ergebnisse (1 - 100, Voreinstellung 10)

start : Anfangsverschiebung der Ergebnisse (Standard 0)

fields : Eine durch Komma getrennte Liste der abzurufenden Profildatenfelder. Siehe getProfile.

Beispiele & Hilfsmittel

Eine einfache Demonstration der API-Funktionen ist verfügbar unter: https://apps.wikitree.com/apps/api_demo.php

Ein JavaScript-SDK mit einigen Hilfsfunktionen für die Arbeit mit den API-Aufrufen ist verfügbar unter: https://github.com/wikitree/wikitree-javascript-sdk. Dies wird in der obigen API-Demo demonstriert, die das SDK verwendet.

Bei Fragen zu den neuesten verfügbaren Aktionen und der entsprechenden Syntax wende Dich bitte per E-Mail an <WikiTreeApps@googlegroups.com>

Siehe auch:



This page was last modified 15:09, 30 March 2022. This page has been accessed 338 times.