- Family Graph API
- PHP SDK
- iOS SDK
- Android SDK
Family Graph API
Getting startedThe 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.
Sample developerThe 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)
"name": "Developer MyHeritage",
"text": "July 28 1975",
"address": "Tilling Road",
"zip_code": "NW2 1LJ",
"name": "Demo Family Site"
"name": "Joseph Patrick Kennedy II"
Sample developer siteThe ID of the sample developer site is
site-, so you can access this object at https://familygraph.myheritage.com/site-144530322 (open in browser)
"name": "Demo Family Site",
"description": "Demo family site for developers",
"name": "Developer MyHeritage"
"name": "Joseph Patrick Kennedy II"
FieldsYou 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)
"name": "Developer MyHeritage",
ObjectsIDs 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:
- User: https://familygraph.myheritage.com/user-10 (open in browser)
- Family site: https://familygraph.myheritage.com/site-144530322 (open in browser)
- Family tree: https://familygraph.myheritage.com/tree-144530322-1 (open in browser)
- Individual: https://familygraph.myheritage.com/individual-144530322-1000001 (open in browser)
- Family: https://familygraph.myheritage.com/family-144530322-1000001 (open in browser)
- Event: https://familygraph.myheritage.com/event-144530322-1000002 (open in browser)
- Note: https://familygraph.myheritage.com/note-144530322-1-1 (open in browser)
- Album: https://familygraph.myheritage.com/album-144530322-1900003 (open in browser)
- Media: https://familygraph.myheritage.com/photo-144530322-1-1000002 (open in browser)
- Source: https://familygraph.myheritage.com/source-144530322-1000003 (open in browser)
- Citation: https://familygraph.myheritage.com/citation-144530322-1000001 (open in browser)
ConnectionsAll 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
Example of supported connections include:
- Trees of a site: https://familygraph.myheritage.com/site-144530322/trees (open in browser)
- Albums of a site: https://familygraph.myheritage.com/site-144530322/albums (open in browser)
- Sources of a family tree: https://familygraph.myheritage.com/tree-144530322-1/sources (open in browser)
- Events of an individual: https://familygraph.myheritage.com/individual-144530322-1000001/events (open in browser)
- Tags of a specific individual in all photos: https://familygraph.myheritage.com/individual-144530322-1000001/tags (open in browser)
- Tags of all individuals in a specific photo: https://familygraph.myheritage.com/photo-144530322-1-1000007/tags (open in browser)
- Membership if a member: https://familygraph.myheritage.com/user-10/memberships (open in browser)
- Smart Matches of an individual https://familygraph.myheritage.com/individual-144530322-1000167/smartmatches (open in browser)
Returning multiple objectsYou 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
AuthorizationTo 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:
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 modelBelow 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.
A user registered in MyHeritage.com. Users are real people with an email address. At the moment, there are more than 75 million such users.
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.
A family tree is the core object in a family site that maintains information about the individuals in the family and their relationships.
An individual (person) in a family tree. An individual may be associated with a user.
A family in a family tree connects between the two spouse (husband and wife individuals) and their children (individuals).
An event of an individual (e.g., birth, death) or a family (e.g., marriage).
A note about an individual, a family, an event or a citation.
An album for organizing media items.
Source of citations used in the family tree, such as a legal document, a book, an interview or a website.
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.
Information about the membership of a user in a family site.
A relationship between two individuals in a family tree.
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 diagramBelow is a high level diagram of the different objects and their connections:
PagingWhen 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)
"name": "Young Jackie"
"name": "Jackie Kennedy Color Portrait"
Event datesDates 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
"gedcom": "May 29 1917",
"text": "May 29 1917",
LanguagesData 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 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.
PHP SDKThe 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 SDKThe 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 SDKThe 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