V1 API Troubleshooting

Please note: Beginning August 8, 2024, Moz API will no longer support plain HTTP access. To avoid service disruption, please update any existing HTTP client configurations to HTTPS.

This documentation outlines the troubleshooting for now archived Moz API V1 endpoints. The Moz API V2 endpoints are available here.

I'm trying to send calls to Moz API V1. My code looks correct, but I still receive 401 Unauthorized errors.

1. With free access to Moz API V1, make sure you're specifying all of the parameters required for—and only the parameters allowed for—free access.
2. Make sure you're not encoding your Access ID or Secret Key before computing the signature. Only apply encoding transformations after the signature is computed.
3. Make sure you are not CGI-escaping before computing the signature.

   The Common Gateway Interface (CGI) is a protocol for passing HTTP requests from a web server to a standalone program, then returning the results to the web browser. Because some characters have special functions in HTML (like the forward slash / and ampersand &), CGI-escape provides a way to handle special characters when they are not part of a URL. If you CGI-escape your Moz API V1 call before computing your signed authentication, your signed authentication is incorrect and the Moz Links server returns a 401 error.

How can I integrate my API Credentials into an open source project?

1. Build an authentication service. Your open source project could make calls to your authentication service, returning individual signed requests set to expire in a shorter interval. (This is how MozBar uses Moz API.)

   A disadvantage to this approach is that it requires you to build your own custom authentication service, which may not be desirable for small-scale projects.

2. Pre-sign a request for your project using a large Expires parameter. Your open source code can include a signed request rather than generating a signed request on the fly. This method has the advantage of keeping your Secret Key secret.

   One disadvantage is that signed requests eventually expire. (In theory; the current maximum expiration interval is approximately 18 years. If this is too short, we'd love to hear about what you're doing!)

   Another disadvantage to this approach is that once you release a signed request into the wild, it's out of your control. Until the request expires, anyone can use it as much as they want. There is no way to stop service selectively; cancelling a signed request renders it invalid for everyone.

3. Embed your Secret Key directly into the source code. This works, but it's a security risk. Anyone who uses your source code has the potential to see your Secret Key and use it without your authorization.

I want to receive domain-level metrics and page-level metrics, but I'm confused by all the fields. Help!

Parameters and response fields let you specify fine degrees of distinction for the results Moz API V1 returns. Moz supports two different ideas of "domain-level":

• All pages on all fully-qualified domain names (or "subdomains") of a paid-level domain (i.e., the domain name registered through a registrar); and
• All pages on only one particular subdomain, including the non-subdomain.

Moz does this to support:

• Providing metrics to optimize a subdomain of a larger organization; for example, office.microsoft.com or googleblog.blogspot.com; and
• Providing aggregate metrics for a domain without meaningfully distinct subdomains.

What's the difference between the `Links` endpoint and the *links* parameter in the `url-metrics` endpoint?

The links parameter in the url-metrics endpoint returns the total number of links to the URL--equity and non-equity, internal and external.

The Links endpoint returns information about the link itself--for example, whether it has the rel=nofollow attribute set.

In the `Links` endpoint, what's the difference between the `LinkCols` and `Filter` parameters?

LinkCols specifies the information you want to receive about the URL itself (for example, anchor text). Filter lets you receive only results matching the value you specify.

For example:

<pre><code>http://lsapi.seomoz.com/linksc... addition to the canonical forms of the source and target pages (SourceCols=4 and TargetCols=4), this call returns the normalized anchor text (8) for the URL and the MozRank passed by the URL (16). 8 + 16 = 24; therefore, LinkCols=24. The call returns only links with the rel=nofollow attribute specified (Filter=nofollow), with a maximum of one result (Limit=1) with the highest page authority (Sort=page_authority).

What is a row, for purposes of pricing?

A row is determined by the Limit value of a Moz API V1 call, no matter how many other parameters a call specifies.

Default Limit values for links, anchor-text, and top-pages calls are 25, and range from 1 to a maximum of 50.

Limit values for url-metrics calls equal 1. Batched url-metrics calls return one row per URL in the batch.

Costs per row vary depending on your monthly commitment and usage.

Can I use wildcards to get all the subdomains for a domain?

Moz Links does not support wildcards.

To get all of the subdomains for a domain, specify the domain as the target URL in a Links call and specify Scope=page_to_domain. For example, searching for moz.com with Scope=page_to_domain would return all of the subdomains for moz.com.

My call received a 302 redirect.

It's all good. Just follow the redirect and your request will complete.

How can I get Moz Links to return an empty array?

For url-metrics calls, specify: Cols = 0.

For links calls, specify:

• LinkCols = 0
• TargetCols = 0
• SourceCols = 0