Help:API Documentation

Search WikiTree's help pages:

Categories: WikiTree Help | WikiTree Apps Project

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! -- Chris Whitten

Contents

How to Access the WikiTree API

The WikiTree API can be accessed via HTTP calls to port 80. Calls should be made to https://apps.wikitree.com/api.php

This isn't a full-featured public API. The API is read-only and only supports these functions:

  • login : 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.
  • getRelatives: Retrieve family members in all directions, not just ancestors.
  • getPrivacyLevels: Returns a summary of the privacy level codes.

Access to the api.php interface is open from any source. However, if you want to call the API from Javascript in a web page, that page needs to be hosted on apps.wikitree.com due to cross-domain scripting security in browsers.

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.

Libraries are under development to demonstrate API usage in both Python and Javascript.

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.

Security

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.

Parameters

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").
  • format : The format of the returned data. This is either "json", for JSON (JavaScript Object Notation) or "xml" for XML (Extensible Markup Language). The default is for data to be returned in JSON.

In addition to "action" and "format", several of the API functions accept other parameters.

login

email : The email address of the WikiTree account you're signing in with.

password : Your password.

getProfile

The getProfile function works for person profiles and free-space profiles.

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
Manager

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.

Note that not all fields are available for all profiles. Access depends on the privacy setting and whether the logged-in user is on the profile's Trusted List.

The behavior regarding missing and private family members for all API functions is as follows:

  1. 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.
  2. If the starting profile has a public family tree (level >= 35) but a relative is missing, return a zero value ("0").
  3. 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).

getBio

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

getWatchlist

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).

getAncestors

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.

getRelatives

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.

Examples & Resources

A skeleton demonstration of the API functions is available at: https://apps.wikitree.com/apps/api_demo.php

A JavaScript SDK with some utility functions for working with the API calls is available at: https://github.com/wikitree/wikitree-javascript-sdk. This is demonstrated at https://apps.wikitree.com/apps/casey1/wikitree-javascript-sdk.

For questions about the latest available actions and their corresponding syntax, please e-mail <WikiTreeApps@googlegroups.com>

Language: en | nl


This page was last modified 05:29, 4 March 2018. This page has been accessed 3,644 times.