Modern Software Experience

2011-08-15

Family Graph API

  2. Getting Started with the MyHeritage Family Graph API
MyHeritage has a public API now. It is called the Family Graph API.

Yet Another Genealogy API

genealogy APIs

The past few years several companies have introduced genealogy APIs. Genealogy APIs offers a quick overview. FamilySearch has an API for New FamilySearch (NFS), Geni has the Geni API. There obviously is some interface between Family Tree Maker and Ancestry.com and the Family Tree Maker SearchService I recently discovered isn't the complete story. Ancestry.com has some API for their iPad application, and it remains undocumented.
There obviously is some undocumented interface between MyHeritage Family Tree Builder and MyHeritage as well. Presumably, their FamilyConnect app for Android and iOS uses that same interface.

Family Graph home page

MyHeritage API

MyHeritage has a public API now. It is called the Family Graph API. Geni has the Geni API, MyHeritage has the Family Graph API. The Geni API and Family Graph API are different, but do share some technical similarities. Both are RESTfull API; both are based on a REST architecture, and both return results in JSON format. Well, the Geni API can return results in either JSON or XML format.
The practical upshot of the Family Graph API being a RESTfull API is that you can - just as with the Geni API - experiment with it from the address bar of your browser.

Family Graph API

Those architectural choices are fairly modern choices, as you would expect for a new API, but not for one that has been in use for years already. It therefore seems that the Family Graph API is a brand new API, and not what Family Tree Builder and FamilyConnect are using. It stands to reason though, that future versions of Family Tree Builder and FamilyConnect will use the Family Graph in favour of any older, private interfaces they may still be using today.

The Family Graph name seems an attempt to associate MyHeritage with the success of FaceBook and its Social Graph API. Sure enough, the home page states that The Family Graph API is for families what Facebook’s Social Graph API is for friends and LinkedIn’s API is for business..

You might expect MyHeritage to document their API on their MyHeritage site. They'll probably put a link up soon, but they opted to document the API on its own domain. That is probably a SEO decision; giving the API its own site keeps that site focused on nothing but the API. Although the site is brand new, it is already one of the top search results for MyHeritage API.

Family Graph site

MyHeritage leaves no doubt that the Family Graph site is part of MyHeritage; the Family Graph site has the same look and feel as the MyHeritage site. The site has four tabs: Overview, Documentation, Sample applications, and Get access.

When you browse to the site, you land on the overview tab. MyHeritage isn't famed for its modesty. Despite the fact that MyHeritage has not even announced the Family Graph API on their own blog, the Family Graph Overview page already describes the Family Graph by MyHeritage.com as the primary API on the web for family connections.

The Documentation tab provides the actual API documentation. The Sample applications page provides several sample applications.

The Get access is a request form for an application key.; using the API is free, but you need an so-called application key to use, so that MyHeritage knows which applications are using the service. When you request an application key, you agree to the terms of service for the Family Graph API, which includes the terms of service for MyHeritage.com itself.

Family Graph documentation

first version: read-only

When Geni introduced the Geni API, the Geni API wasn't done yet. Geni added quite a few interfaces after the initial introduction of the API. The current Family Graph API isn't complete yet either. A quick browse through the current functionality shows that this first version is read-only, download-only.
It is reasonable to expect MyHeritage to update it with the ability to write and upload as well. Only when Family Graph API allows both reading and writing, both downloading and uploading, can it replace the private interface MyHeritage is currently using.

The Family Graph API even includes ExportGEDCOM and SmartMatch functions.

It was the open Geni API that made Real-Time Collaboration decide to start their AncestorSync Beta with Geni.com, despite their extensive experience with the FamilySearch API. The MyHeritage API is just as open as the Geni API; publicly documented, no NDAs and no usage fees. Those choices are consistent with a desire to see broad adoption of the API. To see really broad adoption, the API will have to offer both read and write capability. There is only so much you can do with a read-only API. Perhaps the most relevant case in point is that only when MyHeritage offers both a full access API, will Real-Time Collaboration be able to create AncestorSync for MyHeritage, surely a product MyHeritage would love to see developed.
I have little doubt that the Family Graph API will evolve into a full API that offers both read and write capabilities.

Other than the fact that it is read-only, the Family Graph API seems quite complete. It offers access to members and their family trees, to individuals and events, notes, photos, sources, etcetera. The Family Graph API even includes ExportGEDCOM and SmartMatch functions.

Family Graph Individual

excellent documentation

The Family Graph documentation is excellent. It certainly is much better than the initial Geni API documentation. Sure, the Geni API documentation has improved since then, but the MyHeritage documentation is remarkably polished.

The Family Graph documentation is excellent.

A menu along the left provides an overview of the function in the Family Graph API. You can click on a function name to get information on that function. Each function, or rather object, has its own page. Typically, that page describes the object, enumerates all its fields, its connections to other objects, and rounds it off with some example.
What makes the Family Graph API documentation particularly good is that they use a sample tree through and take advantage of the aforementioned RESTfull-ness; you know the sample code is okay, because you can click the examples to see the results in your browser.

Family Graph Sample Applications

There is example code for each API object helps you understand each individual part of the API. This is completed by a handful of simple sample application that show how they are used together. Again, you know the sample code works, because you cannot only download the example code, but can also click the Run sample link.
The Family Graph API looks fine, and its documentation is excellent.

updates

2011-08-21 Competition tab

The familygraph.com site now has a fifth tab titled Competition. All it says is Coming Soon.... It seems reasonable to assume that they MyHeritage will try to interest third-party developers in their API by offering some awards.

Family Graph home page

2011-08-29 press release

MyHeritage has finally issued a press release announcing the Family Graph API. This press release introduced the Family Graph API logo.

2011-09-01 Competition tab live

The competition page is live. See MyHeritage App Competition.

2011-09-01 MyHeritage blog post

The MyHeritage blog has a new blog post, by Caroline, titled New! MyHeritage Family Graph API and Best Family App Competition, which pretends that MyHeritage is releasing the Family Graph API today.

2011-12-15 MyHeritage 1.0

MyHeritage has introduced the MyHeritage app for both iOS and Android. The MyHeritage 1.0 app is read-only, because the Family Graph API is still read-only.

2013-01-09: Mocavo: MyHeritage 2.0

Version 2.0 of the MyHeritage 2.0 app upgrades it from a genealogy viewer to a genealogy editor. That suggests that the Family Graph API supports editing now, but the Family Graph documentation and SDKs do not reflect this major upgrade yet.

links

genealogy API

MyHeritage

also mentioned

 

Copyright © Tamura Jones. All Rights reserved.