V1 Best Practices

This documentation outlines best practices for now archived V1 Mozscape API endpoints. The new Moz Links API endpoints are available here.

The url-metrics call is a simple and powerful tool for getting metrics about a URL.

You call url-metrics with a URL to analyze and query parameters to refine your search. The Cols parameter indicates which data Links API returns.

Without a Cols parameter, a call may be valid but returns no information.

Getting more data: link metrics

The links call returns information about inbound links, offering parameters and filters to give you exactly the amount of detail you seek.

Getting the data you want

To help you get the data you want, you can use query parameters to limit, offset, filter, sort, and scope your results. Query parameters help restrict the amount of data returned; this may seem less important for a call analyzing only one URL, but the ability to receive only the data you specify becomes increasingly important when making multiple calls per second.

Batching Your Calls

If you want the same url-metrics data for multiple URLs in an url-metrics call, you can group multiple URLs together ("batch" them) in a single call.

An url-metrics call for a single target URL uses the HTTP GET method. Requesting metrics for multiple URLs in a single call uses the POST method, with a JSON-encoded list of URLs in the POST body.

The results from a batch url-metrics call are returned in the order in which you requested them, so if "example.com" is the first element of the request, then the results for "example.com" will be the first listed in the returned response.

Batched calls place the target URLs in the body of a JSON-encoded POST rather than in-line with a GET.

In this example of batching in PHP, the first section sets up signed authentication and constructs the URL for the call. The next section sets up an array of the URLs for which to get metrics, encodes them using JSON, and sends them using CURL.

Batching only works with the url-metrics endpoint. Paid access allows a maximum of 50 URLs per batch. Free access allows 10 URLs per batch.

Tips to Avoid Throttling and Time Outs

1. Avoid making requests in parallel. Parallel requests increase the likelihood that an account will be throttled. Allow individual requests to complete before making new requests.
2. Make sure your batch includes 10 URLs or fewer. POST requests in excess of your access limits may return an HTTP 400 response.
3. Use the Limit and Offset parameters. Unsure of how many batch requests are required to retrieve all the backlinks for a target URL? Use Limit and Offset to advance calls through all possible results. The Moz Links index returns a maximum of 100,000 possible results.
4. Cache your results. Our servers may interpret repeated identical requests as a problem with your code and throttle your access in order to preserve good performance for everyone.

The Links API index updates periodically. Instead of making additional calls during the same Links API index period, you can cache the information you've already requested—there's no sense in paying for multiple requests to repeatedly receive identical information!

If you're concerned about caching stale data, you can set a time-to-live (TTL) value on the cache to expire at certain intervals. For finer control, use the next_update call in the metadata endpoint to learn the date of the next scheduled Moz Links index update.