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:

http://ID:KEY@lsapi.seomoz.com/linkscape/url-metrics/distilled.net

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”:“distilled.net/”,“uid”:2,“umrp”:0,“umrr”:1.525682808100888e-15, “upa”:1,“upl”:“distilled.net/”,“us”:0,“ut”:“”,“uu”:“distilled.net/”}

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...

...an 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:

http://ID:KEY@lsapi.seomoz.com/linkscape/url-metrics/distilled.net?Cols=5

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:

http://ID:KEY@lsapi.seomoz.com/linkscape/url-metrics/distilled.net?Cols=68719476736

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!

Benjamin Estes

Benjamin Estes

Benjamin is a senior consultant who joined Distilled in 2010. Having earned a BA in Mass Media, his intention is to continue studying the ways in which people interact with media and apply those lessons to his consulting. Ben-h264 // Born and...   read more

Get blog posts via email

8 Comments

  1. Would this work with the magical Yahoo Pipes? I haven't had an excuse to use one for ages...

    reply >
    • Benjamin Estes

      I hadn't thought about that one. Yeah, there should be no problem using this as the output is JSON and I believe there are bits in place to handle Basic Authentication.

      Good spot!

  2. This is excellent stuff! Great post Ben.

    reply >
  3. Great post, thanks!

    Had been thinking about making use of the API for a while, but as often is the case, kept talking myself out of it because I imagined it would be beyond me to set it up without help from our techs.

    Having read your post I do believe this little black duck actually gets it!

    A whole new world is opening up before me :-)

    reply >
  4. iPullRank

    FYI, If you are coding in PHP json_decode will be your best friend for this.

    reply >
  5. Just another piece of great advice of Ben how to be building authority on your present social followers. Haven´t been thinking about this great connection with SEO Moz data yet. Thx for the advice. I´ll have a try asap.

    reply >
  6. Interesting article - Thanks for the info!

    reply >
  7. Rory

    I've just tried step one but all I get back is {} - any pointers where I might be going wrong?

    reply >

Leave a Reply

Your email address will not be published. Required fields are marked *

*
*

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>