There is a basic API available for any WikiTree member who wishes to contribute to the community via their coding skills. It supports queries for various data elements contained in WikiTree profiles.
If you have any questions, please add yourself to the WikiTree Apps Google Group and ask there. Thanks!
How to Access the WikiTree API
The WikiTree API can be accessed via HTTP calls to port 80. Calls should be made to https://api.wikitree.com/api.php
This isn't a full-featured public API. The API is read-only. It supports these functions:
- authentication : Authenticate to a particular user account.
- getProfile : The getProfile function returns a default set of fields for a given key (WikiTree ID or page ID number). This default set includes the various name fields, birth/death dates, gender, and the mother and father ID values. In addition to these defaults, there are optional fields that you can request using the "fields" parameter. These additional fields include: Parents, Children, Siblings, and Spouses. If you request these fields, then the return JSON includes person profile data for the relevant people.
- getPerson : The getPerson function has been largely deprecated in favor of the more flexible getProfile. However, it still functions, and may be useful if your application needs to request a profile using a user ID number, rather than the page ID number that getProfile uses (e.g. to use a Mother/Father ID and get that parent's profile data). It accepts a "fields" parameter and returns data exactly as getProfile. The only difference is the acceptance of a user ID for the key.
- getAncestors : Retrieve ancestors for a given person.
- getRelatives: Retrieve family members in all directions, not just ancestors.
- getPrivacyLevels: Returns a summary of the privacy level codes.
- getDNATestsByTestTaker : Returns the list of DNA tests taken by a particular profile.
- getConnectedProfilesByDNATest : Returns a list of profiles connected to a specific test.
- getConnectedDNATestsByProfile : Returns the list of tests that appear under the "DNA Tested" section on a profile.
- searchPerson : Returns a list of person profiles that match given criteria.
To have a directory on the apps server created for you - whether you want to upload a real application or just experiment - join the WikiTree Apps Project.
If you don't know where to begin, don't worry. E-mail <WikiTreeApps@googlegroups.com> and the community will help you.
Data on Apps Server
The API calls data from WikiTree's apps server. This ensures that apps can't interfere with the normal operation of WikiTree.
The Apps data should be essentially concurrent with the live data. It uses a read-only replicating copy of the primary WikiTree database. There are times when heavy changes are made to the live server that the Apps copy falls behind for a short time (it's a less capable machine), but it is usually within seconds or less of being fully up-to-date with the live data.
The WikiTree API extends the existing Trusted List security model of the WikiTree web site. Information returned by the API will be limited to only what is available to the currently logged-in user.
Any WikiTree member can login to an app running on apps.wikitree.com unless you hide your application.
The WikiTree API requires certain parameters in order to return desired results. Two parameters are common to all of the functions. These are:
- action : The action/function to execute (e.g. "getProfile").
In addition to "action" and "format", several of the API functions accept other parameters.
Many operations with the API can be used without any authentication. Public profiles can be retrieved just by using the getProfile action. However, in order to retrieve data for private profiles, the user will need to authenticate into a user account that is on the Trusted List for those profiles.
Authentication is a multi-step process. The user goes to api.wikitree.com where they login with their WikiTree credentials. Upon login, the user receives a session cookie for future requests to the API and is then sent back to the application with a token. The application can then validate the token with the API and store the user's ID. In a bit more detail...
The first step is to send the user to authenticate. This lets them login at WikiTree without providing credentials to a third-party application. You should not ask users directly for their login information.
https://api.wikitree.com/api.php?action=clientLogin&returnURL=[encoded URL of application]
The API will return the user to returnURL with an "authcode" parameter. The application should then post to the API URL with action equal to "clientLogin" and authcode equal to the value received. The returned data will include "result = Success" when the authorization code is confirmed. You can then note in your application that the user is signed in. The clientLogin result also includes the user's user_id and user_name (i.e. WikiTree ID) which the application can store for future use.
The clientLogin process is demonstrated in detail at the API Demo page.
key : This is either the Person.Name (WikiTree ID, e.g. "Adams-35"), the space page_name (e.g. "Space:Allied_POW_camps"), or the integer profile PageId.
fields : This parameter describes which fields from the person profile you want the API to return. Available fields include:
- Id, Name, FirstName, MiddleName, MiddleInitial, LastNameAtBirth, LastNameCurrent, Nicknames, LastNameOther, RealName, Prefix, Suffix
- Gender, BirthDate, DeathDate, BirthLocation, DeathLocation, BirthDateDecade, DeathDateDecade, Photo
- Mother, Father, Parents, Children, Siblings, Spouses
- HasChildren, NoChildren, Touched, IsLiving, Privacy, DataStatus
- Derived.ShortName, Derived.BirthNamePrivate, Derived.LongNamePrivate, Derived.LongName, Derived.BirthName
The BirthDate and DeathDate are YYYY-MM-DD, and may have zeroes for the year or month if the date is incomplete. The BirthDateDecade and DeathDateDecade fields are strings like "1960's".
The Mother and Father fields are the Id values for the requested profile's parents. Those can be used to retrieve more profile data with, e.g., another call to getPerson. If the fields value includes "Parents", then the profile data for the mother and father is returned along with the original profile. Similarly, you can request a profile's Children, Siblings, and Spouses. The fields returned for these extra relatives' profiles are the same as the fields returned for the requested profile.
The HasChildren field means the profile has children. The NoChildren field is the "no more children" checkbox on the edit page.
DataStatus includes the data qualifiers for the following fields: FirstName, LastNameCurrent, RealName, BirthDate, DeathDate, BirthLocation, DeathLocation, Father, Mother, Spouse, MiddleName, LastNameAtBirth, ColloquialName, Nicknames, Gender, Prefix, Suffix, LastNameOther. Father and Mother will have a numerical code: 30 = confirmed with DNA, 20 = confident, 10 = uncertain, 5 = non-biological.
The behavior regarding missing and private family members for all API functions is as follows:
- If the starting profile doesn't have a public family tree (privacy level < 35) and the user is not on the Trusted List, exclude the fields/objects for relatives entirely.
- If the starting profile has a public family tree (level >= 35) but a relative is missing, return a zero value ("0").
- If the relative exists but the relative does not have a public family tree (< 35) and the user is not on the relative's Trusted List, return a null/empty value for the relative.
If you leave "fields" blank, the data returned does not include the relatives.
If you use "*" for the "fields" parameter, then all available data is returned (i.e. all of the fields listed above, including the profile data for the relatives).
The getBio function retrieves the biography text for a single person profile.
key : This is either the Person.Name (WikiTree ID) or the integer profile person ID (Id).
The fields returned are:
- page_name (WikiTree ID), user_id, bio
The getWatchlist function returns profiles on the logged-in user's Watchlist, and thus requires the user first login. The returned list of profiles includes fields matching those from getProfile.
getPerson : If set (1), then Person profiles on the Watchlist are returned. If passed as zero, then Person profiles are excluded. The default (if you don't pass the parameter at all) is to include Person profiles.
getSpace : If set (1), then Space profiles on the Watchlist are returned. If passed as zero, then Space profiles are excluded. The default (if you don't pass the parameter at all) is to include Space profiles.
onlyLiving : If set (1), then only Person profiles of Living People (those with IsLiving = true) are returned.
excludeLiving : If set (1), then Person profiles where IsLiving = true are excluded from the results.
fields : The specific fields to return (see getPerson).
limit : Limit to the number of profiles returned; the default is 100.
offset : Offset to the first record returned; the default is 0.
order : Sort order for the profiles on the Watchlist. Value can be user_id, user_name, user_last_name_current, user_birth_date, user_death_date, or page_touched. The default sort order is by user_id (Person.Id).
key : The WikiTree ID or Person.Id of the profile to return ancestors for.
depth : How many generations back to retrieve. The default is 5. Valid values are 1-10.
fields : Which fields to return.
key : The WikiTree ID or Person.Id of the profile to return descendants for.
depth : How many generations forward to retrieve. The default is 2. Valid values are 1-5.
fields : Which fields to return.
keys : A comma-separated list of WikiTree ID or Person.Id values for the profiles to return relatives for.
getParents : If true, returns Parents for each person profile.
getChildren : If true, returns Children for each person profile.
getSpouses : If true, returns Spouses for each person profile.
getSiblings : If true, returns Siblings for each person profile.
The getDNATestsByTestTaker function returns the list of DNA tests taken by a particular profile.
key : This is either the Person.Name (WikiTree ID) or the integer profile person ID (Id).
The getConnectedProfilesByDNATest function returns a list of profiles connected to a specific test.
key : This is either the WikiTree-ID or the integer profile ID (Id) of the test-taker.
dna_id : This is an integer that specifies a particular DNA test type. The options are:
1 23andMe 2 AncestryDNA 3 AncestryDNA Paternal Lineage 4 AncestryDNA Maternal Lineage 6 Family Tree DNA Family Finder 7 Family Tree DNA mtDNA 8 Family Tree DNA yDNA 9 Other auDNA 10 Other mtDNA 11 Other yDNA 12 MyHeritage DNA 13 Living DNA
The getConnectedDNATestsByProfile function returns the list of tests that appear under the "DNA Tested" section on a profile.
key : This is either the WikiTree-ID or the integer profile ID (Id) of the profile.
These mostly correspond to the fields at Special:SearchPerson.
FirstName : First name
LastName : Last name
BirthDate : Birth date (YYYY-MM-DD)
DeathDate : Death date (YYYY-MM-DD)
RealName : Preferred name
LastNameCurrent : Current last name
BirthLocation : Birth location keyword(s)
DeathLocation : Death location keyword(s)
Gender : Gender (male, female)
fatherFirstName : Father's first name
fatherLastName : Father's last name
motherFirstName : Mother's first name
motherLastName : Mother's last name
watchList : Profiles in relation to the requester's watchlist (in, out, any)
dateInclude : If set (both), then dates on matches are required. If set (neither), then matches without dates are included.
dateSpread : Year range for matching (1 - 20)
centuryTypo : If set (1), then possible century typos in the dates are included in the results.
isLiving : If set (1), then matches are restricted to the profiles of living people.
skipVariants : If set (1), then last name variants are not considered and only exact last name matches will be returned.
lastNameMatch : Last name match options (all, current, birth, strict)
sort : Sort order (first, last, birth, death, manager)
secondarySort : Secondary sort order (first, last, birth, death, manager)
limit : Number of results to return (1 - 100, default 10)
start : Starting offset of results (default 0)
fields : A comma-delimited list of profile data fields to retrieve. See getProfile.
Examples & Resources
A skeleton demonstration of the API functions is available at: https://apps.wikitree.com/apps/api_demo.php
For questions about the latest available actions and their corresponding syntax, please e-mail <WikiTreeApps@googlegroups.com>
This page was last modified 16:42, 18 January 2021. This page has been accessed 12,524 times.