This is a C# library that provides support for consuming the FamilySearch API.
The FamilySearch API is an implementation of the GEDCOM X RS Specification, plus some custom FamilySearch extensions. As such, the FamilySearch API SDK extends the GEDCOM X RS Client.
| Package ID | Link |
|---|---|
| FamilySearch.API.SDK | http://www.nuget.org/packages/FamilySearch.API.SDK/ |
See the section on using these libraries.
To determine the latest version visit the NuGet link listed above.
The FamilySearch API SDK extends the GEDCOM X RS Client. In addition to the base functionality of the GEDCOM X RS Client, the FamilySearch API SDK provides additional model classes, convenience classes, and methods to support FamilySearch-specific functionality.
The FamilySearch API uses hypermedia as the engine of application state and so using a client feels like browsing the web. As such, the SDK feels like using a screen scraper. The process can generally be summarized as follows:
Web sites have a "home page". The FamilySearch API has "home collections". Examples of collections include the FamilySearch Family Tree, FamilySearch Memories, and FamilySearch Records.
You get stuff done on a web site by following links to where you want to go. Ditto for the FamilySearch API.
Follow more links to get more stuff done.
Need something to sink your teeth into?
- Read the FamilySearch Family Tree (Start Here)
- Read a Family Tree Person by Persistent ID
- Read a Family Tree Person by Family Tree ID
- Read a Family Tree Person by Family Tree ID, Including Relationships
- Search for Persons or Person Matches in the Family Tree
- Create a Person in the Family Tree
- Create a Couple Relationship in the Family Tree
- Create a Child-and-Parents Relationship in the Family Tree
- Create a Source
- Create a Source Reference
- Read Everything Attached to a Source
- Read Person for the Current User
- Read Source References
- Read Persona References
- Read Discussion References
- Read Notes
- Read Parents, Children, or Spouses
- Read Ancestry or Descendancy
- Read Person Matches (i.e., Possible Duplicates)
- Declare Not a Match
- Add a Name or Fact
- Update a Name, Gender, or Fact
- Create a Discussion
- Attach a Discussion
- Attach a Photo to a Person
- Read FamilySearch Memories
- Upload Photo or Story or Document
- Create a Memory Persona
- Create a Persona Reference
- Attach a Photo to Multiple Persons
Before you do anything, you need to start by reading the collection that you want to read or update.
May we suggest you start with the FamilySearch Family Tree?
Boolean useIntegration = true; //whether to use the integration (previously sandbox) reference.
String username = "...";
String password = "...";
String developerKey = "...";
//read the Family Tree
FamilySearchFamilyTree ft = new FamilySearchFamilyTree(useIntegration);
//and authenticate.
ft.AuthenticateViaOAuth2Password(username, password, developerKey);String username = "...";
String password = "...";
String developerKey = "...";
String ark = ...; //e.g. "https://www.familysearch.org/ark:/61903/4:1:KW8W-RF8"
FamilyTreePersonState person = new FamilyTreePersonState(new Uri(ark))
.AuthenticateViaOAuth2Password(username, password, developerKey);String pid = ...; //e.g. "KW8W-RF8"
FamilySearchFamilyTree ft = ...;
FamilyTreePersonState person = ft.ReadPersonById(pid);String pid = ...; //e.g. "KW8W-RF8"
FamilySearchFamilyTree ft = ...;
FamilyTreePersonState person = ft.ReadPersonWithRelationshipsById(pid);FamilySearchFamilyTree ft = ...;
//put together a search query
GedcomxPersonSearchQueryBuilder query = new GedcomxPersonSearchQueryBuilder()
//for a John Smith
.SetName("John Smith")
//born 1/1/1900
.SetBirthDate("1 January 1900")
//son of Peter.
.SetFatherName("Peter Smith");
//search the collection
PersonSearchResultsState results = ft.SearchForPersons(query);
//iterate through the results...
List<Entry> entries = results.Results.Entries;
//read the person that was hit
PersonState person = results.ReadPerson(entries[0]);
//search the collection for matches
PersonMatchResultsState matches = ft.SearchForPersonMatches(query);
//iterate through the results...
entries = results.Results.Entries;
//read the person that was matched
person = results.ReadPerson(entries[0]);FamilySearchFamilyTree ft = ...;
//add a person
PersonState person = ft.AddPerson(new Person()
//named John Smith
.SetName(new Name("John Smith", new NamePart(NamePartType.Given, "John"), new NamePart(NamePartType.Surname, "Smith")))
//male
.SetGender(GenderType.Male)
//born in chicago in 1920
.SetFact(new Fact(FactType.Birth, "1 January 1920", "Chicago, Illinois"))
//died in new york 1980
.SetFact(new Fact(FactType.Death, "1 January 1980", "New York, New York")),
//with a change message
FamilySearchOptions.Reason("Because I said so.")
);FamilySearchFamilyTree ft = ...;
PersonState husband = ...;
PersonState wife = ...;
RelationshipState coupleRelationship = ft.AddSpouseRelationship(husband, wife, FamilySearchOptions.Reason("Because I said so."));FamilySearchFamilyTree ft = ...;
PersonState father = ...;
PersonState mother = ...;
PersonState child = ...;
ChildAndParentsRelationshipState chap = ft.AddChildAndParentsRelationship(child, father, mother, FamilySearchOptions.Reason("Because I said so."));FamilySearchFamilyTree ft = ...;
//add a source description
SourceDescriptionState source = ft.AddSourceDescription(new SourceDescription()
//about some resource.
.SetAbout("http://familysearch.org/ark:/...")
//with a title.
.SetTitle("Birth Certificate for John Smith")
//and a citation
.SetCitation("Citation for the birth certificate")
//and a note
.SetNote(new Note().SetText("Some note for the source.")),
//with a change message.
FamilySearchOptions.Reason("Because I said so.")
);//the person that will be citing the record, source, or artifact.
PersonState person = ...;
SourceDescriptionState source = ...;
person.AddSourceReference(source, FamilySearchOptions.Reason("Because I said so.")); //cite the source.//the source.
SourceDescriptionState source = ...;
SourceDescriptionState attachedReferences = ((FamilySearchSourceDescriptionState)source).QueryAttachedReferences();
//iterate through the persons attached to the source
List<Person> persons = attachedReferences.Entity.Persons;FamilySearchFamilyTree ft = ...;
PersonState person = ft.ReadPersonForCurrentUser();//the person on which to read the source references.
PersonState person = ...;
//load the source references for the person.
person.LoadSourceReferences();
//read the source references.
List<SourceReference> sourceRefs = person.Person.Sources;//the person on which to read the persona references.
PersonState person = ...;
//load the persona references for the person.
person.LoadPersonaReferences();
//read the persona references.
List<EvidenceReference> personaRefs = person.Person.Evidence;//the person on which to read the discussion references.
PersonState person = ...;
//load the discussion references for the person.
((FamilyTreePersonState)person).LoadDiscussionReferences();
//read the discussion references.
List<DiscussionReference> discussionRefs = person.Person.FindExtensionsOfType<DiscussionReference>();//the person on which to read the notes.
PersonState person = ...;
//load the notes for the person.
person.LoadNotes();
//read the discussion references.
List<Note> notes = person.Person.Notes;//the person for which to read the parents, spouses, children
PersonState person = ...;
PersonChildrenState children = person.ReadChildren(); //read the children
PersonParentsState parents = person.ReadParents(); //read the parents
PersonSpousesState spouses = person.ReadSpouses(); //read the spouses//the person for which to read the ancestry or descendancy
PersonState person = ...;
person.ReadAncestry(); //read the ancestry
person.ReadAncestry(QueryParameter.Generations(8)); //read 8 generations of the ancestry
person.ReadDescendancy(); //read the descendancy
person.ReadDescendancy(QueryParameter.Generations(3)); //read 3 generations of the descendancy//the person for which to read the matches
PersonState person = ...;
PersonMatchResultsState matches = ((FamilyTreePersonState)person).ReadMatches();
//iterate through the matches.
List<Entry> entries = matches.Results.Entries;//the match results
PersonMatchResultsState matches = ...;
//iterate through the matches.
List<Entry> entries = matches.Results.Entries;
matches.AddNonMatch(entries.get[2], FamilySearchOptions.Reason("Because I said so."));//the person to which to add the name, gender, or fact.
PersonState person = ...;
Name name = ...;
person.AddName(name.type(NameType.AlsoKnownAs), FamilySearchOptions.Reason("Because I said so.")); //add name
person.AddFact(new Fact(FactType.Death, "date", "place"), FamilySearchOptions.Reason("Because I said so.")); //add death fact//the person to which to update the name, gender, or fact.
PersonState person = ...;
Name name = person.Name;
name.NameForm.SetFullText("Joanna Smith");
person.UpdateName(name, FamilySearchOptions.Reason("Because I said so.")); //update name
Gender gender = person.Gender;
gender.SetKnownType(GenderType.Female);
person.UpdateGender(gender, FamilySearchOptions.Reason("Because I said so.")); //update gender
Fact death = person.Person.GetFirstFactOfType(FactType.Death);
death.SetDate(new DateInfo().SetOriginal("new date"));
person.UpdateFact(death, FamilySearchOptions.Reason("Because I said so."));FamilySearchFamilyTree ft = ...;
//add a discussion description
DiscussionState discussion = ft.AddDiscussion(new Discussion()
//with a title.
.SetTitle("What about this"),
//with a change message
FamilySearchOptions.Reason("Because I said so.")
);//the person that will be referencing the discussion.
PersonState person = ...;
DiscussionState discussion = ...;
((FamilyTreePersonState)person).AddDiscussionReference(discussion, FamilySearchOptions.Reason("Because I said so."); //reference the discussion//the person to which the photo will be attached.
PersonState person = ...;
DataSource dataSource = ...; // Get a data source
//add an artifact
SourceDescriptionState artifact = person.AddArtifact(new SourceDescription()
//with a title
.SetTitle("Portrait of John Smith"),
dataSource
);Boolean useIntegration = true; //whether to use the integration (previously sandbox) reference.
String username = "...";
String password = "...";
String developerKey = "...";
//read the Family Tree
FamilySearchMemories fsMemories = new FamilySearchMemories(useIntegration)
//and authenticate.
.AuthenticateViaOAuth2Password(username, password, developerKey);FamilySearchMemories fsMemories = ...;
DataSource digitalImage = ...;
//add an artifact
SourceDescriptionState artifact = fsMemories.AddArtifact(new SourceDescription()
//with a title
.SetTitle("Death Certificate for John Smith")
//and a citation
.SetCitation("Citation for the death certificate"),
digitalImage
);//the artifact from which a persona will be extracted.
SourceDescriptionState artifact = ...;
//add the persona
PersonState persona = artifact.AddPersona(new Person()
//named John Smith
.SetName("John Smith"));//the person that will be citing the record, source, or artifact.
PersonState person = ...;
//the persona that was extracted from a record or artifact.
PersonState persona = ...;
//add the persona reference.
person.AddPersonaReference(persona);//the collection to which the artifact is to be added
CollectionState fsMemories = ...;
//the persons to which the photo will be attached.
PersonState person1 = ...;
PersonState person2 = ...;
PersonState person3 = ...;
DataSource digitalImage = ...;
//add an artifact
SourceDescriptionState artifact = fsMemories.AddArtifact(new SourceDescription()
//with a title
.SetTitle("Family of John Smith"),
digitalImage
);
person1.AddMediaReference(artifact); //attach to person1
person2.AddMediaReference(artifact); //attach to person2
person3.AddMediaReference(artifact); //attach to person3