2010-12-15 The Geni API

Introduction to the Geni API

Geni.com for developers

You do not need to write an application to start experimenting with the Geni API. You only need a web browser, and to be registered and logged in as a Geni.com user.

Geni API

According to the main Geni developer page, Geni released the Geni API to empower developers to create new applications for our rich dataset. There currently isn't much documentation, and there is only one example program, written in Ruby. No surprise the, that the documentation is still incomplete, but there is just enough to get started developing your own Geni application.

registration

However, even if you already knew everything there is to know about the Geni API, you still could not use it in your application. The documentation is public, but before you can develop and use your own client application to access the Geni.com database, you'll have to register your application.

Geni API: register application

The screenshot shows the three items you need to provide: an application name, the main URL of your application and a callback URL. Notice that all three items are mandatory. The application name field needs no explanation. The main URL is simply your application's home page, the callback URL is the address that Geni will direct users to after authorisation.
A callback URL makes perfect sense for a web app, but not for a desktop app. It is a mandatory field, so it seems the Geni API is limited to web apps. However, that is not the case. Developers of desktop apps can put anything they like in that field.

authorisation

Authorisation is done through OAuth, the same authorisation protocol that Twitter uses. The Geni API does not use OAuth 1.0, but already uses OAuth 2.0, which is still under development. Using a standard before it finished seems premature, but FaceBook is already using OAuth 2.0 as well.
Geni's use of OAuth 2.0 explains why developers of desktop application can put anything in the callback field. OAuth 2.0 has different authorisation flows for web apps and desktop apps. Geni.com needs the callback address for a webapp, but will never use it for a desktop app.

interface

The Geni API is a web API, all interfaces are URLs. For example, the URL https://www.geni.com/api/profile returns profile data. Notice that the protocol isn't http:// but https://; the Geni API uses Secure HTTP.

You do not need to write an application to start experimenting with the Geni API. You only need a web browser, and to be registered and logged in as a Geni.com user. You can type that URL in your browser's address bar, and the browser will display Geni.com's reply as plain text.

Geni API: profile

The screenshot shows what that looks like. I modified a few values to focus on the format instead of the content.

The return value is a list of key-value pairs, separated by commas. For example, the first key is last_name, and its value is Jones. The second key is big_tree, and its value is false; this means that my profile has not been assimilated into the Borg Tree. The user id is https://www.geni.com/api/profile-1234567, and this profile has been created_by https://www.geni.com/api/profile-1234567 too; I created my own profile, and my user id is 1234567. If you were to ask for your own profile by id, by entering https://www.geni.com/api/profile-123456 in the address bar instead of https://www.geni.com/api/profile, you would get exactly the same response. You can query any Geni.com profile this way - provided that you have access to that profile.

Geni API: Access Denied

When you do not have access, the result of your API request is an Access Denied error.

restrictions

The Geni API does not provide unlimited access to all of Geni.com. Accessing Geni.com through the Geni API does not bypass its access controls. The usual access restrictions apply, and yes, that means that Geni Pro users can access more than regular Geni Basic user. Use of the Geni API is subject to the same terms and conditions as use of the Geni web site. There's a rate limit as well; the initial rate limit is 40 requests every 10 seconds.

The Geni API supports both JSON and XML.

JSON and XML

The output format returned by the Geni API is JavaScript Object Notation (JSON). The list of key-value pairs is known as a JSON array, a JSON associative array to be precise. Some programmers call it a JSON hash, which is odd, because it isn't a hash table. It is a text-based format, and that everything is on one line that just runs on and on. For the small results shown here and for incidental usage, that isn't a big problem, but if you frequently look at JSON results, you may to install a JSON browser extension that shows the results in a more readable layout.

The JSON format is becoming quite popular with web applications, but it isn't the only format the Geni API supports. The Geni API supports both JSON and XML. The documented Geni API returns JSON, to get XML instead, you need to append .xml to the base URL.

Geni API: Profile XML

That result may not look like XML, but that is only because the browser understands XML, and defaults to displaying it as if it was plain text. To see the XML, choose to view the source.

Geni API: Profile XML: Source

RESTfull

The Geni API is a largely RESTfull API, which is technical way of saying that it very much works like any web server. Everything is done with URLs. That it why it easy to experiment with the Geni API in a browser.

Every profile on Geni.com web site is identified by an unique URL; each profile has a number, and the URL of that profile is https://www.geni.com/api/profile-number. If you leave the number of, and just ask for https://www.geni.com/api/profile, you get your own profile.

linked

Profiles are linked to other profiles. Each Geni.com profile not only has properties such as birth_date, each profile also has a creator and one or more managers. These are generally links to other profiles, so that is one way to start navigating through Geni.com profiles. There are just two problems with that; you typically are both the creator and only manager of your own profile and you probably do not visit Geni.com to follow creator or manager links. You want to follow genealogical links.

The https://www.geni.com/api/profile-1234567/tree-matches URL returns the tree matches for profile 1234567. However, tree matches are a Geni Pro feature. If you are Geni Basic user, you'll receive the error Pro Subscription required.

Geni API: Pro Subscription required

conclusion

That's it really. It is that simple. You now know how to use the Geni API from the, ahem, comfort of your browser. Well, there still is the little matter of how navigate from one profile to the next.

updates

2010-12-15 instant update: Geni announcement

Geni.com has announced the Geni API on their blog. This includes the information that Geni has started The Geni API project that you can choose to follow or join.

2010-12-17: early use

The Geni.com blog post Geni API Feedback is about early use of the API to automate merging of identical profiles. The merging tool mentioned, but not identified, is geni-automerge, a Perl script by Daniel Walton and Erin Spiceland.

2011-02-10 API expansion

The Geni API has been expanded with calls for handling documents and photos.

2011-02-11 Traces of the Past

Traces of the Past 2.0, an iPhone app that started out as an app for NFS, now supports Geni.com through the Geni API.

2011-03-18 Traces discontinued

TrueScape Solutions has discontinued Traces of the Past.

2011-04-06 Progeny Charting Companion

Progeny has used the Geni API to create a Geni.com edition of the Progeny Charting Companion.

2011-04-11: Tpstry

The Tpstry site announced support for GEDCOM and the Geni API.