Modern Software Experience

2010-12-15

Introduction to the Geni API

  1. The Geni API
  2. The Geni Model

relationships


<nuclear-family-no-merges> 
  <focus> 
    <url>https://www.geni.com/api/profile-focus</url> 
    <id>profile-focus</id> 
  </focus> 

  <nodes> 
    <union-parentsfamily> 
      <edges> 
        <profile-focus> 
          <rel>child</rel> 
        </profile-focus> 
        <profile-sister> 
          <rel>child</rel> 
        </profile-sister> 
        <profile-brother> 
          <rel>child</rel> 
        </profile-brother> 
        <profile-father> 
          <rel>partner</rel> 
        </profile-father> 
        <profile-mother> 
          <rel>partner</rel> 
        </profile-mother> 
      </edges> 
    </union-parentsfamily> 
     
    <profile-focus> 
      <edges> 
        <union-parentsfamily> 
          <rel>child</rel> 
        </union-parentsfamily> 
        <union-focusfamily> 
          <rel>partner</rel> 
        </union-focusfamily> 
      </edges> 
     ...
      <url>https://www.geni.com/api/profile-focus</url> 
      <id>profile-focus</id>
    </profile-focus> 

    <profile-spouse> 
      <edges> 
        <union-focusfamily> 
          <rel>partner</rel> 
        </union-focusfamily> 
      </edges> 
     ...
      <url>https://www.geni.com/api/profile-spouse</url> 
      <id>profile-spouse</id> 
    </profile-spouse> 

    <profile-sister> 
      <edges> 
        <union-parentsfamily> 
          <rel>child</rel> 
        </union-parentsfamily> 
      </edges> 
     ...
      <url>https://www.geni.com/api/profile-sister</url> 
    </profile-sister> 

    <profile-daughter> 
      <edges> 
        <union-focusfamily> 
          <rel>child</rel> 
        </union-focusfamily> 
      </edges> 
      ...
      <url>https://www.geni.com/api/profile-daughter</url> 
      <id>profile-daughter</id> 
    </profile-daughter> 

    <profile-brother> 
      <edges> 
        <union-parentsfamily> 
          <rel>child</rel> 
        </union-parentsfamily> 
      </edges> 
      ...
      <url>https://www.geni.com/api/profile-brother</url> 
      <id>profile-brother</id> 
    </profile-brother> 

    <union-focusfamily> 
      <edges> 
        <profile-focus> 
          <rel>partner</rel> 
        </profile-focus> 
        <profile-spouse> 
          <rel>partner</rel> 
        </profile-spouse> 
        <profile-daughter> 
          <rel>child</rel> 
        </profile-daughter> 
        <profile-son> 
          <rel>child</rel> 
        </profile-son> 
      </edges> 
    </union-focusfamily> 

    <profile-father> 
      <edges> 
        <union-parentsfamily> 
          <rel>partner</rel> 
        </union-parentsfamily> 
      </edges> 
      ...
      <url>https://www.geni.com/api/profile-father</url> 
      <id>profile-father</id> 
    </profile-father> 

    <profile-mother> 
      <edges> 
        <union-parentsfamily> 
          <rel>partner</rel> 
        </union-parentsfamily> 
      </edges> 
      ...
      <url>https://www.geni.com/api/profile-mother</url> 
      <id>profile-mother</id> 
    </profile-mother> 

    <profile-son> 
      <edges> 
        <union-focusfamily> 
          <rel>child</rel> 
        </union-focusfamily> 
      </edges> 
      ....
      <url>https://www.geni.com/api/profile-son</url> 
      <id>profile-son</id> 
    </profile-son> 

  </nodes> 
</nuclear-family-no-merges> 

navigating the tree

If you have your immediate family on Geni.com, https://​­www.geni.com/​­api/​­profile/​­immediate-family should return all of them; parents, spouses and children.
To find your grandfather on your mother's side, ask for your immediate family, find your mother in the results, and using her identifier, ask for her immediate family. If your mother's profile identifier is 1234567, you'd ask for https://​­www.geni.com/​­api/​­profile-1234567/​­immediate-family. Find her father in the results, and you know have the identifier of your grandfather.
This is how you navigate through a family tree; from one profile to the next. You ask for the immediate family, choose one of them as the new focus person and ask for the immediate family again.

relationships

The trick in navigating through the Geni.com tree isn't making the URLs. It is interpreting the relationships. The immediate-family result set starts with the profile for the focus person, and then list the surrounding profiles.
However, Geni.com does not only return a bunch of profiles, it also returnes the relationships between those profiles. When you first see nodes, union-12345678, edges and rel, your eyes may glaze over, especially when you see that the link to your mother is labelled partner, and the link to your brother is labeled child. What's more, this bit isn't documented at all, at least not yet.

Geni.com data model

You might think that Geni.com's data model consists of profiles linked together by relationships. However, Geni.com is closely modelled on GEDCOM, and GEDCOM does not support direct relationships between persons. GEDCOM places the nuclear family at the centre of its data model; people aren't related to each other, instead they are part of some nuclear family. That is how it is in GEDCOM, and that is how it is Geni.com. In Geni.com, the nuclear family is known as a union. The role each member plays in that family is known as a relationship, and Geni.com abbreviates that to rel. Each union has a number of links to other profiles. Together, these links are known as the edges of the union. Within the collection of links, each link has relationship (rel) attribute to indicate the type of relationship, and there are only two types: a profile is either a partner in the union, or a child of the union.

So, to find the mother of the focus person, you find the union in which the focus person is listed a child. That union has two partners, one is male and one is female. The female one is the mother.

immediate-family result set

The illustration is a schematic representation of the immediate-family.xml result set. All detail has been left out, so we can focus on the structure.
In real immediate-family.xml results sets, the union and profile identifiers do not have helpful names such as union-focusfamily and profile-father. They have names like union-12345678 and profile-12345678, and contain many attributes for each profile record.

This illustration shows a schematic result set for a focus person with one father, one mother, one brother, one sister, one son and one daughter. The entire result set is contained in the nuclear-family-no-merges tag.

nodes

The nuclear-family-no-merges tag contains just two things; the focus tag containing the focus person and the nodes tag. The nodes tag contains all the profiles that make up the immediate family, including the focus person itself again.

two families

The nodes collection contains  two nuclear families two numbered union records; union-parentsfamily is the family the focus person is child in, and union-focusfamily is the family they started themselves. The two children are part of the union-focusfamily, the brother and sister are part of union-parentsfamily.

The result set starts with union-parentsfamily, followed by the profiles referenced in this union; profile-father, profile-mother, profile-focus, profile-brother, profile-sister.
It then continues with union-focusfamily, followed by the profiles that referenced in this union: profile-focus, profile-spouse, profile-son, profile-daughter.
This particular order is merely the order that Geni.com happens to be using right now. The result set is not garantueed to be in any particular order. You should navigate the result set using the links between the profile and union records.   

Each union (nuclear family) contains edges; In a union the edges collection is a list of profile records that are part of that union and their role in (relationship to, rel) to that union: partner or child.

Each profile contains an edges collection as well. In a profile, the edges collection is a list of union records (nuclear families) the profile is part of, and its role in that particular union: partner or child.

Each links back to the all unions it is part of. In this ilustration, the focus person links back to union-parentsfamily as a child, and links back to union-focusfamily as a partner.

conclusion

Once you understand this model, you can navigate from one Geni.com profile to the next using the Geni.com API. What attributes each profile contains and what other functions are available is documented on the Geni developer pages.