Family Tree API - Display GEDCOM Online
The Family Echo API allows your desktop or web application to display a family tree using the online Family Echo display engine. Your application sends a family description in GEDCOM or FamilyScript format, and receives back a URL that can be used to browse that family interactively for the next 7 days.
The API is free and unlimited, and requires no developer registration. To prevent abuse, each request you send to the API must be in response to a user-initiated action in your application, such as a click on a button.
The information you provide in the API request will only be stored temporarily. It will be deleted from the Family Echo database after 7 days. The information will not be sold or shared with any third party.
The access the API, send an HTTP POST request to the URL:
All parameters are specified as form-urlencoded data within the HTTP POST payload. This is how web browsers submit forms over HTTP. If your programming language lets you set up an HTTP POST request with a list of parameter values, it will probably build this form-urlencoded payload automatically.
The parameters to be provided are as follows:
|Family to display
||[GEDCOM or FamilyScript in UTF-8]
||[GEDCOM or FamilyScript identifier]
|URL of logo image
||[URL of GIF, JPEG or PNG image]
|Width of logo to display
||[Width in pixels]
|Height of logo to display
||[Height in pixels]
format parameter is
xml, the response will be returned as UTF-8 encoded XML, within an outermost
<response> element. If the API call was successful, this will contain an inner
<url> element specifying the URL for browsing the family. Otherwise, it will contain an
<error> element with a textual explanation of the problem.
format parameter is
url, whose value is the URL for browsing the family. Otherwise, the object will contain the key
error, whose value is a textual explanation of the problem.
format parameter is
redirect, and the API call was successful, the HTTP response will contain a
Location: header redirecting to the URL for browsing the family. If the API call was not successful, the response will contain a plain text explanation of what went wrong. This format is particularly useful if you want to access the API via an ordinary form on a web page - see below for an example.
operation parameter is for future expansion of the API. For now, fix its value to
family parameter should contain a full description of the family, in GEDCOM or FamilyScript format with UTF-8 encoding. The API will automatically detect the correct format by examining the parameter's contents.
focus parameter (optional) allows you to specify which individual should be focused when the family tree is first displayed. If
family was in GEDCOM format, the
focus parameter should contain a GEDCOM cross-reference to the individual, e.g.
family was in FamilyScript format, the
focus parameter should contain the individual's FamilyScript ID, e.g.
R3QK8. If the
focus parameter is not provided, the focus individual will be the GEDCOM submitter (if available) or otherwise the first person described in the family.
The optional parameters
logo_height parameters allow you to specify a logo image that should be displayed instead of the Family Echo logo at the top of the family tree page.
Example of Usage
Below is a simple web-based form that can be used to send an HTTP POST request to the API:
Sample Code (PHP)
Below is a PHP function which can be used to make calls to the Family Echo API, and retrieve the response in XML or JSON format. It requires the PHP curl extension to be installed. An example of this function's usage is included.
function family_echo_api_temp_view($format, $family, $focus=null,
$logo_url=null, $logo_width=null, $logo_height=null)
$params=compact('format', 'family', 'focus',
'logo_url', 'logo_width', 'logo_height');
foreach ($params as $key => $value)
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $poststring);
"0 HEAD\n1 SOUR Family Echo\n2 WWW http://www.familyecho.com/\n".
"1 FILE My Family\n1 DATE 23 OCT 2011\n1 DEST ANSTFILE\n".
"1 GEDC\n2 VERS 5.5.1\n2 FORM LINEAGE-LINKED\n".
"1 SUBM @I1@\n2 NAME John Doe\n1 SUBN\n1 CHAR UTF-8\n".
"0 @I1@ INDI\n1 NAME John /Doe/\n2 GIVN John\n2 SURN Doe\n1 SEX M\n0 TRLR",
Please send any questions or comments about the API via the feedback form.