To call the MOZ API first we will need to work out what the request Url should look like.To illustrate how to do this I will use the example of requesting the domain authority for the website comparethemarket.com.

A completed url looks like this (login details have been altered):
‍https://lsapi.seomoz.com/linkscape/url-metrics/comparethemarket.com?Cols=68719476736&Limit=10&AccessID=member-mozscape-45676fedfgg11918&Expires=1519988622&Signature=dg%2bWtcTbVBg%2fQmtAIwcloy2S7aY%3d

This has been put together by the following steps:

1. The HTTP or HTTPS request to the host name and resource.
‍http://lsapi.seomoz.com/linkscape/
‍
‍2. The API command to call. Domain authority comes under url-metrics:
‍http://lsapi.seomoz.com/linkscape/url-metrics/
‍
‍3. The target URL to analyze(in this case comparethemarket.com) .
‍http://lsapi.seomoz.com/linkscape/url-metrics/comparethemarket.com
‍
‍4. The parameters to call. The ? indicates where the parameters begin. The & separates each parameter. The ‘Cols=’ then the number is the reference to which parameter you are querying (in this example domain authority which has been given the code 68719476736). The ‘Cols=’ is always before the number no matter which parameters/ information you want to find out.
‍https://lsapi.seomoz.com/linkscape/url-metrics/comparethemarket.com?Cols=68719476736&Limit=10&

‍The limit relates to the amount of decimal places you get back in the response for the domain authority.

5. Paste this url into your browser. A pop up is generated which asks for your authetication information.

Fill this in with your; Access ID and Secret Key.

You can generate your access ID and secret key here:
‍https://moz.com/products/api/keys

‍Free access allows for one request every ten seconds, up to 25,000 rows per month.

‍When you fill this in your browser generates an ‘encrypted authentication’ string, a signature which is added to the end of the rest of the url.

The completed url looks like (I have altered secret key and signature information):

‍https://lsapi.seomoz.com/linkscape/url-metrics/comparethemarket.com?Cols=68719476736&Limit=10&AccessID=member-mozscape-454568fedfgg11918&Expires=1519088614& Signature=dg%2bWtcTbVBg%2gQcvAIwcloy2S7aP%3k

6. To call this url with a programme (written in C# or any other language). Then this end authentication signature needs to be encoded by your programme.

This signed authentication has 3 query string parameters to every call:

1. AccessID
2. Expires (UNIX timestamp in seconds) — how long the request is valid for .. should only be a few mins ahead of current time.
3. Signature — an HMAC-SHA1 hash of your Access ID, the Expires parameter, and your Secret Key. The secure hash must be base64 encoded then URL-encoded before Mozscape accepts the signature as valid.

The final authentication string, which will be added to the end of the API call url should look like this (again information has been altered):

AccessID=member-cf180f1267&Expires=1267838899&Signature= LxvNXYcPqc%12BkapNKzHzYz2BI4SXfC%9H

What is the Encrypted signature?

‍Part 3, the encrypted signature relates to the “&Signature=” part at the end of the url call. The letters and numbers which come after this label are created by the following process:

1. Create a HMAC hash from the 3 described paramaters (Access ID, Expires parameter, and Secret Key).

Access ID ==> HMAC-SHA1 String

The HMAC is a hash based method which takes some information, say a word, and character by character changes this into hexidecimal numbers.

The SHA1 is the specific algorithm which is used to create the HMAC hash.

An example of a HMAC-SHA1 hash is;a298f932c163f3abf36c324f1e252e81eec577ea

‍This is basically a string of hexidecimal characters.(Generated using; https://www.freeformatter.com/hmac-generator.html).

2. Then we convert this Hexidecimal string to a base64 one.

Hexadecimal string ==> base64 string

A Hex is a base16 string. Base64 is shorter but has a much larger number of letters and characters which represent it.

An example of a base64 string is:
‍0kDaABnU4R+J6OiCjezSk5Io8vw=

‍(Generated using; http://tomeko.net/online_tools/hex_to_base64.php?lang=en).

3. Convert this base64 string to a url encoded string.

Base64 string ==> URL encrypted string

A base64 string can include characters which are not supported in a url. Since the encoded string generated needs to be posted in the url the last step is to url encrypt it.

An example of a url encoded string is:
‍0kDaABnU4R%2BJ6OiCjezSk5Io8vw%3D

‍Characters such as = cannot go in a url so this step has encoded these unsupported characters.
(Generated using; https://ostermiller.org/calc/encode.html).
‍

An application written in C# which can request information from Moz’s API

The code would follow the same steps and order as above. The below example is only for the encryption aspect of the code as I have assumed putting together the rest of the Url request in code is fairly straight forward.

An Authentication class:

This class first creates the encrypted signature string, then appends this to a string with the AccessID and Expires details on.

To call and use this class the Programme.cs class would look like:

Why has this encryption been done by Moz?

This has been done because Moz‘s database will most likely hold an encryption of your access ID and Secrete Key. They will have done the same steps (potentially bar the url encryption) once they generated your account information. This means they aren’t holding in their database (which can be seen by the engineers working for them or potentially someone who hacked in to get access) your information but instead they are holding an encoded version of it. This means someone would not be able to know your information if they got hold of the database which contains it.

This is an example of a one-way encryption.

In this article I have expanded on the documentation MOZ has put together on how to compose the request Url string to get information from its API. I have used the example of requesting domain authority for comparethemarket.com.