familysearch-sdk

A modern, TypeScript-first SDK for the FamilySearch API v3.

Features

• 🔷 Full TypeScript support with comprehensive type definitions
• 🔐 OAuth v3 compatible authentication utilities
• 📊 Promise-based API for async operations
• 🌍 Environment support (production, beta, integration)
• 📝 GEDCOM export - Convert FamilySearch data to GEDCOM 5.5 format
• 📍 Places API helpers for location searches
• 👨‍👩‍👧 Tree/Pedigree API for ancestry data

Installation

npm install familysearch-sdk

Quick Start

import {
  createFamilySearchSDK,
  fetchPedigree,
  convertToGedcom
} from 'familysearch-sdk';

// Create SDK instance with your OAuth access token
const sdk = createFamilySearchSDK({
  environment: 'production',
  accessToken: 'your-oauth-token'
});

// Fetch pedigree data
const pedigree = await fetchPedigree(sdk, undefined, {
  generations: 5,
  onProgress: (progress) => {
    console.log(`${progress.percent}% complete`);
  }
});

// Convert to GEDCOM format
const gedcom = convertToGedcom(pedigree, {
  treeName: 'My Family Tree'
});

console.log(gedcom);

OAuth Authentication

The SDK provides utilities for OAuth 2.0 authentication with FamilySearch.

import {
  generateOAuthState,
  buildAuthorizationUrl,
  exchangeCodeForToken,
  validateAccessToken
} from 'familysearch-sdk/auth';

// Generate state for CSRF protection
const state = generateOAuthState();

// Build authorization URL
const authUrl = buildAuthorizationUrl({
  clientId: 'your-client-id',
  redirectUri: 'https://your-app.com/callback',
  environment: 'production'
}, state);

// Redirect user to authUrl...

// After callback, exchange code for token
const tokens = await exchangeCodeForToken(code, {
  clientId: 'your-client-id',
  redirectUri: 'https://your-app.com/callback',
  environment: 'production'
});

// Validate token
const isValid = await validateAccessToken(tokens.access_token, 'production');

Places API

Search and retrieve place information from FamilySearch.

import { createFamilySearchSDK } from 'familysearch-sdk';
import { searchPlaces, getPlaceDetails } from 'familysearch-sdk/places';

const sdk = createFamilySearchSDK({ accessToken: 'token' });

// Search for places
const results = await searchPlaces(sdk, 'London, England', {
  date: '1850',
  count: 10
});

// Get place details
const details = await getPlaceDetails(sdk, 'place-id');
console.log(details.name, details.latitude, details.longitude);

Tree/Pedigree API

Fetch and manage family tree data.

import { createFamilySearchSDK } from 'familysearch-sdk';
import { fetchPedigree, getCurrentUser } from 'familysearch-sdk/tree';

const sdk = createFamilySearchSDK({ accessToken: 'token' });

// Get current user
const user = await getCurrentUser(sdk);
console.log(user?.displayName);

// Fetch pedigree (will use current user's personId)
const pedigree = await fetchPedigree(sdk, undefined, {
  generations: 4,
  includeDetails: true,
  includeNotes: true
});

GEDCOM Conversion

Convert FamilySearch data to GEDCOM 5.5 format.

import { convertToGedcom } from 'familysearch-sdk/utils';

const gedcom = convertToGedcom(pedigreeData, {
  treeName: 'Family Tree',
  includeLinks: true,
  includeNotes: true
});

// Save to file
fs.writeFileSync('family.ged', gedcom);

Environment Configuration

The SDK supports three FamilySearch environments:

| Environment | Description | API Host | |-------------|-------------|----------| | production | Live production API | api.familysearch.org | | beta | Beta testing environment | apibeta.familysearch.org | | integration | Sandbox for development | api-integ.familysearch.org |

import { createFamilySearchSDK, ENVIRONMENT_CONFIGS } from 'familysearch-sdk';

// Create SDK for production
const sdk = createFamilySearchSDK({
  environment: 'production',
  accessToken: 'token'
});

// Access environment configuration
const config = ENVIRONMENT_CONFIGS['production'];
console.log(config.platformHost); // https://api.familysearch.org

Custom Logging

Provide a custom logger for debugging.

const sdk = createFamilySearchSDK({
  accessToken: 'token',
  logger: {
    log: (msg, ...args) => console.log(`[FS SDK] ${msg}`, ...args),
    warn: (msg, ...args) => console.warn(`[FS SDK] ${msg}`, ...args),
    error: (msg, ...args) => console.error(`[FS SDK] ${msg}`, ...args),
  }
});

API Reference

Core SDK

• FamilySearchSDK - Main SDK class
• createFamilySearchSDK(config) - Create a new SDK instance
• initFamilySearchSDK(config) - Initialize/get singleton instance
• getFamilySearchSDK() - Get singleton instance

Authentication (/auth)

• generateOAuthState() - Generate CSRF state
• buildAuthorizationUrl(config, state) - Build OAuth URL
• exchangeCodeForToken(code, config) - Exchange code for tokens
• refreshAccessToken(refreshToken, config) - Refresh access token
• validateAccessToken(token, environment) - Validate token

Places (/places)

• searchPlaces(sdk, query, options) - Search for places
• getPlaceById(sdk, id) - Get place by ID
• getPlaceChildren(sdk, id, options) - Get child places
• getPlaceDetails(sdk, id) - Get detailed place info

Tree (/tree)

• fetchPedigree(sdk, personId, options) - Fetch ancestry data
• getCurrentUser(sdk) - Get current user info
• getPersonWithDetails(sdk, personId) - Get person details
• fetchMultiplePersons(sdk, personIds) - Batch fetch persons

Utils (/utils)

• convertToGedcom(pedigreeData, options) - Convert to GEDCOM

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting a pull request.