Overview
Documentation
Sample applications
Get access

Family Graph API

Getting started

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.

The Family Graph API is based on the REST architecture and all API calls return JSON objects.

The API currently supports reading information and does not yet support adding, editing and deleting information. These capabilities will be added in the very near future.

Every object in the Family Graph has a unique ID. You can access the properties of an object by requesting it, e.g. https://familygraph.myheritage.com/ID.

Examples:

Sample developer

The ID of the sample developer user is user-10, so you can access this object at https://familygraph.myheritage.com/user-10 (open in browser) 
{
	"first_name": "Developer",
	"last_name": "MyHeritage",
	"nickname": "dev",
	"is_privatized": false,
	"preferred_display_language": "EN",
	"preferred_email_language": "EN",
	"link": "https:\/\/www.myheritage.com\/member-10_1\/member",
	"country_code": "GB",
	"country": "United Kingdom",
	"created_time": "2006-06-26T16:40:50+0000",
	"last_visit_time": "2019-12-04T14:43:59+0000",
	"is_public": true,
	"show_age": true,
	"allow_posting_comments": false,
	"notify_on_comment": false,
	"show_real_name": true,
	"reports_full_name": [
		"",
		""
	],
	"personal_photo": {
		"id": "photo-0-3-12181762"
	},
	"default_site": {
		"id": "site-144530322",
		"name": "Demo Family Site"
	},
	"default_tree": {
		"id": "tree-144530322-1",
		"name": "jfk"
	},
	"default_individual": {
		"id": "individual-144530322-1000028",
		"name": "Joseph Patrick Kennedy II"
	},
	"age_group": "A",
	"age_group_in_years": "40's",
	"suggestions": {
		"id": "suggestions-10"
	},
	"new_notifications_count": 0,
	"colorization_count": 0,
	"color_restoration_count": 0,
	"enhancement_count": 0,
	"repair_count": 0,
	"photo_with_portrait_animation_count": 0,
	"live_story_created_count": 0,
	"live_story_edited_count": 0,
	"preferences": {
		"id": "userpreferences-1000000000"
	},
	"is_mobile_subscription": false,
	"default_photo_site": {
		"id": "site-144530322",
		"name": "Demo Family Site"
	}
}

Sample developer site

The ID of the sample developer site is site-, so you can access this object at https://familygraph.myheritage.com/site-144530322 (open in browser)

Fields

You can also request for specific fields in an object by adding the fields names like this: https://familygraph.myheritage.com/user-10?fields=nickname,gender (open in browser)

Deep nesting

It is possible to request further fields of fields, in a nesting way: https://familygraph.myheritage.com/user-10?fields=site.id,site.name (open in browser)
Multiple fields can also be wrapped in round brackets: https://familygraph.myheritage.com/user-10?fields=site.(id,name) (open in browser)

Parameters

General parameters can be provided to further specify the requst: https://familygraph.myheritage.com/site-144530322?fields=media,albums&thumbnail_size=96x96&thumbnail_type=small (open in browser)

However, the parameters will impact all fields. We can be more specific in following way: https://familygraph.myheritage.com/site-144530322?fields=media{thumbnail_size=96x96;thumbnail_type=small},albums (open in browser) Note that any param value that contain special chars (such as , & =) must be url-encoded.

Conditional fields

An additional parameter can be added (using the specific field syntax only), to ask for a field only if a certain condition is met.
For example, we will ask for the trees of a site, only if it has 5 or less trees: https://familygraph.myheritage.com/site-144530322?fields=tree_count,trees{condition=tree_count%3C%3D5} (open in browser)
(%3C%3D is <= encoded)

Expressions for the condition must be in one of the following structures: a=b, a!=b, a>b, a>=b, a<b, a<=b, a, !a.

Objects

IDs in the Family Graph consist of a prefix for the type of the object (user, site, photo, etc.) and a unique number within this object type. While the prefixes will remain the same, MyHeritage reserves the right to change the implementation of the numbers in the future so their value cannot be assumed to be fixed over time.

Example of supported objects include:

Connections

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. You can examine the connections between objects using the URL structure https://graph.myheritage.com/ID/CONNECTION_TYPE.

Example of supported connections include:

Returning multiple objects

You can use the ids parameter to list more than one object to return in a single response. For example:
https://familygraph.myheritage.com/?ids=tree-144530322-1,individual-144530322-1000001,individual-144530322-1000002 (open in browser) returns three objects, a tree and two individuals in the same response

Authorization

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. After you obtain the access token for the user, you can perform authorized requests on behalf of that user by including the access token in your Family Graph API requests:
https://familygraph.myheritage.com/REQUEST?bearer_token=...

The Family Graph API uses OAuth 2.0 for authorization. Please read the authentication guide which provides details of MyHeritage.com OAuth 2.0 implementation, how to request permissions from a user and obtain an access token.

Object model

Below is a list of all object types that are used in the Family Graph API. At the basic level MyHeritage.com includes a list of users and family sites. A user can be a member of several family sites (none, one site or multiple sites) A user can be a manager of the site, which gives this user 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 usually includes a family tree, but it can also include several such trees. A family tree includes a collection of individuals. 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. 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.

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.

Object types

  • User
    A user registered in MyHeritage.com. Users are real people with an email address. At the moment, there are more than 57 million such users.
  • Site
    A family site created by a user in order to preserve and share the family history. Other users, typically family relatives, can be invited to be members of the family site. At the moment, there are approx. 18 million family sites.
  • Tree
    A family tree is the core object in a family site that maintains information about the individuals in the family and their relationships.
  • Individual
    An individual (person) in a family tree. An individual may be associated with a user.
  • Family
    A family in a family tree connects between the two spouse (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 match between two individuals in two family trees that are found to be referring to the same person. Smart Matches help users find connections between family trees.

Object diagram

Below is a high level diagram of the different objects and their connections:

documentation
Larger view

Paging

When requesting lists, you can specify which page in the list to return using the offset and limit parameters.

This example requests 2 photos in the album starting with the 5th photo: https://familygraph.myheritage.com/album-144530322-2/media?offset=4&limit=2&fields=name (open in browser)

Event dates

Dates of events such as birth, death and marriage are returned in the eventdate object. This object has four 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.
  • structured_date - the date of the event in a structured format
Example: https://familygraph.myheritage.com/event-144530322-1000002?fields=date (open in browser)

Languages

Data in MyHeritage can be stored in more than one language. For example the first name of an individual can be spelled and saved differently in English and in Russian. By default, data is returned 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.

For example:

SDKs

PHP SDK

The PHP SDK provides Family Graph support for PHP-based web apps. This library can help you add MyHeritage Login and Family Graph API support to your Website.
Download PHP SDK

iOS SDK

The iOS SDK provides Family Graph support for iOS native apps. This library can help you add MyHeritage Login and Family Graph API support to your iOS application.
Download iOS SDK

Android SDK

The Android SDK provides Family Graph support for Android native apps. This library can help you add MyHeritage Login and Family Graph API support to your Android application.
Download Android SDK

Browser

You can use the handy browser application to view the return results and traverse the graph easily.
MyHeritage.com  |  About us  |  Terms of service  |  Contact us MyHeritage Ltd.