MyHeritage Family Graph API
Daniel Horowitz - MyHeritage Ltd.
Daniel@MyHeritage.com / www.MyHeritage.com
Objective
The purpose of this project is to develop an API for MyHeritage to be made available to any
approved 3rd party. Currently this API is read-only and all the documentation and examples
can be found at http://www.familygraph.com. Adding, editing and deleting information
capabilities will be added in the very near future.
The Family Graph API provides simple access to the core features and data on
MyHeritage.com. The API lets developers create applications using the MyHeritage dataset. It
presents a simple, consistent view of the data, with uniform representation of the objects in
the graph such as users, sites, trees, individuals, photos and sources; and the connections
between them including site memberships, family relationships and photo tags.
Architecture
The Family Graph API is based on the REST architecture (server-to-server authentication)
and all API calls return JSON objects.
To access the MyHeritage.com Family Graph API for a certain user, you must first get
permission from that user by getting an access token for the user. The Family Graph API uses
OAuth 2.0 for authorization. After successful authentication, all the API calls are performed on
the context of the authenticated user so the data available is only the data that the user can
see on MyHeritage, and you can perform authorized requests on behalf of that user by
including the access token in your Family Graph API requests.
Main Objects
There are 14 main objects, as follows: Site, Tree, Individual, Family, Note, Source, Event,
Family event, Citation, User, Album, Media item, Calendar, Calendar event. All of the objects
in the Family Graph are connected to each other via relationships. We refer to those
relationships as 'connections' in the API.
At the basic level MyHeritage.com includes a list of users and family sites. Users are real
people with an email address. At the moment, there are more than 61 million such users, and
they can be members of several family sites (none, one or multiple sites) A user can be a
manager of the site, which gives him special administrative privileges in the site, or a regular
member in the site. A user who is a member of a site can invite other users to become
members of the site.
A family site created by a user in order to preserve and share the family history. Usually
includes a family tree, but it can also include several such trees. Other users, typically family
relatives, can be invited to be members of the family site. At the moment, there are approx. 21
million family sites.
A family tree is the core object in a family site that maintains information about the individuals
in the family and their relationships. Individuals in the tree are connected using families - each
family can have a husband, a wife and children, though same-gender families are supported
too. Information such as names and gender are found in the individuals' objects.
Events such as birth and death are found in event objects that are connected to individuals
and events such as marriage are found in family events objects that are connected to families.
Dates of events such as birth, death and marriage are returned in the “eventdate” object. This
object has three fields:
 gedcom - the date of the event encoded in the GEDCOM standard.
 text - the date of the event formatted in the current language.
 date - the date of the event encoded in YYYY, YYYY-MM or YYYY-MM-DD format.
Notes, citations and source can be associated with objects in the family tree. Media items
such as photos, videos, documents and audios can also be part of a family site and can be
organized in albums. Individuals in the tree can be tagged in photos.
Languages
MyHeritage currently supports 38 languages and data can be stored in more than one
language at the time. For example the first name of an individual can be spelled and saved
differently in English and in Russian. By default, data is return in the language of the current
user, if there is data in that language for that object. Otherwise, the best matching language is
used, based on the character sets of the two languages.
To request for data in a particular language, add the lang=<language_code> parameter to
your call: https://familygraph.myheritage.com/individual-144530322-2000001?lang=RU
Other Objects
Individual: An individual (person) in a family tree. An individual may or not be associated with
a user.
Family: A family in a family tree connects between the two spouses (husband and wife
individuals) and their children (individuals).
Event: An event of an individual (e.g., birth, death) or a family (e.g., marriage).
Note: A note about an individual, a family, an event or a citation.
Album: An album for organizing media items.
Source: Source of citations used in the family tree, such as a legal document, a book, an
interview or a website.
Citation: Citation to a source, about an individual, family, event or note. A citation records
where a piece of information about an object in the tree is taken from.
Membership: Information about the membership of a user in a family site.
Relationship: A relationship between two individuals in a family tree.
Smart Match: A Smart Match is a match between two individuals who are thought to be the
same person, in two family trees from different family sites. Smart Matches help users find
connections between family trees.
Every object in the Family Graph is represented by a prefix for the type of the object and a
unique ID number. IDs parameter can be used to list more than one object to return in a single
response: https://familygraph.myheritage.com/?ids=tree-144530322-1,individual-1445303221000001,individual-144530322-1000002
Example of a profile retrieved via API.
High level diagram of the different objects and their connections.