Family Echo Family Tree API

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 the URL:

http://api.familyecho.com/

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:

Parameter Explanation Value Required?
format Response format xml | json | redirect Yes
operation API operation temp_view Yes
family Family to display [GEDCOM or FamilyScript in UTF-8] Yes
focus Focus individual [GEDCOM or FamilyScript identifier] No
logo_url URL of logo image [URL of GIF, JPEG or PNG image] No
logo_width Width of logo to display [Width in pixels] No
logo_height Height of logo to display [Height in pixels] No
hide_header Hide the header at the top 1 | 0 No
hide_sidebar Hide the sidebar by default 1 | 0 No
hide_navbar Hide the navigation bar at bottom 1 | 0 No
no_centering Do not re-center tree on clicked person 1 | 0 No
zoom_factor How large to show the tree 0.5 to 2.0 No
parent_gen Show how many levels of parents 1 to 15 No
child_gen Show how many levels of children 1 to 15 No
other_gen Show how many levels of others 0 to 15 No
show_detail Show additional details on the tree none | life_dates
| life_years | birth
| death | email
| address | telephone
| profession | company
| interests | activities
No
show_middle Show middle names 1 | 0 No
surname_birth Show surnames at birth (if changed) 1 | 0 No
living_color Color for living people Standard HTML colors (e.g. #ff0000 | ff0000 | #f00 | f00 | red for red color) No
deceased_color Color for deceased people Standard HTML colors (e.g. #ff0000 | ff0000 | #f00 | f00 | red for red color) No

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:

GEDCOM or FamilyScript:

Response Format:

All the parameters below are optional:

Focus individual:

Logo URL: - Size: x pixels

Hide header   Hide sidebar   Hide navigation bar   No auto re-centering

Zoom factor:   Show detail:   Middle names:   Surnames:

Parent generations:   Child generations:   Other generations:

Color for living:   Color for deceased:

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 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",
        
        "@I1@"
    );
    
?>

Getting Help

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

About     FAQs     API     Baby Names     Resources     Terms     Data Policies     Send Feedback
© Familiality 2014 - All rights reserved