Getting Started With The Free Linkscape API

When they released Open Site Explorer, SEOmoz gave SEOs a powerful, free tool upon which many now rely.  But did you know that all SEOmoz members have access to the just-as-free and perhaps powerfuller Linkscape API?  This API uses the same data set as OSE, but you can use it to make large numbers of queries which might be cumbersome with OSE.

Linkscape is a web based API.  Your query looks like a URL, and requesting that URL will return the data you need.  We mention the API from time to time on the Distilled blog.  Will Critchlow wrote a post a while back with a bash script that accessed Linkscape data.  What I want to do here, though, is just take you from zero to fifty-five in a few easy steps.

There are, of course, many query types to choose from.  I'm going to focus on the url-metrics portion of the API because it is relatively straightforward and knowing how to use it to automate requests.  This is the type of query that will allow you to enter a URL and get stats like Domain Authority, Page Authority, mozRank, et cetera.  So to get started...

0. ...sign up for an SEOmoz account!

This is step 0 because if you're reading this blog, there's a good chance you've got an SEOmoz account already.  But sign up if you don't and you want to play with Linkscape.

1. Get your free Linkscape API credentials!

Once you've got an SEOmoz account, it couldn't be easier to get your API credentials.  Everything you need is right on the Linkscape API home page.  Also note (if you're being super-thorough and reading every detail on that page) that the API actually uses HTTP Basic Authentication now, so there won't be any timestamps or hasherry involved.

What you need to get from this process is an Access ID and a Secret Key.  You can't miss them; they're prominently featured on the page.

2. Form your first query!

As I mentioned above, queries to Linkscape will look like URLs.  This is what that URL looks like for accessing url-metrics:

Naturally, you will need to replace ID and KEY above with your Access ID and Secret Key.  If you enter this into your browser's address bar your should see the following JSON string output:

{"fmrp":0,"fmrr":5.376863065430114e-15,"pda":64.59381022404928,"ueid":2, "ufq":"","uid":2,"umrp":0,"umrr":1.525682808100888e-15, "upa":1,"upl":"","us":0,"ut":"","uu":""}

Ah... Ha!  That's a lot of letters and numbers.  What's happening is that each of these pairs has a label and a value.  The labels are short abreviations which tell you what the data is.  These are followed by numbers or strings which have the relevant information.  The label "uu", for instance (the last label above), marks the standardized URL the 'moz is using.  The Linkscape API has a full reference for these values.  Some more interesting values above would be "pda" and "upa" which indicate Domain Authority and Page Authority respectively.

3. Set your bit flags flyin'!

Bit fields are a convenient (and somewhat obfuscatory) way of setting bit flags, which is how we tell Linkscape what data we want returned.  Suffice it to say, you can take advantage of them to filter the values returned by Linkscape.  The way it works is that each field (URL, Title, DA, PA, mozRank, et cetera) has a number associated with it.  These numbers can be found on the Linkscape wiki.  By adding these numbers together, Linkscape will know that you want just the fields whose numbers you've added.  That might not make a lot of sense, so... example: say I only want to return the Title and URL in my request.  The number associated with Title is 1, the number associated with URL is 4.  Together that's 5.  My query is:

And lo!  I see the title and URL returned.

Of course, that isn't a particularly exciting query.  How about this one, instead, which returns only the Domain Authority associate with any URL you enter:

In some cases, limiting your requests to returning one value can significantly simplify processing the resulting JSON.

4. Sail into the sunset!

You may feel I've left you hanging; you've got a JSON string, now what?!  The thing is, you can do so much with it!  I really can't say what will be most useful for you.  Import it into Google Docs (perhaps with the help of some app script wizardry provided by user Ahab), create a Python script to automate the process and spit out a CSV file (my personal favorite), or draw this information automatically for client reporting.  Only you can say.

Have fun, read the Linkscape wiki, and let us know if you've got any ingenous ways of using this data.  Hope you've enjoyed the primer!

P.S.  Remember, with great power comes great responsibility.  Use of the Linkscape API is governed by an agreement to provide proper attribution to SEOmoz.  Basically this amounts to calling Domain Authority "Domain Authority" and mozRank "mozRank".  But be sure to read the details just in case!

Get blog posts via email

About the author
Benjamin Estes

Benjamin Estes

Ben is a Principal Consultant who joined Distilled in 2010. Now he focuses on leveling up our team. Through group training and internal consultation, he guides team members as they effect change for our clients.   read more