Redirect mapping is one of the most time-consuming parts of a website migration. Every old URL needs the right destination. Miss a redirect or send visitors to the wrong page, and you could lose search visibility, valuable backlinks and customers.
AI tools can now create redirect maps in minutes. Used properly, they can save days of manual work. But faster does not always mean more accurate.
We tested an open-source AI redirect mapping tool to find out where it helps, where it makes mistakes and what needs checking before a website goes live.
This guide explains what we found and how SEO, content, marketing and development teams can use AI to build redirect maps without putting their website’s search performance at risk.
1. What Happened?
An Open-Source AI Redirect Mapping Tool
The Automated Redirect Mapper, published on GitHub by John McAlpin, is a free Python tool designed to create redirect maps for website migrations and URL changes.
You give it two lists: your old URLs and your new URLs. It then tries to match them using three methods, in this order.
- URL structure matching: The tool compares URL paths, shared words and folder depth. It accepts a match when its score reaches 0.7 or higher.
- AI matching: If the tool cannot find a suitable structural match, it sends groups of URL paths to Google’s Gemini model. The AI suggests destinations and returns a confidence score.
- Homepage fallback: Any URL that remains unmatched, or receives an AI confidence score below 0.7, is redirected to the homepage.
The tool can export the redirect map as CSV, JSON, Nginx rules and Apache rules. It also produces a report showing how each redirect was matched.
It runs in Google Colab, stores AI responses to help reduce API costs, and sends URL paths to the AI rather than the full page content.
It is a useful starting point, especially for teams managing large migrations. However, our testing showed why the output should be treated as a first draft rather than a finished redirect map.
What We Found When We Tested the Tool
We ran the tool’s code offline, with its AI calls switched off, against a sample set of migration URLs.
This allowed us to test the parts that work without AI, including URL structure matching, the prompts prepared for the AI and the rules generated for web servers.
We found five issues that anyone using this tool, or a similar one, should understand.
| What we tested | What happened | Why it matters |
|---|---|---|
| Matching a product URL | /products/red-shoes scored 0.41 against the correct destination, /shop/shoes/red-shoes, but 0.72 against /products/blue-shoes. The tool chose blue shoes. | The folder structure mattered more than the product itself. A wrong match still passed the confidence threshold. |
| Matching similar articles | /blog/how-to-clean-shoes scored 0.77 against /blog/how-to-clean-boots. | A high score did not mean the pages were equivalent. |
| URLs supplied to the AI | When we supplied 64 new URLs, the prompt included only 25, selected without a clear order. | The AI could not choose the correct destination if it was not shown that URL. |
| Nginx and Apache exports | The generated rules included full URLs in places where paths were expected, along with unescaped characters such as those in c++. | The rules could fail to match the intended URLs. |
| URL formatting | /search?q=shoes was reduced to /search, and trailing slashes were removed. | URLs with different parameters could be treated as the same URL, causing incorrect or missing redirects. |
Two further issues stood out.
First, the AI’s confidence score is its own estimate. It is not a measurement of how often the tool gets its matches right.
Second, the tool does not check whether every AI-suggested destination exists in the supplied list of new URLs. If the AI invents a URL, that destination could still make it into the exported map.
This does not mean the tool is useless. It means its output needs checking.
The project’s own documentation also recommends reviewing homepage fallbacks manually and explains that the tool works best when old and new URLs have similar structures.
What Google Says About Redirect Mapping
Google’s website migration guidance sets out several important principles that any redirect map should follow.
- Match old URLs to their new equivalents. Each old page should redirect to the most relevant page on the new site.
- Do not send unrelated pages to the homepage. Redirecting many old URLs to one irrelevant destination can cause Google to treat those URLs as soft 404s. It is fine to redirect several old pages to one new page when that page genuinely replaces their content.
- Avoid redirect chains. Send visitors and search engines directly to the final destination wherever possible. Keep any unavoidable chains short.
- Use permanent redirects. Google recommends permanent redirects, such as HTTP 301 or 308 redirects, for permanent URL changes. These do not cause a loss of PageRank.
- Keep redirects in place. Google recommends keeping them for at least a year, and longer where possible to help users who still visit old URLs.
- Allow time for Google to process the migration. For a medium-sized website, it can take a few weeks or longer for Google to show the new URLs in search results. Larger websites can take longer.
The principle is straightforward: a redirect should take people and search engines to the page that genuinely replaces the original one.
2. Why Does Redirect Mapping Matter?
A redirect map helps preserve the search value of your existing website when URLs change.
Automating the first draft can save time. But if that draft contains mistakes, the cost can show up after launch, when recovering lost traffic and sales becomes much harder.
Our testing highlighted five main risks.
1. Homepage Fallbacks Can Waste Existing Search Value
The tool sends unmatched URLs to the homepage.
This might seem like a safe option because visitors still reach the website. However, Google warns that redirecting many unrelated URLs to one destination can result in soft 404s.
Imagine a customer clicks a search result for a specific product but lands on the homepage instead. They must find the product themselves, assuming it is still available.
The same applies to articles, service pages and category pages.
You could lose valuable traffic, backlinks and conversions simply because the redirect does not take visitors to a relevant destination.
On a large e-commerce website, the fallback list could contain thousands of URLs.
2. A Wrong Match Can Be Worse Than a Missing Redirect
A missing redirect is relatively easy to identify during testing. The old URL returns a 404 error instead of taking visitors to the intended destination.
A wrong redirect can be harder to spot.
For example, an old red-shoes product URL might redirect to a blue-shoes product. The redirect works technically, and the destination returns a 200 status code.
An automated test may therefore consider it successful.
Yet customers land on the wrong product, and the original page’s search performance could suffer. Unless someone checks the destination itself, the mistake might remain unnoticed until traffic or sales decline.
A redirect that works technically is not necessarily a correct redirect.
3. Confidence Scores Can Create a False Sense of Security
The tool uses two types of scores: one based on URL structure and another generated by the AI.
Neither score proves that the old and new pages contain equivalent information.
A report showing an average confidence score of 0.85 might look reassuring. However, without checking a sample of the matches against the actual pages, you cannot know how accurate the map really is.
Confidence scores can help prioritise reviews, but they should not replace quality checks.
4. Incorrect Server Rules Can Fail Without Being Obvious
Redirect rules must use the correct syntax for the server or platform running them.
Rules containing full URLs where paths are expected, unescaped special characters or incorrect matching patterns might not work as intended.
That means an exported file can look complete while some redirects never fire.
If these problems are caught during staging tests, they can be fixed before launch. If not, they can lead to missing pages, 404 errors and lost traffic after launch.
5. Migration Mistakes Can Take Time to Recover From
Google needs time to process a website migration and update the URLs it shows in search results.
If the redirect map contains errors, those mistakes can make the transition harder.
For example, an old page may stop appearing in search results before its intended replacement gains visibility. A wrong redirect can make the situation worse by sending users to a page that does not answer their query.
The longer the problem goes unnoticed, the harder it can be to understand what happened and recover the lost performance.
The Main Redirect Mapping Risks at a Glance
| Risk | What happens | When you might notice | Potential cost |
|---|---|---|---|
| Homepage fallbacks | Unrelated pages redirect to the homepage | Weeks after launch | Lost search visibility, backlinks and relevant traffic |
| Wrong matches | Visitors land on the wrong product or article | When traffic or sales decline | Lost conversions and a poor user experience |
| Overstated confidence | The report makes an inaccurate map look reliable | Potentially never, unless someone checks | Incorrect redirects approved without proper review |
| Broken server rules | Redirects fail to fire and old URLs return 404 errors | On launch day if tested; otherwise potentially weeks later | Widespread loss of access to old URLs |
| Lost parameters or trailing slashes | Some versions of old URLs fail to match the rules | After launch, during crawling or log analysis | Missing redirects for affected URLs |
3. Who Is Affected by AI Redirect Mapping?
Any business changing its website URLs needs a reliable redirect map. This includes domain changes, rebrands, platform migrations, redesigns and changes to website categories.
The risk generally increases with the number of URLs involved and the extent to which the website structure changes.
E-commerce and Retail Websites
E-commerce websites often have thousands of product and category URLs.
Many products have similar names, such as red shoes and blue shoes. Others are discontinued, replaced or available through URLs containing filters and other parameters.
These websites are particularly vulnerable to incorrect matches based on URL text. They can also end up with large numbers of homepage fallbacks.
Publishers and Content Websites
Publishers often have years of articles with similar titles, topics and URL structures.
A tool matching pages based on shared words might send an old article to another article covering a similar subject, even when it is not the right replacement.
The correct destination needs to be chosen based on the content and purpose of the original page.
Website Platform Migrations
Moving from WordPress to Shopify, Magento to a headless website, or one content management system to another can change URL structures considerably.
When the old and new URLs share little structural similarity, automated URL matching becomes less reliable.
More URLs may need AI-assisted matching or manual review.
Rebrands, Mergers and Acquisitions
When two websites become one, some pages overlap while others use different names and URL structures.
Deciding which page should replace another may require decisions about content, products, services and business priorities.
A simple URL comparison cannot make those decisions reliably on its own.
Multi-Language and Multi-Region Websites
URLs in different languages may share few or no words, even when the pages cover the same product or service.
This makes text-based matching less useful.
Migration planning must also account for the relationships between language and regional versions of pages, including their hreflang annotations where applicable.
SEO Agencies and Consultants
Agencies often manage migrations against tight deadlines.
AI-generated redirect maps can reduce the time spent on repetitive tasks, but rushing the review process creates unnecessary risks for both the client and the agency.
A map that looks complete is not necessarily ready to go live.
Developers Implementing Redirect Rules
Developers are responsible for implementing redirect maps in the appropriate environment, whether that is Nginx, Apache, a content management system or a content delivery network.
Even a well-mapped spreadsheet can fail if the rules are implemented incorrectly.
The mapping process and the implementation process must therefore be checked separately.
When is automation worthwhile?
For a small restructure involving a few dozen URLs, mapping everything manually may be quicker than setting up an AI tool.
Automation becomes more attractive when the number of URLs reaches the hundreds or thousands. At that scale, however, automated checks and targeted human reviews become even more important.
4. What Should Businesses Do?
The safest approach is to let automation draft the redirect map, use data to guide the decisions, have people approve important matches and run tests before launch.
The process below works with the open-source tool, another AI solution or a spreadsheet. The important part is following the steps in the right order.
Step 1: Build a Complete List of Old URLs
You cannot redirect URLs that you do not know exist.
Start by collecting URLs from every useful source and removing duplicates.
Include:
- A full website crawl: Collect URLs from the current website, including pages that might not appear in the XML sitemap.
- XML sitemaps: Use these to identify URLs the website currently lists for search engines.
- Google Search Console: Export page-level performance data covering up to 16 months, using the API where necessary to collect data beyond the interface’s row limit.
- Analytics data: Collect landing pages from the previous 12 to 24 months to identify URLs that bring visitors to the website.
- Backlink tools: Identify the pages with the most valuable external links.
- Server logs: Find old URLs that users and search engine crawlers have requested recently.
Combine the data into one list and remove duplicates.
Next, rank the URLs by business value. Consider organic clicks, revenue, conversions and referring domains.
This gives you a clear view of which pages deserve the most attention during the review process.
A URL that generates substantial revenue or attracts valuable backlinks should receive more scrutiny than an old page with no traffic or links.
Step 2: Build a Complete List of New URLs
Once the new website structure is finalised, crawl the staging website or export its XML sitemap.
Use the resulting list as the official set of permitted redirect destinations.
Every redirect destination should be checked against this list.
This helps prevent the map from sending visitors to a URL that was never created, has a spelling mistake or no longer exists.
If the new URL structure is still changing, the redirect map is not ready for final approval. Freeze the structure before completing the mapping work, and update the map if any URLs change afterwards.
Step 3: Match URLs Using Data Before Using AI
The most reliable matches often come from shared identifiers rather than similar-looking URLs.
Before involving AI, look for ways to match the old and new URLs using information from the content management systems.
- Products: Match using SKUs, product IDs, GTINs or other stable identifiers available in both systems.
- Articles: Match using post IDs, publication dates combined with titles, or other reliable content identifiers.
- Categories and landing pages: Map these manually where possible. There are often fewer of them, and they can be important to organic traffic and revenue.
- Unchanged URLs: Match exact paths where the URL remains the same and the page continues to serve the same purpose.
For example, if a product’s ID is preserved during a move from one e-commerce platform to another, the ID can provide a much stronger match than comparing two product names.
Where both systems provide reliable IDs, this step can map a large proportion of URLs before AI is needed.
Step 4: Use AI for the Remaining URLs
AI becomes more useful when the remaining URLs are difficult to match through IDs or URL structure alone.
However, the quality of the results depends on the information the model receives and the options it can choose from.
Give the AI Page Content, Not Just URLs
A URL does not always explain what a page contains.
Where possible, provide the model with page titles, H1 headings, meta descriptions and a short summary of the page content.
This gives it more information to work with when comparing old and new pages.
For complex migrations, including the actual page content may improve matching further.
Shortlist Relevant Destinations Before Asking the AI to Choose
Do not ask an AI model to compare one old URL against a huge list of new URLs without first narrowing down the options.
Instead, use embeddings or another similarity method to find the ten most relevant new pages for each old page.
Then ask the AI to choose the best destination from that shortlist, or return “no match” if none is suitable.
This approach has two main advantages.
First, the model sees a smaller set of relevant candidates rather than an arbitrary selection of URLs.
Second, every suggested destination comes from the approved list of new URLs, rather than being invented by the model.
Allow the AI to Return No Match
Not every old page will have an equivalent on the new website.
If a relevant replacement exists at a higher level, the page might be redirected to its parent category. If there is no suitable destination, returning a 404 or 410 status may be more appropriate.
Do not redirect every unmatched URL to the homepage simply to make the spreadsheet look complete.
Changes to Make Before Relying on the Open-Source Tool
If you use the Automated Redirect Mapper, make the following changes before using its output in a live migration:
- Ensure the AI receives all relevant new URLs or a suitable shortlist for each old URL, rather than only the first 25 candidates.
- Replace automatic homepage fallbacks with an unmapped label that requires review.
- Reject any suggested destination that is not present in the approved new-URL list.
- Generate the final server rules only after the redirect map has passed the necessary checks.
The aim is not to force a match for every URL. It is to find the right destination where one exists and identify the exceptions that need a decision.
Step 5: Review the Map by Business Value, Not Just URL Count
Manually checking 50,000 redirects is rarely practical. Fortunately, not every redirect needs the same level of attention.
Focus your effort on important pages and anything flagged by automated checks.
| Group | Recommended review |
|---|---|
| Top 20% of old URLs by traffic, revenue or backlinks | Check every destination manually with someone who understands the content. |
| URLs flagged for near matches, homepage redirects, conflicts, chains or unknown destinations | Investigate and resolve every issue. |
| URLs matched through reliable identifiers | Spot-check the results to confirm the matching process is working correctly. |
| URLs matched through AI | Review a random sample of 5%. If more than 2% of the sample is incorrect, review the entire group. |
The sample also gives you a measured error rate.
For example, if you review 200 AI-generated matches and find eight incorrect destinations, the observed error rate is 4%.
That is a more useful measure of accuracy than an AI-generated confidence score. It is still an estimate, however, and the quality of the sample matters.
Step 6: Run Automated Checks Until the Map Is Clean
Use a redirect map checker against the old URL list, new URL list and proposed redirect map.
At a minimum, it should identify:
- Destinations that do not exist on the new website.
- Redirects pointing to the homepage.
- Destinations receiving unusually large numbers of redirects.
- Redirect chains and loops.
- Conflicting rules that send the same old URL to different destinations.
- Suspicious near matches, such as red shoes redirecting to blue shoes.
- URLs with no meaningful words in common between the old and new paths.
- Low-confidence matches.
- Old URLs containing parameters that need special handling.
- Old URLs that have no redirect in the proposed map.
Fix the flagged issues, run the checks again and repeat until all unresolved problems have been reviewed.
Some flags will be intentional. A retired product may correctly redirect to a replacement category, for example. The important thing is to document and approve those decisions rather than allowing them to pass without review.
The developer toolkit later in this article includes a Python script for carrying out several of these checks.
Step 7: Implement the Redirect Rules Correctly
Once the map has been checked and approved, implement the redirects in the appropriate server, platform or edge environment.
Use Permanent Redirects and Avoid Chains
Use 301 or 308 redirects for permanent URL changes.
Where possible, send the old URL straight to the final destination rather than redirecting it through an intermediate page.
Use the Correct Matching Rules
The implementation must match the URL patterns that actually exist.
In Nginx, a map using exact-path matching can be easier to manage than thousands of individual rewrite rules. In Apache, carefully written RedirectMatch rules can provide precise path matching.
The rules must be tested against the actual server configuration. Special characters, trailing slashes and query parameters can affect how URLs are matched.
The developer toolkit below generates example Nginx and Apache rules from rows that pass its checks. These outputs still need to be reviewed and tested before they are deployed.
Handle URL Parameters Deliberately
URLs can contain query parameters for filters, sorting, campaigns and other functions.
For example:
/search?q=shoes
A redirect rule that ignores the query string may treat several different parameter URLs as the same path.
Decide which parameter URLs need individual redirects. Give dedicated rules to important URLs, such as filter pages with organic traffic or campaign landing pages that still receive visitors.
Consider Redirects at the Edge
For very large migrations, a content delivery network (CDN) or edge redirect service can make it easier to manage large redirect maps without placing unnecessary work on the origin server.
The right approach depends on your infrastructure, the size of the map and the features supported by your hosting provider.
Update Internal Links and Other Website Signals
Redirects should not be used as a substitute for updating the new website itself.
Update:
- Internal links and navigation.
- Canonical tags.
- Hreflang annotations.
- Structured data containing old URLs.
- XML sitemaps.
- Campaign URLs and other links controlled by your business.
Where possible, contact the websites responsible for your most valuable backlinks and ask them to update their links to the new URLs.
For a domain move, use Google Search Console’s Change of Address tool where applicable, once the redirects are live.
Step 8: Test Before Launch and Monitor Afterward
The redirect map should be tested before the new website goes live. Monitoring must then continue after launch to catch problems that only appear in production.
Before launch
Request every old URL against the staging environment, where the setup permits it. Confirm that each URL returns the expected permanent redirect and that the final destination returns a successful response.
Check the content of the destination, not just its HTTP status code. A 301 to the wrong page can still pass a basic technical test.
During launch week
Crawl the old URL list daily and review server logs for requests to old paths that return 404 errors.
Investigate unexpected status codes, redirect chains, loops and destinations that do not load correctly.
During the first two months
Monitor Google Search Console for Not found, Page with redirect and soft 404 reports. Bear in mind that some reports take time to update.
Compare search performance for your most valuable old URLs with the performance of their intended replacements.
Do not assume a drop in clicks automatically means the redirects are wrong. Look at the individual URLs, their destinations and the wider migration data before deciding what needs fixing.
Keep the redirects in place
Google recommends retaining redirects for at least a year. Keeping them for longer, or indefinitely where practical, can also help users and external websites that continue to reference the old URLs.
Who Does What? A Team-by-Team Rollout
A successful migration needs clear responsibilities across SEO, content, development and marketing.
| Team | Main responsibilities | Ready for launch when |
|---|---|---|
| SEO | Build the old and new URL inventories, rank pages by value, carry out identifier and AI matching, run the checker and organise reviews. | No important issues remain unresolved, and the reviewed sample meets the agreed accuracy target. |
| Content | Review high-value destinations, decide where retired content should be consolidated and approve cases with no suitable replacement. | Every high-value old URL has an approved destination or a documented reason for its treatment. |
| Development | Export identifiers from both systems, implement redirect rules, handle parameters, test on staging and update internal links, canonicals and sitemaps. | Every old URL has the expected response, with redirects reaching the correct destination. |
| Marketing | Update campaign URLs, email templates, advertising links and social profiles. Contact important linking websites where possible. | Paid and owned marketing channels no longer point to old URLs unnecessarily. |
| Project lead | Freeze the new URL structure, schedule review time, coordinate teams and approve launch readiness. | The migration checklist is complete and outstanding exceptions have been signed off. |
Developer Toolkit: A Python Redirect Map Checker
The following Python script checks a redirect map before launch, regardless of whether a person, spreadsheet formula or AI tool created it.
It uses Python’s standard library and produces three files:
qa_report.csv— a report showing the issues found for each redirect.redirects.nginx.map— an example Nginx map containing only rows that pass the script’s checks.redirects.htaccess— example ApacheRedirectMatchrules containing only rows that pass the script’s checks.
The script checks for unknown destinations, homepage fallbacks, destinations receiving too many redirects, chains, loops, conflicting rules, suspicious URL matches, low-confidence scores and URLs containing query parameters.
It can also compare the map against a list of old URLs to identify URLs with no redirect. An optional live check requests destinations and records their HTTP status codes.
What We Found When Testing the Checker
We tested the script using a sample redirect map containing 12 rows and several mistakes that can occur in automated mapping.
It flagged:
- Red shoes redirecting to blue shoes.
- A shoe-cleaning article redirecting to a boot-cleaning article.
- Both homepage fallbacks.
- A destination missing from the new website’s URL list.
- Conflicting rules for
/about-usand/about-us/. - A redirect chain.
- An old URL containing query parameters.
- An old URL missing from the redirect map.
The live check also identified a destination that redirected again and one that returned a 404 error.
The generated Apache patterns matched the intended path with or without a trailing slash. They also avoided matching longer paths that merely started with the same characters, including paths containing special characters such as /c++/guide.html.
One part of the checker needed changing during testing.
Our first word-overlap check flagged eight of the 12 rows, including valid URL changes where the new page had a different name.
We replaced that broad check with more targeted checks for likely near matches and URLs with no meaningful words in common. These checks flagged fewer rows and made the results more useful for manual review.
Important: This is a first-pass quality checker, not proof that the redirect map is correct. Its rules are based on URL patterns and other available data. It cannot determine every content relationship or business decision automatically. Review flagged rows, test the generated rules in your own environment and confirm the destinations before deploying them.
The Python Script
Save the following code as redirect_map_qa.py.
#!/usr/bin/env python3
"""
redirect_map_qa.py - Szymaniak Digital
Quality checks for a redirect map before launch, whoever (or whatever) drafted
it - a person, a spreadsheet formula or an AI tool. Standard library only.
Inputs
redirects.csv columns old_url,new_url (extra columns such as confidence or
reason are kept). Full URLs or paths.
--new FILE every valid destination URL on the new site (from the new
sitemap or a crawl of staging), one per line
--old FILE (optional) every old URL that needs a redirect, e.g. from a
crawl, Search Console and backlink exports, one per line
--live (optional) request each destination and record its status
Checks
unknown_target destination is not in the new-site inventory (invented or typo)
homepage destination is the homepage
concentrated destination receives many redirects (possible soft 404 pattern)
chain / loop destination is itself redirected, or leads back to the source
conflict the same old URL is mapped to different destinations
near_miss same slug pattern, different key word (red-shoes -> blue-shoes)
no_shared_words old and new URLs share no meaningful word: check by hand
low_confidence confidence column below the threshold
query_string old URL has parameters: needs a dedicated rule
uncovered an old URL in --old has no redirect at all
Outputs
qa_report.csv one row per redirect with its issues
redirects.nginx.map exact-match Nginx map, clean rows only
redirects.htaccess Apache RedirectMatch rules, clean rows only
Usage
python3 redirect_map_qa.py redirects.csv --new new_urls.txt [--old old_urls.txt]
[--concentration 20] [--min-confidence 0.8] [--live]
"""
import re
import csv
import sys
import argparse
import urllib.request
from collections import Counter, defaultdict
from urllib.parse import urlsplit
STOP = {"a", "an", "and", "the", "of", "to", "for", "in", "on", "how", "what", "is", "with",
"html", "htm", "php", "aspx", "index", "www", "page"}
def path_of(url):
"""Path plus query, keeping trailing slashes; '/' for the root."""
p = urlsplit(url if "://" in url else "https://x" + ("" if url.startswith("/") else "/") + url)
return (p.path or "/") + (("?" + p.query) if p.query else "")
def key(url):
"""Comparison key: path without trailing slash, lower-cased, query kept."""
p = urlsplit(url if "://" in url else "https://x" + ("" if url.startswith("/") else "/") + url)
path = (p.path.rstrip("/") or "/").lower()
return path + (("?" + p.query) if p.query else "")
def _tokens(text):
return {w for w in re.split(r"[^a-z0-9]+", text.lower()) if w and w not in STOP and not w.isdigit()}
def words(url):
"""(meaningful words in the last path segment, words in the whole path and query)"""
p = urlsplit(url if "://" in url else "https://x/" + url.lstrip("/"))
segs = [s for s in p.path.split("/") if s]
return _tokens(segs[-1] if segs else ""), _tokens(p.path + " " + p.query)
def load_list(path):
with open(path, encoding="utf-8-sig") as fh:
return [l.strip() for l in fh if l.strip() and not l.startswith("#")]
def status(url):
req = urllib.request.Request(url, method="HEAD", headers={"User-Agent": "redirect-map-qa"})
class NoRedirect(urllib.request.HTTPRedirectHandler):
def redirect_request(self, *a, **k):
return None
try:
with urllib.request.build_opener(NoRedirect).open(req, timeout=15) as r:
return r.status
except urllib.error.HTTPError as e:
return e.code
except Exception:
return 0
def main():
ap = argparse.ArgumentParser()
ap.add_argument("redirects")
ap.add_argument("--new", required=True)
ap.add_argument("--old")
ap.add_argument("--concentration", type=int, default=20)
ap.add_argument("--min-confidence", type=float, default=0.8)
ap.add_argument("--live", action="store_true")
a = ap.parse_args()
with open(a.redirects, encoding="utf-8-sig", newline="") as fh:
rows = [r for r in csv.DictReader(fh) if (r.get("old_url") or "").strip()]
new_inv = {key(u) for u in load_list(a.new)}
sources = {key(r["old_url"]): r for r in rows}
targets = Counter(key(r["new_url"]) for r in rows if (r.get("new_url") or "").strip())
by_source = defaultdict(set)
for r in rows:
by_source[key(r["old_url"])].add(key(r.get("new_url") or ""))
live = {}
if a.live:
for t in sorted({r["new_url"] for r in rows if r.get("new_url", "").startswith("http")}):
live[key(t)] = status(t)
report, clean = [], []
for r in rows:
old, new = r["old_url"].strip(), (r.get("new_url") or "").strip()
ko, kn = key(old), key(new)
issues = []
if not new:
issues.append("no_target")
else:
if kn not in new_inv:
issues.append("unknown_target")
if kn == "/":
issues.append("homepage")
elif targets[kn] >= a.concentration:
issues.append(f"concentrated({targets[kn]})")
if kn == ko:
issues.append("loop")
elif kn in sources:
nxt = key(sources[kn].get("new_url") or "")
issues.append("loop" if nxt == ko else "chain")
if len(by_source[ko]) > 1:
issues.append("conflict")
(o_last, o_all), (n_last, n_all) = words(old), words(new)
if kn != "/":
if o_all and n_all and not (o_all & n_all):
issues.append("no_shared_words")
elif (o_last & n_last) and (o_last - n_last) and (n_last - o_last):
issues.append("near_miss") # e.g. red-shoes -> blue-shoes
conf = r.get("confidence")
if conf not in (None, "") and float(conf) < a.min_confidence:
issues.append("low_confidence")
if kn in live and live[kn] != 200:
issues.append(f"target_status_{live[kn]}")
if "?" in path_of(old):
issues.append("query_string")
report.append({**r, "issues": ";".join(issues)})
if not issues:
clean.append((old, new))
uncovered = []
if a.old:
uncovered = [u for u in load_list(a.old) if key(u) not in sources]
fields = list(rows[0].keys()) + ["issues"] if rows else ["old_url", "new_url", "issues"]
with open("qa_report.csv", "w", newline="", encoding="utf-8") as fh:
w = csv.DictWriter(fh, fieldnames=fields, extrasaction="ignore")
w.writeheader()
w.writerows(report)
for u in uncovered:
w.writerow({"old_url": u, "new_url": "", "issues": "uncovered"})
with open("redirects.nginx.map", "w", encoding="utf-8") as fh:
fh.write("# include inside http {}: exact-path matches, both with and without trailing slash\n"
"map $uri $redirect_target {\n default \"\";\n")
for old, new in clean:
p = path_of(old).rstrip("/") or "/"
for variant in {p, p + "/"} if p != "/" else {p}:
fh.write(f' "{variant}" "{new}";\n')
fh.write("}\n# in the server {} block: if ($redirect_target) { return 301 $redirect_target; }\n")
with open("redirects.htaccess", "w", encoding="utf-8") as fh:
for old, new in clean:
p = path_of(old).rstrip("/") or "/"
fh.write(f"RedirectMatch 301 ^{re.escape(p)}/?$ {new}\n")
counts = Counter(i.split("(")[0] for r in report for i in r["issues"].split(";") if i)
print(f"Redirects checked: {len(rows):,} clean: {len(clean):,} need review: {len(rows) - len(clean):,}")
for issue, n in counts.most_common():
print(f" {issue:<22}{n:>6,}")
if a.old:
print(f" {'uncovered':<22}{len(uncovered):>6,}")
top = [(t, n) for t, n in targets.most_common(5) if n > 1]
if top:
print("Most-used destinations: " + ", ".join(f"{t} ({n})" for t, n in top))
print("Written: qa_report.csv, redirects.nginx.map, redirects.htaccess (clean rows only)")
return 1 if len(clean) < len(rows) or uncovered else 0
if __name__ == "__main__":
sys.exit(main())How to Run the Script
Prepare three files:
redirects.csvwith at least two columns:old_urlandnew_url. You can also include aconfidencecolumn.new_urls.txtcontaining the approved new URLs, one per line.old_urls.txtcontaining the full list of old URLs that need redirects, one per line. This file is optional but recommended.
Run the checker from your terminal:
python3 redirect_map_qa.py redirects.csv --new new_urls.txt --old old_urls.txtTo include the optional live destination check, run:
python3 redirect_map_qa.py redirects.csv --new new_urls.txt --old old_urls.txt --liveThe live check sends HTTP HEAD requests to destinations with full URLs. Some servers handle HEAD requests differently from normal browser requests, so verify any unexpected results manually.
The script requires Python 3. It does not require additional Python packages.
Before using the exported rules: Treat the output as a starting point. Review the generated configuration, verify how your web server handles paths and parameters, and test the rules in a staging environment. Only deploy them after confirming that each important old URL reaches the correct final destination.
5. What We’re Watching Next
AI will continue to make migration planning faster, including the first draft of redirect maps. The next challenge is making the checking process just as reliable.
These are the developments we are following at Szymaniak Digital.
Content-Aware Redirect Mapping
The next generation of tools will compare page content and structured data rather than relying mainly on URL paths.
They will also shortlist relevant destinations before asking an AI model to select the best match.
This should help reduce incorrect matches, but it will not remove the need for people to review high-value pages and make decisions about content that has no direct replacement.
Measured Accuracy Instead of Confidence Scores
We expect redirect mapping tools to provide more useful measures of accuracy, such as the error rate from a reviewed sample.
An AI-generated confidence score does not tell you how often the model is right.
Until tools provide reliable accuracy measurements, teams should check samples of the results and record the mistakes they find.
How Google Handles Large Numbers of Fallback Redirects
Google already warns that redirecting many old URLs to one irrelevant destination can lead to soft 404s.
As AI tools make it easier to generate large redirect maps, we will continue to watch how Google reports these issues and how they affect migration performance.
More Redirects Managed at the Edge
CDNs and edge platforms can support large redirect maps without sending every request to the origin server.
For websites with hundreds of thousands of URLs, this can make redirects easier to manage and maintain.
It also removes one reason to rely on broad, catch-all rules when more relevant destinations are available.
AI Search and Website Migrations
AI search systems can cite individual website URLs in their answers. A migration can therefore affect not only traditional organic search traffic but also the pages used in AI-generated responses.
Wrong or missing redirects may prevent people from reaching the intended content. AI search platforms may also refresh their source information on different schedules from Google’s search index.
We will continue to track how quickly AI search citations adapt to website migrations and which migration practices help businesses retain visibility.
6. About Szymaniak Digital
Szymaniak Digital is a UK enterprise SEO and AI search consultancy helping businesses protect and grow their organic search performance.
We plan and manage website migrations using redirect maps built from data, with automation used where it makes sense and human reviews focused on the pages that matter most.
Our approach combines URL inventories, identifier-based matching, AI-assisted drafting, quality checks and pre-launch testing to help businesses move to a new website without unnecessarily losing search visibility.
Planning a domain move, website replatform or URL restructure? Talk to Szymaniak Digital before your new URL structure is finalised. Early planning gives your team more time to map the URLs, review important pages and test the redirects before launch.
