pywikitree

KO | EN

gitlite — search

#python #react #typescript #golang #android #rust #java #windows #awesome #cli #vue #security #ios #mcp

(★ 11)

Python interface to the WikiTree API

pywikitree Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

There have been a number of breaking changes in the WikiTree API, which has broken this package.

This package is a Python interface to the WikiTree Apps API

Currently, documentation is contained in docstrings in the source.
Documentation for the WikiTree API is found at the
http://apps.wikitree.com/apps/
page
which references the more detailed
http://www.wikitree.com/wiki/API_Documentation
page.

The following console session illustrates retrieving a public person
without logging on to WikiTree, and using Python 3.
When using Python 2, all returned strings are unicode.

Using python 3, get setup to use the API

>>> import wt_apps, pprint, os
    >>> pp = pprint.PrettyPrinter(indent=2, width=120, depth=4)
    >>> apps = wt_apps.WT_Apps()
    >>> try:
    ...     from secrets import *
    ... except ImportError:
    ...     WT_USER = None
    ...     WT_PASS = None
    ...

We are not yet logged in, so we will only see public data.

Retrieve a well known person.

>>> r = apps.getPerson("Churchill-4", "*")
    >>> j = r.json()
    >>> pp.pprint(j)
    [ { 'person': { 'BirthDate': '1874-11-30',
                    'BirthDateDecade': '1870s',
                    'BirthLocation': 'Blenheim, Oxfordshire, England',
                    'BirthNamePrivate': 'Winston Churchill KG OM CH',
                    'Children': {'5596': {...}, '5597': {...}, '5598': {...}, '5599': {...}, '5600': {...}},
                    'DeathDate': '1965-01-24',
                    'DeathDateDecade': '1960s',
                    'DeathLocation': 'Bladon, Oxfordshire, England',
                    'Father': 5584,
                    'FirstName': 'Winston',
                    'Gender': 'Male',
                    'Id': 5589,
                    'IsLiving': 0,
                    'LastNameAtBirth': 'Churchill',
                    'LastNameCurrent': 'Churchill',
                    'LastNameOther': '',
                    'LongNamePrivate': 'Winston L. Churchill KG OM CH',
                    'Manager': 4677796,
                    'MiddleName': 'Leonard Spencer',
                    'Mother': 5554,
                    'Name': 'Churchill-4',
                    'Nicknames': '',
                    'Parents': {'5554': {...}, '5584': {...}},
                    'Photo': 'Winston churchill.jpg',
                    'PhotoData': None,
                    'Prefix': 'Sir',
                    'Privacy': 60,
                    'Privacy_IsAtLeastPublic': True,
                    'Privacy_IsOpen': True,
                    'Privacy_IsPrivate': False,
                    'Privacy_IsPublic': False,
                    'Privacy_IsSemiPrivate': False,
                    'Privacy_IsSemiPrivateBio': False,
                    'RealName': 'Winston',
                    'ShortName': 'Winston Churchill KG OM CH',
                    'Siblings': {'5592': {...}},
                    'Spouses': {'5595': {...}},
                    'Suffix': 'KG OM CH'},
        'status': 0,
        'user_name': 'Churchill-4'}]
    >>>

Grab the privacy name/number translation data.

>>> r = apps.getPrivacyLevels()
    >>> j = r.json()
    >>> pp.pprint(j)
    [ { 'OPEN': 60,
        'PRIVATE': 20,
        'PUBLIC': 50,
        'SEMIPRIVATE_BIO': 30,
        'SEMIPRIVATE_BIOTREE': 40,
        'SEMIPRIVATE_TREE': 35,
        'UNLISTED': 10}]
    >>>

Download the biography, and display the first two lines

>>> r = apps.getBio("Churchill-4")
    >>> j = r.json()
    >>> bio = j[0]["bio"]
    >>> j[0]["bio"] = "See below\nfor a few lines\nfrom the bio.\n"
    >>> pp.pprint(j)
    [{'bio': 'See below\nfor a few lines\nfrom the bio.\n', 'page_name': 'Churchill-4', 'status': 0, 'user_id': 5589}]
    >>>
    >>> print("\n".join([x.strip("\n") for x in bio.split("\n")][:2]))
    [[Category:This Day In History April 24]]
    [[Category: This Day In History November 30]] [[Category: This Day In History January 24]] [[Category: British Prime Ministers]] [[Category: World War II Political Leaders]][[Category: Historians]] [[Category: Famous Politicians of the 20th Century]] [[Category: Knights Companion of the Garter]] {{Notables}}

>>>

Get ancestors, depth=1 gives person and parents, depth=2 adds grandparents, etc.

>>> r = apps.getAncestors("Churchill-4", depth=1)
    >>> j = r.json()
    >>> for p in j[0]['ancestors']: del p['Touched'] # changes on read!
    >>> pp.pprint(j)
    [ { 'ancestors': [ { 'BirthDate': '1874-11-30',
                         'BirthDateDecade': '1870s',
                         'BirthLocation': 'Blenheim, Oxfordshire, England',
                         'BirthNamePrivate': 'Winston Churchill KG OM CH',
                         'DeathDate': '1965-01-24',
                         'DeathDateDecade': '1960s',
                         'DeathLocation': 'Bladon, Oxfordshire, England',
                         'Father': 5584,
                         'FirstName': 'Winston',
                         'Gender': 'Male',
                         'Id': 5589,
                         'IsLiving': 0,
                         'IsPerson': 1,
                         'LastNameAtBirth': 'Churchill',
                         'LastNameCurrent': 'Churchill',
                         'LastNameOther': '',
                         'LongNamePrivate': 'Winston L. Churchill KG OM CH',
                         'Manager': 4677796,
                         'MiddleName': 'Leonard Spencer',
                         'Mother': 5554,
                         'Name': 'Churchill-4',
                         'Nicknames': '',
                         'Photo': 'Winston churchill.jpg',
                         'PhotoData': None,
                         'Prefix': 'Sir',
                         'Privacy': 60,
                         'Privacy_IsAtLeastPublic': True,
                         'Privacy_IsOpen': True,
                         'Privacy_IsPrivate': False,
                         'Privacy_IsPublic': False,
                         'Privacy_IsSemiPrivate': False,
                         'Privacy_IsSemiPrivateBio': False,
                         'RealName': 'Winston',
                         'ShortName': 'Winston Churchill KG OM CH',
                         'Suffix': 'KG OM CH'},
                       { 'BirthDate': '1849-02-13',
                         'BirthDateDecade': '1840s',
                         'BirthLocation': None,
                         'BirthNamePrivate': 'Randolph Spencer-Churchill',
                         'DeathDate': '1895-01-24',
                         'DeathDateDecade': '1890s',
                         'DeathLocation': None,
                         'Father': 5586,
                         'FirstName': 'Randolph',
                         'Gender': 'Male',
                         'Id': 5584,
                         'IsLiving': None,
                         'IsPerson': 1,
                         'LastNameAtBirth': 'Spencer-Churchill',
                         'LastNameCurrent': 'Spencer-Churchill',
                         'LastNameOther': None,
                         'LongNamePrivate': 'Randolph H. Spencer-Churchill',
                         'Manager': 5932170,
                         'MiddleName': 'Henry',
                         'Mother': 5587,
                         'Name': 'Spencer-Churchill-1',
                         'Nicknames': None,
                         'Photo': 'Lord Randolph Churchill.jpg',
                         'PhotoData': None,
                         'Prefix': None,
                         'Privacy': 60,
                         'Privacy_IsAtLeastPublic': True,
                         'Privacy_IsOpen': True,
                         'Privacy_IsPrivate': False,
                         'Privacy_IsPublic': False,
                         'Privacy_IsSemiPrivate': False,
                         'Privacy_IsSemiPrivateBio': False,
                         'RealName': 'Randolph',
                         'ShortName': 'Randolph Spencer-Churchill',
                         'Suffix': ''},
                       { 'BirthDate': '1854-01-09',
                         'BirthDateDecade': '1850s',
                         'BirthLocation': None,
                         'BirthNamePrivate': 'Jennie Jerome CI',
                         'DeathDate': '1921-06-09',
                         'DeathDateDecade': '1920s',
                         'DeathLocation': None,
                         'Father': 5555,
                         'FirstName': 'Jeanette',
                         'Gender': 'Female',
                         'Id': 5554,
                         'IsLiving': None,
                         'IsPerson': 1,
                         'LastNameAtBirth': 'Jerome',
                         'LastNameCurrent': 'Churchill',
                         'LastNameOther': None,
                         'LongNamePrivate': 'Jennie (Jerome) Churchill CI',
                         'Manager': 4840833,
                         'MiddleName': '',
                         'Mother': 5575,
                         'Name': 'Jerome-1',
                         'Nicknames': None,
                         'Photo': 'Lady_Randolph.jpg',
                         'PhotoData': None,
                         'Prefix': None,
                         'Privacy': 60,
                         'Privacy_IsAtLeastPublic': True,
                         'Privacy_IsOpen': True,
                         'Privacy_IsPrivate': False,
                         'Privacy_IsPublic': False,
                         'Privacy_IsSemiPrivate': False,
                         'Privacy_IsSemiPrivateBio': False,
                         'RealName': 'Jennie',
                         'ShortName': 'Jennie (Jerome) Churchill CI',
                         'Suffix': 'CI'}],
        'status': 0,
        'user_name': 'Churchill-4'}]
    >>>

Get relatives, just the spouses and siblings in this case.

>>> pp = pprint.PrettyPrinter(indent=2, width=120, depth=5)
    >>> r = apps.getRelatives("Churchill-4", getSpouses=1, getSiblings=1)
    >>> j = r.json()
    >>> # for p in j[0]['items']: del p['Touched'] # changes on read!
    >>> pp.pprint(j)
    [ { 'items': [ { 'key': 'Churchill-4',
                     'person': { 'BirthDate': '1874-11-30',
                                 'BirthDateDecade': '1870s',
                                 'BirthLocation': 'Blenheim, Oxfordshire, England',
                                 'BirthNamePrivate': 'Winston Churchill KG OM CH',
                                 'DeathDate': '1965-01-24',
                                 'DeathDateDecade': '1960s',
                                 'DeathLocation': 'Bladon, Oxfordshire, England',
                                 'Father': 5584,
                                 'FirstName': 'Winston',
                                 'Gender': 'Male',
                                 'Id': 5589,
                                 'IsLiving': 0,
                                 'IsPerson': 1,
                                 'LastNameAtBirth': 'Churchill',
                                 'LastNameCurrent': 'Churchill',
                                 'LastNameOther': '',
                                 'LongNamePrivate': 'Winston L. Churchill KG OM CH',
                                 'Manager': 4677796,
                                 'MiddleName': 'Leonard Spencer',
                                 'Mother': 5554,
                                 'Name': 'Churchill-4',
                                 'Nicknames': '',
                                 'Photo': 'Winston churchill.jpg',
                                 'PhotoData': None,
                                 'Prefix': 'Sir',
                                 'Privacy': 60,
                                 'Privacy_IsAtLeastPublic': True,
                                 'Privacy_IsOpen': True,
                                 'Privacy_IsPrivate': False,
                                 'Privacy_IsPublic': False,
                                 'Privacy_IsSemiPrivate': False,
                                 'Privacy_IsSemiPrivateBio': False,
                                 'RealName': 'Winston',
                                 'ShortName': 'Winston Churchill KG OM CH',
                                 'Siblings': {...},
                                 'Spouses': {...},
                                 'Suffix': 'KG OM CH',
                                 'Touched': '20170211033528'},
                     'user_id': 5589,
                     'user_name': 'Churchill-4'}],
        'status': 0}]
    >>>

Try to retrieve the FamilySearch connections. This will fail because we are not logged in.

>>> r = apps.getPersonFSConnections("Churchill-4")
    >>> j = r.json()
    >>> pp.pprint(j)
    [{'status': 'Permission denied', 'user_name': 'Churchill-4'}]
    >>>

Illustrate login failure.
Use an invalid password, so as to see the error result.

>>> r = apps.login("MissingSurname-1", "InvalidPassword")
    >>> j = r.json()
    >>> pp.pprint(j)
    {'login': {'result': 'Illegal', 'wait': 1}}
    >>>

Try logging in with user and password from environment.
Provide your own WikiTree.com credentials.
Use "SET WT_USER=your_user_id" or "export WT_USER=your_user_id", etc.
Or create a "secrets.py" file with lines with WT_USER=your_user_id, etc.

>>> wt_user = os.environ.get("WT_USER", WT_USER)
    >>> wt_pass = os.environ.get("WT_PASS", WT_PASS)
    >>> r = apps.login(wt_user, wt_pass)
    >>> j = r.json()
    >>> del j['login']['token']  # hide the token (it won't match)
    >>> del j['login']['userid'] # hide the userid (it won't match)
    >>> del j['login']['username'] # hide the userid (it won't match)
    >>> pp.pprint(j)
    {'login': {'result': 'Success'}}
    >>>

Try to retrieve the FamilySearch connections while logged in.

>>> r = apps.getPersonFSConnections("Churchill-4")
    >>> j = r.json()
    >>> pp.pprint(j)
    [{'status': 'Permission denied', 'user_name': 'Churchill-4'}]
    >>>

Illustrate logging off.

>>> apps.logout()
    >>>

Our session is ended.

pywikitree

pywikitree Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

pywikitree

pywikitree Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README