FamGEN – FamilySearch API Interface (Status 4.19)

Updating the Family Tree and CET Projects

The API interface connects your FamGEN inputs directly with the Family Tree as well as optionally with CET projects of FamilySearch.

In addition to classic person maintenance, FamGEN now also enables advanced analysis, DNA integration, document management (Memories), map features, and efficient workflows – entirely in the browser, without switching systems.

Typical Use Cases (Updated)

• Create new person (including extended facts such as birth, marriage, death, migration)
• Update existing person via PID
• Set relationships (parents, spouses, children)
• Document DNA test participants (without making relationship claims)
• Upload documents (Memories) directly to FamilySearch
• Perform analyses by locations, events, and time periods
• Retrieve and visualize ancestors/descendants (Topola, KML)

Functionality

1. Core Data & API Operations

• Create new person (including extended facts: birth, death, marriage, migration, occupation, residence)
• Update existing person via PID
• Automatic normalization (e.g., date: 20.08.1910 → 20 Aug 1910)
• Load a person (including automatic prefill of the input form)
• Direct navigation to:
  • Details
  • Sources
  • Family Tree
  • Timeline
  • Memories

2. Relationships (Relationship Management)

• Link child ↔ parents
• Link spouses
• Multiple linking via log (batch processing)
• Convenience control via Area 8 (assignment logic)
• Safety mechanisms to prevent incorrect relationships

3. Retrieval & Analysis Functions

• Retrieve:
  • Ancestors (n generations)
  • Descendants (n generations)
  • Combination (ancestors and descendants)
• Direct transfer to:
  • Topola (family tree visualization)
• Filter and selection functions in the result area

4. Advanced Analysis

• Births ↔ location
• Deaths ↔ location
• Marriages ↔ location
• Emigration
• Frequency of births per location

Functions:

• Sorting by date / location / first name
• Substring search (e.g., district level)
• Result display with selection and filter options

5. Memories (Document Management)

• Upload files (.jpg, .pdf) directly to FamilySearch
• Automatic prefill via file name (e.g., Archion logic)
• Structured metadata:
  • Time period
  • Location
  • Title
  • Description (caption)
• Support for standardized source citations

6. DNA Matches Integration

• Management of DNA test participants as descendants
• Support for multiple DNA platforms:
  • GEDmatch
  • MyHeritage
  • Ancestry
  • FTDNA
• Automatic generation of GDPR-compliant notes
• Table management of DNA matches including delete and assignment functions

7. Location Register & Maps

• Automatic location register from FS data
• Storage of:
  • Coordinates
  • District / federal state
• Map features:
  • Google Earth
  • KML export
  • geojson.io
• Integration of historical maps

8. Favorites & Log

• Storage of up to 10 favorites
• Log of all actions
• Reuse of datasets
• Direct access to FamilySearch pages

9. Patriarch Management

• Own table for managing genealogical lines
• Storage:
  • Name
  • PID
  • Year of birth
• Direct link to pedigree view

10. GEDCOM & ADaTP Integration

• Transfer to person and location search, GEDCOM generator, and chatbots
• ADaTP as central data interface
• Live data from FamilySearch (no caching)

Key Advantages

• All-in-one solution: maintenance + analysis + documentation + DNA
• 100% browser-based (no server required)
• Direct integration with FamilySearch
• Extendable for CET projects
• Structured workflows for secure data entry

Typical Scenarios

• Building genealogical lines (including patriarchs)
• Documentation with sources (Memories)
• DNA-supported research
• Regional analysis (e.g., location analysis)
• Visualization (Topola, KML)
• Data export (GEDCOM)

How to Use the API (Workflow)

1. Login
   → OAuth2 dialog, status indicator active
2. Enter or load data
   → manually or via GEDCOM / URL
3. Perform pre-check
   → duplicate check or detail view
4. Select operation
   • Create person
   • Update person
   • Link persons
   • Fetch
   • Evaluate
   • DNA matches / Memories
5. Set reason for change (recommended)
   → transferred as X-Reason
6. Execute operation
   → result display + status banner

Hotkeys & Usability

• Extensive keyboard control (ALT+…)
  • ALT+A → Start operation
  • ALT+D → DNA matches
  • ALT+F → Show favorites
  • ALT+M → Memories
  • ALT+P → Show protocol
  • ALT+R → Reset operation
  • ALT+S → Patriarchs
  • ALT+T → Open Topola
  • and more
• Quick access to all areas
• Focus control within the form

Technical Requirements

• Free FamilySearch account
• Client ID (App ID) of a registered FamilySearch application
• Configured redirect URI in the app (must exactly match the accessed api.html)
• Modern browser (Chrome, Edge, Firefox)

Login & Authentication

• Login via OAuth2 with PKCE directly in the browser
• Clicking “Login” opens the FamilySearch dialog
• Successful login confirmed by status indicator
• Automatic token refresh before expiration
• Logout fully removes the token

Data Protection & Costs

• Access tokens are stored locally in the browser only (localStorage)
• No transmission to external servers
• API usage is free of charge
• Official FamilySearch API limits apply

DNA Function

• Only pseudonymized DNA IDs
• No lineage claims
• GDPR-compliant usage through data minimization

Technical Notes

Authentication

• OAuth2 PKCE
• Token in localStorage
• Auto-refresh + status indicator

API

Base: https://api.familysearch.org/platform

Header:

• Authorization: Bearer Token
• Accept / Content-Type: application/x-fs-v1+json
• Optional: X-Reason

Supported Core Operations

• createPerson
• updatePerson
• Relationships (Child/Parents, Couple)
• fetchAncestors / fetchDescendants
• fetchPerson