Mozscape API Application Tutorial

January 22, 2013

Behind SEOmoz’s popular Open Site Explorer is a breadth of metric-defining data. The engineers at SEOmoz have coalesced and interpreted this data, forming well known metrics, like Page Authority and Domain Authority, and delivering meaningful counts, like External Followed Links. As SEOs, we use these metrics almost daily, accessing them via OSE, the SEOmoz toolbar, and third party applications (like HubSpot).

mozscape api

In this tutorial, we’ll examine the practice of accessing SEOmoz metrics via your own applications, making use of the free version of the Mozscape API and the provided PHP Signed Authentication Example. Prior programming experience isn’t a must, but it certainly won’t hurt. All you’ll need to complete this tutorial is an SEOmoz account, a text editor (we use Sublime Text 2 in this tutorial), and a web server (for testing your application). If you don’t have access to a hosting account, you can set up a local web server using XAMPP (Windows) or MAMP (Mac).

This step-by-step walkthrough will help you understand the intricacies of our example application. We encourage you to reference the below PHP file as you read through each step. Let’s do this.

<?php

// you can obtain you access id and secret key here: http://www.seomoz.org/api/keys
$accessID = "ACCESS_ID_HERE"; // * Add unique Access ID
$secretKey = "SECRET_KEY_HERE"; // * Add unique Secret Key
 
// Set your expires for several minutes into the future.
// Values excessively far in the future will not be honored by the Mozscape API.
$expires = time() + 300;
 
// A new linefeed is necessary between your AccessID and Expires.
$stringToSign = $accessID."\n".$expires;
 
// Get the "raw" or binary output of the hmac hash.
$binarySignature = hash_hmac('sha1', $stringToSign, $secretKey, true);
 
// We need to base64-encode it and then url-encode that.
$urlSafeSignature = urlencode(base64_encode($binarySignature));
 
// This is the URL that we want link metrics for.
$objectURL = $_POST['url'];
 
// Add up all the bit flags you want returned.
// Learn more here: http://apiwiki.seomoz.org/categories/api-reference
$cols = "103079215140";
 
// Now put your entire request together.
// This example uses the Mozscape URL Metrics API.
$requestUrl = "http://lsapi.seomoz.com/linkscape/url-metrics/".urlencode($objectURL)."?Cols=".$cols."&AccessID=".$accessID."&Expires=".$expires."&Signature=".$urlSafeSignature;
 
// We can easily use Curl to send off our request.
$options = array(
    CURLOPT_RETURNTRANSFER => true
    );
 
$ch = curl_init($requestUrl);
curl_setopt_array($ch, $options);
$content = curl_exec($ch);
curl_close($ch);
 
// * Store URL metrics in array

$json_a = json_decode($content);

// * Assign URL metrics to separate variables

$pageAuthority = round($json_a->upa,0); // * Use the round() function to return integer
$domainAuthority = round($json_a->pda,0);
$externalLinks = $json_a->ueid;
$theUrl = $json_a->uu;
 
?>

<html>
	<head>
		<title>Mozscape API Application Example</title>
	</head>
	<body>
		<h1>Mozscape API Application Example</h1>
		<form method="post" action="/example-app.php">
			<label for="url">Enter URL:</label><input type="url" name="url" id="url"/>
			<input type="submit" value="Get URL Metrics!"/>
		</form>
		<ul>
			<li><strong>URL:</strong> <?php echo $theUrl; ?></li>
			<li><strong>Page Authority:</strong> <?php echo $pageAuthority; ?></li>
			<li><strong>Domain Authority:</strong> <?php echo $domainAuthority; ?></li>
			<li><strong>External Links:</strong> <?php echo $externalLinks; ?></li>
		</ul>
	</body>
</html>

1. Generate your API credentials

In order to access the Mozscape API, you’ll need to generate a unique set of API credentials. Don’t fret; this is pretty simple. First, sign into your SEOmoz account (or, if you don’t have one, create one) and navigate to the ‘Get Started with the Mozscape API’ page. Follow the steps to generate your unique Secret Key. Once you’ve done this, you should see a nice green box with both your API Access ID and new Secret Key. Keep this tab open, as you’ll be using your credentials shortly.

2. Copy the PHP Signed Authentication Example to your text editor

Provided with the Mozscape API documentation are a number of code examples. As we’ll be using PHP to build our simple application, we’ll make use of the PHP Signed Authentication Example. Using this code as a starting point will make understanding our API calls a more feasible task.

php signed authentication example

Select all of the code provided in the Signed Authentication Example and copy it to your clipboard. Open a new file in your text editor and paste in the code. Save the file as ‘example-app.php’. It’s time to start constructing your API calls!

3. Get started with your PHP file

Since the example code omits the opening tag for PHP, we’ll start by adding it to our file. Above the first example line, include the opening tag:

php example

Note that the characters ‘//‘ denote a single line comment in PHP. In the screenshots we provide throughout this tutorial, instruction comments are preceded by an asterisk (*) — like ‘// * Add opening tag‘ above. Speaking of comments, you can learn quite a bit from the comments that SEOmoz has provided in their example code. Now is a good time to peruse these comments and get a feel for what the code does.

After you’ve had a chance to look over the code, return to the top of your file. Remember the API credentials you generated just a bit ago? It’s time to put these to use. We’re provided with a variable for each of our credentials, $accessID and $secretKey. (PHP variables always begin with the dollar sign.) Copy and paste your credentials in place of the respective sample text (i.e., ACCESS_ID_HERE). Be sure to preserve the quotation marks surrounding the variable values.

assign api credentials

Once you’ve entered your credentials, you have yourself a PHP file that, when uploaded to your web server and requested, will make a Mozscape API call. However, the format of the information returned won’t be particularly useful, and, furthermore, you’ll have to edit the file itself every time you want information about a different URL. Not to mention, you might want to specify which URL metrics your application should fetch, rather than retrieving just those defined in the example code (URL, Page Authority and Domain Authority).

4. Define URL metrics to be requested

In this tutorial, we’ll be making use of the URL Metrics API (given that our example code does the same). In the API documentation for URL Metrics, we see that, “by default, the response to a URL Metrics call includes all response fields available to your account, except Domain and Page Authority, which need to be explicitly requested.” Since we know that both Domain and Page Authority are being requested (as our example request is constructed), we can infer that some facet of our code is responsible for the explicit requests.

define url metrics requested

In fact, the $cols variable in the screenshot above does just that — its value determines which URL metrics are requested and returned. By summing the Bit Flags of metrics available in the free URL Metrics API and assigning this sum to the $cols variable, we can specify which metrics we’d like to request. You can read more about Bit Flags in the documentation linked above. Bit Flags and Response Fields (we’ll get to this) for specific URL Metrics are specified in that documentation, as well.

url metrics

Above, in the second column, we see the Bit Flag values for the Page and Domain Authority URL metrics. When we sum these values (34359738368 + 68719476736), we get 103079215104. After adding the URL Bit Flag (4), we have 103079215108. If you look at the screenshot with the $cols variable, you’ll notice that $cols‘ value is exactly that. So, as our code stands, we’re requesting the URL itself, Page Authority, and Domain Authority. Pretty cool, right?

external links

Let’s add another metric to our call: External Links. In the Bit Flag column of the External Links row, shown in the screenshot above, we see a value of 32. We add this 32 to our current total (103079215108) to get 103079215140. In your code, insert this new value in place of the old $cols value.

insert new total

If you’re working on a local web server, you can refresh the file in your browser to see the additional metric returned. Still no formatting, though. First, we have to make the information returned easy to use within our application.

5. Organize the metrics returned

Rather than printing the requested URL metrics in their ugly return format, we want to use them in a way that makes sense to our application’s users. The first step in this process is to assign each returned metric to its own unique variable. This way, metrics are easily accessible within our code.

outputting requested information

If you scroll down to the bottom of your PHP file, you’ll see that the print_r() function is being used to output the requested information. While print_r() is useful for displaying the URL metrics in the browser, it isn’t particularly helpful when it comes to segmenting the individual metrics. For this, we’ll make use of the json_decode() function — a function that, given a JSON encoded string (which the Mozscape API does indeed return), will convert that string into a PHP variable. In the case of our example, a PHP array. You can think of an array as an organized list of values (i.e., our requested URL metrics). We won’t go into too much detail about these functions, but if you care to, you can read more on json_decode() and PHP arrays.

using json_decode

For now, supplant the print_r($content); line with the $json_a = json_decode($content); line shown in the screenshot above. (Note that each line of PHP ends with a semi-colon.) Now we have an associative array that will hold the values of each of the URL metrics returned. We can assign these array values to separate variables using the keys that SEOmoz provides in the URL Metrics documentation. Keys for each metric can be found in the Response Field column of the metric table.

url metrics response fields

The keys for the metrics we’re requesting — Page Authority, Domain Authority, External Links, and URL — are upa, pda, ueid, and uu, respectively. Let’s use these keys to access our array values and store them in new variables. We can do this via the array->key syntax.

Assign Metrics to Variables

The code in the screenshot above accomplishes just what we’re looking to do, assigning URL metrics in our PHP array to their own separate variables. Notice that we’ve made use of the round() function to limit our Page and Domain Authority values to integers. (By default, they’re returned as decimal values.) The second argument in round($argument1,$argument2) (in this case, a 0) indicates to how many decimal places the function will round our values. If you’d like to get a little more granular and see numbers with, let’s say, two decimal places, you can change this argument to 2.

6. Display the URL metrics in the browser

Now that we can readily access the returned URL metrics using our newly defined variables, we want to make it easy for users to read the metrics returned. We can do this by partnering our PHP with a little HTML. We’ll be making use of the PHP echo construct and an HTML unordered list to display the URL metrics in the user’s browser. We can start our HTML structure below the PHP we’ve already written (right after the closing PHP tag).

displaying url metrics to the browser

In the screenshot above, we’ve structured our application’s HTML and created a list item for each URL metric (with the metric name bolded). We’ve used inline PHP to output the values of our URL metric variables within the appropriate list items. (Notice that the inline PHP starts and ends with the same opening and closing tags and includes the semi-colon at lines’ end.) At this juncture, you should have a functioning application that displays Mozscape metrics for the requested URL. Re-upload the PHP file to your server and/or refresh your browser to see the results thus far.

Mozscape Application Thus Far

Not too shabby, eh? We’ve come a long way. Now it’s time to make your application a bit more dynamic.

7. Accept users’ URL inputs

As it stands, our simple application works, but it isn’t incredibly useful. In the example code provided, the object URL — or the URL that we want link metrics for — is set to ‘www.seomoz.org’ (a static value). With a static object URL, we get static results. Each time we refresh our browser, we request the same link metrics for the same URL. Seems boring, doesn’t it? We want users to interact with our application, not just use it once and be on their way.

Here’s a thought: We allow users to choose the URL for which they want Mozscape link metrics. That seems a bit more useful, and it only takes a couple of steps to implement. We’ll need an HTML form to process the user’s URL input and some PHP to accept that input and set the $objectURL equal to it. Let’s start with the form.

Process Users' Input

The form itself is fairly straightforward. We’ve provided users with a URL field and a submit button so that they can request metrics for specific URLs. We’ve set the form method to ‘post’ and the action to ‘/example-app.php’, as we’ll be processing the input using the same PHP file. If you’ve uploaded your file at the root level and used the same file name, this should work properly. If not, simply set the action attribute equal to the location of the file (or the URL at which the file can be accessed on your web server).

Now, let’s move along to accepting the user’s input with PHP.

Accepting User Input

When a user submits our application’s form to the PHP file on which it resides, we want to set that input equal to our $objectURL variable (which, in the example code, is set to ‘www.seomoz.org’). To do this, we make use of the PHP $_POST variable and the name attribute we set for our URL input (‘url’). $_POST collects all of the input values submitted with our form, and [‘url’] specifies which of those values we’d like to access. Just like that, we’ve accomplished our goal of allowing users to input their own URLs.

URL Metrics for Google

In the screenshot above, we’ve used our application to fetch URL metrics for Google.com. Nearly 50 million external links say that we’ve constructed a functioning test application using the Mozscape API! Woohoo!

8. Refine, expand, attribute, and launch!

Now that you have an example application up and running, the ball is in your court. Think of ways that you can augment tools like OSE by expanding upon your current application. Add some styling to make it look pretty. Read up on and comply to SEOmoz’s attribution and branding requirements. And, finally, launch your application to web users!

If you happen to live in the Pittsburgh area, you should check out our upcoming Google Analytics and AdWords training. In the Google Analytics APIs class, we’ll be teaching attendees how to interact with and get the most out of the Google Analytics API.