Family Tree API - Display GEDCOM Online

Introduction

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 Basics

The access the API, send an HTTP POST request to either of these URLs:

http://api.familyecho.com/
https://www.familyecho.com/api/

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:

Response Formats

If the 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.

If the format parameter is json, the response will be returned in JavaScript Object Notation format. If the API call was successful, an object will be returned containing the key 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.

If the 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.

Other Parameters

The operation parameter is for future expansion of the API. For now, fix its value to temp_view.

The 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.

The 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. @I123@. If 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_url , logo_width and 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. All the other optional parameters let you control exactly how the family is displayed. If they are excluded, Family Echo's default settings will be used.

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.

<?php
    
    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');
        
        $poststring='operation=temp_view';

        foreach ($params as $key => $value)
            if (isset($value))
                $poststring.='&'.urlencode($key).'='.urlencode($value);
                
        $curl=curl_init('http://api.familyecho.com/');

        curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($curl, CURLOPT_POST, true);
        curl_setopt($curl, CURLOPT_POSTFIELDS, $poststring);
            
        $result=curl_exec($curl);
            
        curl_close($curl);

        return $result;
    }
    
    echo family_echo_api_temp_view(
        "json",
        
        "0 HEAD\n1 SOUR Family Echo\n2 WWW https://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",
        
        "@I1@"
    );
    
?>

Getting Help

Please send any questions or comments about the API via the feedback form.