Import your Geni family tree into your self-hosted ɳFamily instance. Pull persons, relationships, photos, and the unique Geni "big tree" connections that link your family to millions of others.
Requires nself-family. Geni uses OAuth 2.0. The importer reads your immediate tree and optionally follows the big tree edges to import extended relatives.
nself license set nself_pro_...
nself plugin install family family-geni
nself build
nself startnself-family-geni authenticates with the Geni API via OAuth 2.0 and fetches the authenticated user's immediate family tree. Each Geni profile maps to a np_family_members row; relationships (parent, spouse, sibling, child) map to np_family_relationships.
Geni's "big tree" model means any person in your tree may be connected to a vast number of extended relatives through shared profiles. By default the importer stops at your immediate tree. Setting PLUGIN_GENI_IMPORT_DEPTH to a higher number walks the big tree outward — useful for finding distant cousins already on Geni, but can pull in thousands of records on the first run.
Photos attached to Geni profiles are downloaded into MinIO when nself-photos is installed. Documents and sources linked from Geni facts are stored as citations in np_geni_sources.
| Variable | Required | Default | Description |
|---|---|---|---|
PLUGIN_GENI_APP_ID | Yes | — | Geni application ID from the Geni Developer page |
PLUGIN_GENI_APP_SECRET | Yes | — | Geni application secret |
PLUGIN_GENI_IMPORT_DEPTH | No | 2 | How many relationship hops to follow from the authenticated user. 1 = immediate family only. Higher values pull extended big tree. |
PLUGIN_GENI_SYNC_INTERVAL_HOURS | No | 24 | How often to check for changes. Set to 0 to disable. |
PLUGIN_GENI_IMPORT_PHOTOS | No | true | Download profile photos into MinIO. Requires nself-photos. |
PLUGIN_GENI_MAX_PERSONS | No | 5000 | Hard cap on persons imported per run. Prevents runaway big tree imports. |
| Endpoint | Method | Description |
|---|---|---|
/geni/auth | GET | Begin OAuth flow. Redirects to Geni login. |
/geni/callback | GET | OAuth callback. Stores tokens and triggers first import. |
/geni/import | POST | Trigger a manual import. Body: { depth? } (overrides env default for this run) |
/geni/status | GET | Last sync time, person count, depth reached, errors |
/geni/sources/:person_id | GET | Source citations for a local family member |
/health | GET | Plugin health check |
| Table | Purpose |
|---|---|
np_geni_tokens | OAuth access + refresh tokens per user |
np_geni_person_map | Maps Geni profile IDs to local np_family_members IDs |
np_geni_sources | Source citations: person_id, fact_type, title, url, geni_document_id |
np_geni_sync_log | Import history: started_at, depth, persons_imported, cap_hit, errors |
| Event | Payload |
|---|---|
geni.import.completed | Persons imported, depth reached, cap_hit boolean, duration |
geni.auth.revoked | User ID — sync paused until re-auth |
Start with the default import depth and expand only after confirming the initial import looks correct:
# 1. Register app at https://www.geni.com/platform/applications/new
# Callback URL: https://your-nself-host/geni/callback
# 2. Authorize
open https://your-nself-host/geni/auth
# 3. Run a deeper import (overrides env depth for this run only)
curl -X POST https://your-nself-host/geni/import \
-H 'Authorization: Bearer <token>' \
-d '{"depth": 3}'| Feature | nself-family-geni | Geni.com only | GEDCOM export |
|---|---|---|---|
| Self-hosted | Yes | No | Yes (one-time) |
| Big tree import | Yes (configurable depth) | N/A | No |
| Automatic sync | Yes | N/A | No |
| Photos included | Yes (into MinIO) | Yes (on Geni only) | No |
| Symptom | Fix |
|---|---|
| Import hits person cap immediately | Your tree (with big tree edges at current depth) exceeds PLUGIN_GENI_MAX_PERSONS. Reduce PLUGIN_GENI_IMPORT_DEPTH first to import just immediate family, then gradually increase depth on subsequent runs. |
| Geni returns 429 during import | The Geni API rate-limits at 60 requests per minute. The plugin backs off automatically with exponential delay. Large imports will pause and resume — check status after 10–15 minutes. |
| Photos missing for some persons | Not all Geni profiles are public. Photos are skipped when the profile is private or the access token does not have rights to view that person. |
Port: 3832 | Bundle: ɳFamily ($0.99/mo) or ɳSelf+ ($3.99/mo) | Last Updated: May 2026 | Plugin Version 1.0.13