Using FTDNA's API: Commands and Explanations

After hearing from all of you, I am now fairly certain that anyone is, in fact, allowed to access FTDNA's family finder API. And, as a bonus, I learned some new things about how APIs function in websites as well (special thanks for that goes to the anonymous commenter on the previous post). The question that remains is whether or not programmatically accessing it is against FTDNA's terms of use, and if anyone knows anything about that I'd be very happy to hear it, as I can think of a few things I want to try doing with the API and my best friend, python.

Anyways, this new post will go over the ways you can use the API and the different requests you can send to it. It's not all-inclusive and only includes the things I thought were important/most useful.

Please note, this post will include a lot of technical words without a lot of detailed explanation. If you just want to try it out for yourself simply click one of the links in the post to see the match data after signing into ftdna in your web browser.

How to Send GET Requests (In General)

There are two ways you can send Requests. The first is to just put the URL in your browser and the 2nd is to use Postman. For the most part, I use because making requests in it is faster and its easier to change parameters, however, I will use my browser in this tutorial because that will make it easier to collapse things/ limit the amount of censoring I have to do.

Match Lists

Basic Match List

The JSON Data for the Basic Match List

To return the information for your first 9 matches in JSON format (the same number as you would normally see on the screen) Use the following url:

https://www.familytreedna.com/my/family-finder-api/matches?

Full Match List

You'll notice that the first line of JSON data returned by the last command has the total count of matches you have. You can use this number or any number larger than it in the url to print out that number of matches. In the url set page=1 (to start on your first page of matches) and set pageSize=numberofmatches. Here is an example url:

https://www.familytreedna.com/my/family-finder-api/matches?page=1&pageSize=4000

Using FTDNA's API

Edit 1 5/11/2018: Note that this does not mean anything bad for you at all and you can continue using ftdna as normal, it's a fantastic site. Also, there is a possibility that the information I was sent regarding who was supposed to be able to use the API could have been incorrect, see the comments section for an interesting discussion on that. I think that the big takeaway from this post should be if you want to use the API for your company it is worth checking in with ftdna to ensure you have permission to do so.

Edit 2 5/11/2018: I have been looking into it more, and I believe that this is not in fact an issue at all which I am very happy about. I am still confused about why ftdna told me otherwise, and it may be that you are technically still not supposed to use it, but I'm really not sure at this time. Special thanks to the anonymous commenter for clearing things up!

Note: I actually wrote this all the way back on March 12th. I had notified FTDNA of the fact that their API was accessible by the public even before that. I am publishing this now because I feel it is my right/duty. They made the decision not to fix it or notify the public that they can use the API, so I think that somebody should. I'm hoping that this post will perhaps raise awareness about this and make FTDNA make a definitive choice about whether they want their API to be publicly available (which I personally think would be fantastic).

Purpose

This document will serve to explain the process through which I found a security vulnerability in the FTDNA web API, as well as the process I went through in reporting said vulnerability and what I would have done differently if given the chance.

Definitions

Some company names and terms used in this document will undoubtedly be unfamiliar to those reading it. This section will serve to clarify said terms.

A Comparison of FTDNA and MyHeritage Results Between Grandchild and Grandparents

The real value of DNA testing lies in the matches. DNA has done so many spectacular things for me, from solving a case of false parentage to revealing new photos of my relatives. However, one can not deny the novelty that comes with the ethnicity results.

It's important to remember that ethnicity results are not everything, and definitely not 100% accurate. They are usually fairly accurate on the continental level, but it's hard to distinguish Swedish from English, for instance. However, I thought it might be interesting to compare the ethnicity percentages yielded by different companies. I have tested myself, all four of my grandparents, and some great uncles and aunts. This post will compare not only ethnicity but also match counts.

My FTDNA Results

Main Ethnicities

My FTDNA Main Ethnicity Results