2011-09-07 Getting Started with the MyHeritage Family Graph API

Family Graph API

essential undocumented facts & features

documentation

The MyHeritage Family Graph API article introduced MyHeritage's public API. I noted that the Family Graph API looks fine, and the documentation is excellent. Upon closer examination however, that statement is somewhat misleading. The documentation that is there is fine, the problem is that there should be more.

The Family Graph site has a Documentation tab that offers excellent documentation of the Family Graph API objects. The site has an Sample applications tab that offers five working sample applications, complete with source code, and it has an Overview tab - which does not provide an overview.
The Overview tab does not provide an overview of the Family Graph API, nor does any other tab. The Family Graph site lacks an overview.

The so-called Overview tab is just an Overview title above the site's home page, which is little more than an advertisement for MyHeritage.com, and offers no more information on the Family Graph API than the unsupported claim that it is the primary API on the web for family connections.

Family Graph API home page

The site offers an SDK, but it does not include any documentation either.
There is no introductory documentation, no programming guide, no overview of the class model, no high-level overview of how to use the API, no documentation of typical API usage patterns.
There is no Family Graph API overview or introduction at all. You have to read through the API documentation to extract the big picture from the many details.

This article presents what's missing. This is an unofficial introduction of the Family Graph API.

overview

This article presents what's missing. This is an unofficial introduction of the Family Graph API.
It is based on the official documentation, the samples, the SDK, and a bit of experimenting in the browser. I believe the information provided here to be correct, but the Family Graph API is still in beta, so even correct information may be outdated when you read it…

basic facts

The MyHeritage Family Graph API article revealed some basic facts. MyHeritage.com has a public API, it is called the Family Graph API, and the official documentation is on the separate familygraph.com domain. The MyHeritage Family Graph API has some similarities to the Geni API. The Family Graph API is a RESTfull API; it has a REST architecture, and returns results in JSON format.

read-only

A major limitation that should be highlighted immediately is that the initial release of the Family Graph API is a read-only API; applications can use the API can read and download, but not to write or upload.
This surely is a temporary state of affairs, that will be remedied by a future update. Until that time, it is important to be aware that the API is read-only, as that severely limits what you can do with it.

Terms of Service

The API documentation is public, and using the API is free of charge, but that is not all there is to it. Use of the Family Graph API is subject to the Family Graph API ToS. As is so often the case, the Family Graph API TOS can be changed whenever MyHeritage feels like doing so. The Family Graph API ToS includes the MyHeritage ToS.

MyHeritage tells you that you need an application key, but does not tell what to do with it.

application key

Before you can use the Family Graph, you need to request an application key, and then wait for MyHeritage to approve your request and provide you with one. When you request an application key, you agree to the Family Graph API ToS. One thing that ToS states is that MyHeritage reserves the right to disable your application or limit its access to Family Graph functionality.
That may sound bad, as it puts your app at their mercy, but it isn't any worse than the conditions of Apple's App Store.

There is something odd about the application key requirement. The Get access tab mentions the application key, the ToS page mentions the application key, the Contact page mentions the application key, but the Overview tab, the Documentation tab and the Sample applications tab do not. Getting an application key is mandatory, but the Family Graph API does not use it.
MyHeritage tells you that you need an application key, but does not tell what to do with it.

Not all Family Graph API functionality is available to all apps.

scope: application privilege

There is an important restriction that the ToS does not mention, and only becomes apparent when you read through the Family Graph documentation. Not all Family Graph API functionality is available to all apps. Some functionality requires a privilege that MyHeritage has to grant to your application before it can be used. These application privileges are known as scopes.

All applications get the basic scope, which allows using most of the Family Graph API, but there are two restricted scopes associated with the current Family Graph API.
Use of the ExportGEDCOM and ExportGEDCOMStatus objects is only available to applications that have been granted the ExportGEDCOM privilege, while a user's own email address and access to email addresses of individuals in trees is only available to applications that have been granted the email privilege.

JSON

Unlike the Geni API, the Family Graph API does not return results in XML format, but in JSON format only. The JavaScript Object Notation name is unfortunate; the JSON format is not tied to the JavaScript language at all. The JSON format is supported by JavaScript starting with ECMAScript Fifth Edition (ES5).

The JSON format is gaining in popularity, but it still does not enjoy the same widespread support by major libraries and frameworks as XML. Chances are that your favourite language does not come with JSON support. JSON is a simple format, that is easy to parse and generate, so it is not hard to roll your own JSON library, but you probably do not have to do so; the JSON web site has a list of existing JSON libraries you can use.

PHP SDK

The MyHeritage site appears to be a LAMP site; they use a Linux operating, the Apache web server, the MySQL database server and the PHP scripting language. MyHeritage job postings confirm this impression.

No big surprise then, that the Family Graph site includes an SDK for PHP. The Family Graph PHP SDK is made available under the Apache License, Version 2.0. You can find the PHP SDK link on the Documentation page, but you need not bother; the PHP SDK is included in the samples download.

The PHP SDK contains two classes: BaseFamilyGraph and FamilyGraph. The FamilyGraph class extends the BaseFamilyGraph class. The BaseFamilyGraph relies on and therefore requires the CURL and JSON extensions.

PHP samples

The Family Graph website offers several samples; Profiles, Faces, Sites, Tree and Object Browser. All these samples are PHP pages; web pages with the *.php extensions that contain a mix of HTML and PHP. These samples have to be run on a web server with PHP installed.
There currently are no samples in any other programming language. There probably will be samples in other languages in the future, but for now, you are on your own.

connection and session

The MyHeritage samples do not deal with establishing or closing down a connection. All the samples simply assume that there is a working Internet connection. They can do so, because PHP pages live on the server and are only invoked when a client requests the page.
When you create an app that does not live on a web server, but on the desktop or a mobile device, you have to establish and later close down an Internet connection using the methods available on your chosen development platform.

The Family Graph API is billed as a RESTfull API, so you do not need to create a session or maintain session state just to use the API. However, many family trees on MyHeritage are private, and only accessible when the user is logged in.

OAuth

The Family Graph API does not include any functions to log users in or out. Like the Geni API, the Family Graph API relies on OAuth. This way, apps using the API do not have to deal with user credentials.
This is a major architectural decision, yet the word OAuth does not appear even once on the entire familygraph.com site. The PHP BaseFamilyGraph code reveals the use of OAuth authorisation.
That mysterious application key you need? It is for use with OAuth.

users

Like many websites, MyHeritage distinguishes between members and visitors. The Family Graph API refers to members as users. The user credentials consist of the email address and password.
Your app does not need to know these user credentials, as users log in using OAuth. The Family Graph API does not identify users by email address, but by their unique user id.

identifiers

The Family Graph API contains several types of identifiers, such as user ids, site ids and tree ids. These identifiers really are just numbers, but within the Family Graph API, they have prefixes to tell them from each other; users ids are prefixed with user-, site ids are prefixed with site- and tree ids are prefixed with tree-.
The sample site, owned by user-10, is site-144530322, with default tree tree-144530322-1 and root individual individual-144530322-1000001.

The starting point is provided by the undocumented magic user id me.

magic user-id: me

You can navigate from one Family Graph API object such as User, Site, Tree and Album to another. It is all connected, but the familygraph.com documentation does not tell you how to get hold of some starting point inside that family graph. Examining the sample applications provides the answer. The starting point is provided by the undocumented magic user id me.

You can request the details for a particular user through the URL https://familygraph.myheritage.com/userid, where userid is the user id of the user you are interested in. For example, if you enter https://familygraph.myheritage.com/user-10 in the address bar of your browser, MyHeritage will return the User object for user-10 in JSON format.
That is nice, but it requires that you already know the user id for the current user. The problem is that you do not know any id.

The solution is the magic user id that does not start with the ubiquitous user- prefix: me.
The URL https://familygraph.myheritage.com/me will return the User object for the currently logged in user.
That is how you get started using the Family Graph API.