Gramps Evidence

Add an alternate (non-primary) name to a person, cited to the record using it. Use for maiden/married names, aliases, anglicized forms, or nicknames-of-record. The person's primary name is left unchanged. Correct or remove one later with update_alternate_name.

Add a typed key/value attribute to an object. Sources and citations use a SrcAttribute; everything else uses an Attribute. The right class is chosen automatically from object_type.

Add an existing person as a child of an existing family. Links the child both ways: a ChildRef is added to the family and the family is added to the child's parent-family list. The child must already exist. Duplicate children are skipped.

Create a standalone Citation on a Source (or reuse an existing one). Usually you don't call this directly -- pass a CitationInput to add_person / add_event_to_person / add_family instead, which creates the citation and attaches it to the fact in one step. Use this when you want a reusable citation handle to attach to several facts.

Record a DNA match as evidence, cited to the test that found it. Stored as Gramps Web stores a match, so its interface and get_dna_matches read it back. Nothing is written unless the segments parse: unreadable data would otherwise record a match sharing no DNA. A match proves the two share DNA, not how they are related. Record any relationship separately, with its own evidence.

Share an existing event with another person, in a role. For one census entry, residence or burial that several people took part in: each references the same event, so its citations and later corrections serve all of them. Refused if the person already has it. A new fact is add_event_to_person.

Add a dated/placed event (fact) to an existing family. Use for family-level facts: marriage, divorce, residence, census. The event is added with the 'Family' role. Cite it to the record establishing the fact.

Add a dated/placed event (fact) to an existing person. Use for facts beyond birth/death: residence, occupation, census, baptism, immigration, marriage-adjacent events, etc. The event's citation should point at the record establishing the fact. Adding a 'Birth'/'Death' event will set the person's primary birth/death reference if not already set.

Create a family linking parents and children, with an optional cited marriage. All members must already exist (create them first with add_person). Creating the family automatically links each person's family/parent-family lists, so you don't need to update the individuals separately. Cite the marriage event to a marriage record where possible.

Upload a document as a standalone Media object, reusing an identical file already in the tree. One image, one Media object -- then attach it wherever it belongs with attach_media(media_ref=...) and cite it once per fact it proves. Uploading the same photograph once per person it depicts is the duplicate pattern that later has to be unpicked by hand.

Create a research/general note, optionally attached to an object. Use notes for research logs, reasoning about conflicting evidence, or transcriptions. Attach to a person/event/source by giving target + target_type.

Create a new person, optionally with cited birth and/or death events. Use this to add someone to the tree. Good practice: attach the birth event with a citation to the *specific* record that proves it (a birth or baptism certificate, a census entry), setting the citation's confidence honestly. If you only have a legacy-tree hint with no underlying record, either omit the event or set require_citation=False so it's flagged for follow-up. Returns the new person's handle and gramps_id.

Create a place deliberately, with a type and a parent. Use this instead of letting a place appear as a side effect of naming one in an event. That route produces an untyped, unparented place whose title is the bare string you typed, which is how duplicate hierarchies start.

Create a Repository (an institution or place that holds sources). Repositories sit at the top of the evidence model: Repository -> Source -> Citation -> fact. Create these for archives, libraries, cemeteries, or websites you'll cite sources from.

Create a Source (a body of evidence: a record set, book, certificate, website). In the Gramps evidence model a Source is what you cite *through* a Citation. Create the source once, then create citations against it for each fact it supports. Optionally link it to a Repository (where the source is held).

Add a web URL to a person, place, or repository. Only these three object types carry a URL list. For sources/citations, record a web address as an attribute (add_attribute) instead.

Ask the server whether a person is probably still alive, and why. The server walks relatives to decide, so it handles people with no dates of their own — someone undated whose children died a century ago. Use it before publishing or sharing anything, and use `explain` when you want to see the reasoning rather than just the verdict. Note this is advisory. Bulk output is filtered by this server's own rule regardless of what this returns.

Attach an image or document to an object -- a new upload, or one already in the tree. With file_path, the bytes are uploaded into the tree's managed media directory (so don't point at files you don't want copied); if that exact file is already present it is reused rather than duplicated. With media_ref, an existing Media object is linked. One image should be ONE Media object, linked from each object it belongs to and cited once per fact it proves. Uploading the same photograph separately for the husband and the wife creates duplicates that have to be unpicked later. The write is verified afterwards: `verified: false` means nothing attached, whatever the rest of the result says.

Audit the links between people and families, in both directions. Finds a family a person lists twice, a child a family lists twice, a link one side holds and the other lacks, and links to objects that do not exist. Each finding says how to repair it. Reports only.

Cite the parent-child link itself, on the family's ChildRef. "This child belongs to these parents" is a DIFFERENT claim from "this child appears in this record", and it needs its own citation object. Reusing the child's existing citation handle makes the link inherit a confidence that was assigned to another claim entirely, so the link displays a confidence its evidence never earned. Note what a ChildRef citation asserts: BOTH sides of the link. A census naming only the mother does not document the father. Where only one parent is evidenced, cite that parent's relationship instead of implying both.

Attach a citation to an event that ALREADY exists. Use this to source an event you didn't create with an inline citation -- e.g. one added through the Gramps web UI, or an unsourced event surfaced by list_unsourced_facts. The citation is resolved/created (existing handle/id, or an inline source_title + page + confidence) and appended to the event's citation list (no duplicates). Does not change any other event field.

Attach a citation to any object that carries one -- not just events. cite_event covers facts; this covers the rest. The important case is the FAMILY, whose citation supports a claim no event makes: that these two people were a couple. Person-level citations are for evidence about the individual as a whole (an identity document) rather than about one dated fact -- prefer citing the specific event where one exists. A NAME is cited with object_type='name': "this record gives this spelling" is narrower than evidence about the person. To cite a parent-child link, use cite_child_link: that is a different claim and needs its own citation.

Merge several people or families into one chronological timeline. The way to see a household move together through censuses, or to check whether a family's events are mutually consistent. Carries the same citation count and confidence per event as get_timeline, with an uncited_count across the whole set.

Consult the legacy GEDCOM reference layer for HINTS (never authoritative). Searches the configured Ancestry/FamilySearch exports and returns, per file, matching individuals and their claimed facts. Crucially, each fact is flagged whether the legacy tree attached a source, with the source text if present -- so you can distinguish 'they cite an actual death certificate' from 'unsourced guess'. These are UNTRUSTED hints: use them to decide what real record to hunt for, then create the fact in the tree citing that record -- do not copy a hint in as a sourced fact. Probably-living people are withheld and counted.

Save a reusable custom filter built from Gramps' own rules. Worth doing for a selection you will run repeatedly — an audit scope, a branch of the tree — because the filter then has a name rather than being retyped each time.

Counts of people, families, events, citations, sources, repositories, places, media, and notes in the tree. A quick health/overview check.

Delete a saved custom filter. Deletes the filter definition only. Nothing in the tree is touched.

Permanently delete an object from the tree by handle or gramps_id. DESTRUCTIVE. The server also removes every reference to it. Refused when it is the only holder of a note or image (pass carry_to to move them), and for a source with citations, which the server would delete with it.

Remove a reference from an object: an event from a person, an image from a source, a tag, a note, a child from a family. The reference is removed; the object itself survives unless delete_if_orphan is set AND nothing else points at it -- which is checked, because deleting something other facts still reference leaves dangling handles behind.

Measure the elapsed time between two events. The arithmetic behind most plausibility checks: age at marriage, years between a census and a death, how long a widow waited. Doing this by hand from two formatted date strings is where transcription errors hide.

Write a full-tree export to disk. Take one before any bulk write. Cheap insurance: a few seconds and one file. A bulk write that goes wrong cannot always be undone transaction by transaction; a dump can be re-imported.

Find likely-duplicate objects. Reports only -- it never merges anything. Duplicates are not merely untidy: a duplicate SOURCE makes a single-sourced fact look corroborated, which is a false evidentiary claim. But the reverse error is just as real -- an index entry and the register page it indexes are TWO documents and must stay separate. This tool finds candidates; deciding which are truly the same document is yours. Merge with merge_objects.

Walk a person's ancestors up to N generations (a nested parents tree). Living/private ancestors appear as redacted stubs unless include_private is set.

List everything that references this object, grouped by type. The right way to ask "is this source actually cited?", "which facts rest on this citation?", or "is it safe to delete this?" -- an object with zero backlinks is orphaned; one with backlinks will leave dangling references if deleted.

Read one citation: page, confidence, date, and its source. `cited_by_count` is the useful part. Zero means nothing references this citation — it is orphan debris, and `uncite` should have deleted it.

Walk a person's descendants up to N generations (a nested children tree). Living/private descendants appear as redacted stubs unless include_private is set.

List the DNA matches recorded against a person. Each match reports total shared centiMorgans and the largest single segment — the two figures a relationship estimate actually rests on — plus any common ancestor already identified. **DNA evidence works differently from documentary evidence.** A match proves a biological relationship exists; it does not say which one. Shared cM constrains the possibilities and rarely resolves them, and it says nothing about the paper trail. `unattributed_count` is the useful number: matches with no common ancestor identified are the open research.

Get an event: type, date, place handle, description, citation count, and attributes. Use to inspect an event before citing or editing it.

Read the tree's record-holders: oldest at death, youngest parent, most children. Superlatives across a set of people, not statistics about one person. An implausible holder — a father at eight, a death at 130 — is usually a data error, which makes this a quick plausibility check. Living and private people are excluded unless include_private is set. Slow: the server computes it all per call.

Get a family: relationship type, parent handles, child handles, event count.

Read one media object: path, mime type, checksum, description, date. `referenced_by_count` above one is usually correct — one image cited from every fact it proves. Several media objects sharing a checksum is the duplicate that `find_duplicates(kind='media_checksum')` hunts.

Read one note in full, with its type and what it is attached to. Notes hold the researcher's own reasoning — why a conflict was resolved one way, what a hard-to-read page actually said — so the text comes back whole rather than truncated.

Read any object's raw record -- including places, media, notes and citations, which have no shaped getter. Returns the record as stored, which is what you want before editing one. For people and sources the shaped getters (get_person, get_source) are easier to read.

Get full detail for one person: name, gender, events (with citation counts), family links, and media count. Direct lookup is allowed even for living/private individuals (this is your own local tool); only bulk/list tools filter them. Use this to inspect someone before adding facts, or to check whether an event is already cited.

Read one place: name, title, type, enclosure, coordinates and URLs. The `enclosed_by` handles are the jurisdictional chain. A place with none is orphaned in the hierarchy, which is usually a place that got minted from an event's place string rather than created deliberately.

Work out how two people in the tree are related. Returns the relationship in words plus the generation distance from each person to their common ancestor. `related` is false when no common ancestor was found within the search depth — which is a finding in itself if you expected one.

Read one report's default options before running it. Reports take a full option dict, not a partial one, so the way to change a single setting is to read these defaults and override that key.

Get a repository: name, type, URLs, address count, and (if available) the number of sources it holds.

Read the researcher details recorded for this tree. These are embedded in every export, so they travel with any GEDCOM or Gramps XML you hand to someone else. Worth checking before sharing one.

Get a source: title, author, publication info, abbreviation, linked repositories, media/note counts, attributes, and citation count. Use to inspect a source before citing through it or editing it.