Redirect map recipe: rank old URLs by the links they hold
A redirect map is a priority list, not a spreadsheet of every URL. Start with the pages other sites link to, and the rest of the map gets easier.
ArchiLinks research team ·
Why rank by links
Teams build maps from the crawl. It is complete. It also treats a forgotten 2014 press page like the homepage.
When you check backlinks to my site and sort the pages by the number of linking domains, a pattern shows up in most migrations: a few dozen URLs hold most of the external value. Those URLs get hand-matched, reviewed twice and tested first.
Everything else follows rules. Folders map by pattern, parameters get stripped, and orphan URLs with no links and no traffic can return 410 if you decide so. Pair the output with the migration checklist so the map gets a test before launch and a re-check on day 45, and with the API scripts for scheduling the monthly pull.
Step 1: pull the linked pages
One call returns up to 1,000 rows and costs 2 credits, whatever the row count. Field names below are an example; look at one real response and adjust the keys.
import csv, requests
BASE = "https://archilinks.com/api.php"
KEY = "sk_live_..."
def call(action, **params):
r = requests.get(BASE, params={"action": action, "key": KEY, **params}, timeout=30)
r.raise_for_status()
return r.json()
data = call("toppages", q="old-shop.com", per=1000)
rows = next(v for v in data.values() if isinstance(v, list))
with open("linked-pages.csv", "w", newline="") as f:
w = csv.writer(f)
w.writerow(["old_url", "links", "new_url"])
for row in rows:
w.writerow([row.get("url"), row.get("backlinks"), ""])Step 2: fill the third column
Match by meaning
A product page goes to the same product, or its category if the product is gone. Never to the homepage unless the page was the homepage.
Let a second person check the top 50
A tired person at 6 p.m. maps a guide on canonicals to a blog index. A reviewer catches it.
Rules for the long tail
Write patterns for folders and strip tracking parameters. Keep each rule in version control with a comment explaining why.
Step 3: emit server rules
nginx reads a map file well, and it scales to tens of thousands of lines.
# /etc/nginx/redirects.map (generated from the csv)
/old/guide-canonicals /guides/canonical-tags;
/products/blue-widget /shop/widgets/blue;
# in nginx.conf, http context
map $request_uri $new_uri {
default "";
include /etc/nginx/redirects.map;
}
# in the server block of the old host
if ($new_uri) {
return 301 https://new-shop.com$new_uri;
}Step 4: test every hop
Fail the pipeline on anything that is not a single 301 to a 200.
while IFS=, read -r old new; do
out=$(curl -s -o /dev/null -w "%{http_code} %{num_redirects} %{url_effective}" -L "https://old-shop.com$old")
echo "$old -> $out"
done < redirect-pairs.csv | grep -v "^.* -> 200 1 " && echo "FIX ABOVE"Mistakes we would check for first
| Symptom | Likely cause | Fix |
|---|---|---|
| Chains of two or three hops | Old rules stacked on new ones | Point the old rule straight at the final URL |
| Everything lands on the homepage | Lazy catch-all rule | Match by topic; Google may treat mass homepage redirects as soft 404s |
| Query strings lost | Rule drops the arguments | Carry over the parameters that change content; strip the rest |
| Top URL returns 404 after launch | Left out of the CSV | Rerun the pull and diff against the live map |
Redirect questions that keep coming up
- Should I remove the old redirects after a year?
- Google advises keeping them for at least a year. Beyond that, keep them as long as old URLs still get external links or traffic. Redirects cost almost nothing to serve, so there is rarely a good reason to delete them early.
- Is it fine to redirect only the indexed pages?
- Not if the unindexed ones carry links. Index status says little about external value. Redirect every URL that has a linking domain, then decide on the rest by traffic.
- What about 302 or 307 for a permanent move?
- Use 301 or 308 for permanent moves. Google treats long-lived 302s as permanent in time, but you are leaving the signal to chance, and other consumers of the redirect may not guess the same way.
- Can I redirect 404s from the old site to the new one?
- Only when a close match exists. A redirect to an unrelated page is a soft 404 in Google's eyes. Return a real 404 or 410 when the content is gone.