Ancestry exposes an undocumented REST API for its DNA features. This Python wrapper inventories the available calls, and exposes it to novice developers or power users in a more intuitive manner. I have consciously tried to keep the method names and parameters self-explanatory, but included the documentation below if additional context is needed.
Many DNA function calls require you to obtain and input GUIDs corresponding to tests and cousin matches. Later revisions of this wrapper might simplify this process, translating human-readable values to their GUIDs.
This wrapper assumes intermediate knowledge of Python -- for example, being able to read the ancestryDnaWrapper
class definition, and knowing to input the username and password values to authenticate successfully.
This wrapper pulls browser cookies for authentication using browser_cookie3. It defaults to Google Chrome (Ctrl-F "chrome" in core.py
), but should be changed to a browser you rarely use. The browser selected needs to be closed, so this program can access its cookies. Most (all?) browsers create a file lock on cookies while running.
Login to Ancestry on that browser of choice, and this wrapper will inherit the authentication cookie. This is a one-time requirement. However, if you encounter issues, ensure the browser is still logged in. Although Ancestry has authentication endpoints (ancestry.com/account/signin/api/pre-authenticate
and ancestry.com/account/signin/api/authenticate
), I could not get it functional here.
It will authenticate the US-based endpoint by default. This can be overrided with the endpoint
keyword argument.
Any of the group, star, and test require a test to be selected. The wrapper will not default to anything.
get_tests
-- will enumerate all completed tests registered to the account. By default, this will not include any tests shipped, or awaiting processing. To see other tests, change thetest_type
parameter (default value iscomplete
).use_test
-- every object returned fromget_tests
will include aguid
property. That property must be inputted to use any latter options. Like the Ancestry UI, you cannot select more than one test.
get_dna_matches
-- This will return all DNA matches. Every DNA match will contain atestGuid
attribute. The method also contains ashared_match_test_id
attribute. To obtain shared matches, inputtestGuid
there.get_admixture
-- This will return your admixture (e.g. 100% Martian). The method also contains ashared_match_test_id
attribute. To compare admixture with another user, input theirtestGuid
there.
get_custom_groups
-- This will return all custom groups you created. If you do not have any, it will return an empty array. Each object will containtagId
attribute -- required in anydelete
ormodify
operations.create_custom_group
-- This creates a custom group for you to categorize your matches. Include a name and color value (e.g.#FFFFFF
). The response object will include atagId
attribute, needed for addition/deletion operations.delete_custom_group
-- deletes group corresponding to thetagId
. If creating, and then immediately deleting groups, you may encounter eventual consistency issues. Ensure you wait ~ 30 seconds before attempting operations.modify_group_membership
-- add or remove DNA matches to a custom group. Obtain thetestGuid
fromget_dna_matches
and thetagId
fromcreate/get_custom_group
. Action will beadd
orremove
.
modify_star
-- enables you to favorite a match by starring it. Obtain thetestGuid
fromget_dna_matches
. Action will beadd
orremove
.