Memories

The FamilySearch Memories resource is used to manage a user's "memories" of persons in their family Tree, such as photos, stories, documents and audio files. The Memories API is used to upload, annotate, and organize memories and to attach those memories to persons in the FamilySearch Family Tree. For an overview of "memories" data objects in the Family Tree, see The Family Tree Data Model.

A memory is a container for user-contributed artifacts, such as photos, stories, documents and audio. Although a memory typically contains a single artifact, occasionally a memory may contain more than one artifact. Multi-artifact memories are currently not in use. Use cases for a memory that contains multiple artifacts include the front and back of a photograph, the multiple images required to capture a panoramic photo, and a multi-page document, such as a will, probate administration, or a military pension record.

Each memory artifact has an associated source description that contains metadata for the artifact, such as a title, a created timestamp, links, references, and any extracted information, specifically personas. Personas are used to capture information about a single person from the memory, such as a tag on a photo or a mention in a document. Each persona contains a reference to the artifact from which it was extracted. Each artifact reference on the persona may contain qualifiers to describe the tagging coordinates on the artifact.

There are defaults for the artifact type. If left unspecified, an image file will be uploaded as a photo, a .pdf as a document, an audio as a story, and text as a story. If you want the image of your grandparents' marriage certificate to show up in the documents bucket of memories, you would need to set the type (artifact type) to “document” rather than let it default to “photo”. That is the only difference, and the example shows that the type is set to “document”.

A persona references a single artifact. It represents a "sighting" of a person within an artifact. When you create a persona, the ID of the Tree person should be provided in order to attach it to the Tree. In the case of image artifacts, the persona contains a tag that defines the rectangular region where the person appears in the image. Some images may contain multiple appearances of a person (e.g., a collage). The persona represents this using multiple tag objects, one for each appearance. If the region of the image where a person appears is not known or defined, a default tag will be created that includes the entire image. Also note that tags should be placed around the faces of people and are used to generate a list of potential portraits. Square tags are recommended to accommodate applications that use circular regions for portraits, such as the FamilySearch Family Tree.

Persons in the Family Tree may contain multiple references to memory personas. These references are used to "attach" memories to a Tree person when the persona is created.

A memory can be added in two steps or in one combined request.

Upload the memory (not attached to a person in the tree)
Tag the photo, for a specific person or persons, and provide the ID of the Tree person, if available.

To protect FamilySearch and all users of the system, uploaded images are subject to approval. The review process ensures that there is no pornography, copyright infringement, immodest clothing (including bathing suits), and no violence (blood, mutilation, gore). Until images are approved, only the current user will be able to see them. Other users will get a 403 Forbidden error.

Memories Date and Location

A Memory can be provided with a date and/or a location to which the photo, document, or story is applicable. The date and place of a memory is referred to as the "coverage" of the memory and is provided via the description of the memory using the coverage property. The coverage property describes the temporal (date) coverage and the spatial (place) coverage of the memory.

While the FamilySearch Family Tree uses the original, normalized, and formal parts of the date, currently FamilySearch Memories only uses the normalized text of the date as temporal coverage. To obtain the normalize text of a date, use the Date resource

While the FamilySearch Family Tree uses the original and normalized parts of the place, FamilySearch Memories uses the original place text as well as the description reference of the place for spatial coverage.

Examples

To create a memory by uploading a photo, story or document, use the Memories resource.
To read, update, or delete a memory, use the Memory resource.
To read, update or create personas on a memory, use the Memory Personas resource.
To delete a persona on a memory, use the Memory Persona resource.
To create or read the references from a Tree person to memory personas, use the Person Memory References resource.
To get a paged list of all memories linked to a person, use the Person Memories resource.
To get a paged list of all memories contributed by a particular user, use the User Memories resource.
To create or read a comment on a memory, use the Memory Comments resource.
To delete a comment a user has made on a memory, use the Memory Comment resource.
To upload a memory directly to a Tree person, use the Person Memories resource.
To upload an audio file attached to the Tree, use the Person Memories resource.
To upload an audio file not attached to the Tree, use the Memories resource.
To get a thumbnail-sized portrait for a Tree person, use the Person Memories Portrait resource.
To get a list of portrait descriptions for a Tree person, use the Person Portraits resource.