Mapping Legacy Traffic to New URL Structures

Problem Statement

Legacy URL restructuring during migrations routinely triggers traffic collapse, attribution loss, and crawl budget waste. Unmapped paths generate immediate 404 spikes, overlapping regex rules create redirect loops, and stripped query strings break campaign tracking and revenue attribution. This page belongs to Traffic & Conversion Mapping; use it to isolate revenue-critical routes and enforce deterministic routing before structural changes occur.

Legacy-to-new traffic mapping flow GA4 revenue and crawl data are joined on page path, prioritised by value, mapped to new URLs, then deployed as 301 rules. Legacy Traffic Mapping Flow GA4 revenue Crawl export 2. Prioritise 3. Map URLs 4. 301 rules Tier by value Regex + CSV Nginx/Apache Join GA4 and crawl data on page_path before tiering
Revenue and crawl data join on page path, then flow through prioritisation and mapping into deployed 301 rules.

When to Use This Approach

Map by value, not by volume. The goal is to guarantee that the paths carrying the most revenue and the most organic equity land cleanly on their new homes, even if the low-traffic remainder of URLs is handled by broader pattern rules. This value-first ordering is what separates a migration that holds its rankings from one that bleeds them for months. Use this approach when:

  • The URL structure changes during the migration (directory renames, taxonomy moves, parameter cleanup).
  • Significant organic traffic and revenue are concentrated in a small set of paths.
  • Campaign tracking (UTM/session) must survive the cutover without attribution loss.
  • You already have a crawl baseline and 90 days of analytics to correlate.
  • You need a deterministic, testable mapping rather than ad-hoc per-page redirects.

The 90-day window matters: a shorter sample misses seasonal and campaign-driven paths that may be dormant on the day you crawl but critical to annual revenue. Joining analytics to the crawl on page_path ensures every high-value URL has both a measured value and a confirmed live status before it enters the mapping table.

Step-by-Step Instructions

1. Build Quantified Traffic Baselines

Correlate 90-day GA4 BigQuery exports with the crawl baseline by joining on page_path, and fingerprint each legacy URL for immutable change tracking. Pull the crawl side using how to export full crawl data before migration.

# Deterministic fingerprint per legacy path for change tracking
echo -n '/legacy/path' | sha256sum

2. Define Deterministic Transformation Rules

Write PCRE-compatible regex for legacy route capture and store the result in a strict CSV schema. Keep UTM-preservation intent explicit per row.

# Capture a legacy category path with optional query string
# regex: ^/old-category/([a-z0-9-]+)(?:\?|$)
# csvkit: confirm old_url values are well-formed paths
csvgrep -c old_url -r '^/' mapping.csv | wc -l   # count valid source rows
old_url,new_url,status_code,utm_preserve
/old/blog/post-1,/new/resources/post-1,301,yes
/old/product/widget,/new/shop/widget,301,yes

3. Deploy High-Performance 301 Routing

Apply the mapping at the web-server layer with strict header control. Use a map directive in Nginx or an external RewriteMap in Apache so large mappings stay maintainable — both data structures are hash-backed, so a 50,000-row map resolves in constant time rather than scanning a long list of rewrite rules. Decide permanence using the 301 vs 302 Decision Trees, and keep UTM parameters intact. Server-layer routing is preferred over application-layer logic here because it runs before the framework boots, cutting latency on every redirected request and removing a class of session-handling bugs.

map $request_uri $redirect_target {
    ~*^/legacy/(\w+)/(.*)$ /new/$1/$2;   # capture family + remainder
    default "";
}
server {
    if ($redirect_target) {
        return 301 $redirect_target$is_args$args;   # preserve query string
    }
}
RewriteEngine On
RewriteMap legacy txt:/etc/httpd/conf/legacy_urls.map
RewriteCond ${legacy:$1|NOTFOUND} !NOTFOUND
RewriteRule ^(.*)$ ${legacy:$1} [R=301,L,QSA]

4. Validate Routing Before Cutover

Run the redirect set against staging to confirm every Tier-1 path resolves in a single hop with its query string intact. Feed the validated schema into your reusable CSV Mapping Workflows.

# Confirm final status, single hop, and effective URL
curl -I -L -s -o /dev/null -w "%{http_code} %{url_effective}\n" \
  https://example.com/legacy/blog/post-1

Worked Example

A SaaS site moves oldapp.example.com/blog/ to app.example.com/resources/. GA4 shows three posts driving 64% of trial signups, so they are tagged Tier-1. The crawl join reveals 11 legacy posts share a UTM-laden inbound link, so utm_preserve=yes is set on those rows.

The Nginx map rewrites ^/legacy/(\w+)/(.*)$ → /new/$1/$2 and appends $is_args$args, so oldapp.example.com/blog/post-1?utm_source=newsletter returns 301 to app.example.com/resources/post-1?utm_source=newsletter. A staging curl -I -L confirms 200 https://app.example.com/resources/post-1?utm_source=newsletter in a single hop, proving both routing and attribution survive.

Verification

Validate schema integrity and live routing before DNS propagates.

# Detect duplicate source URLs that cause unpredictable routing
awk -F',' 'NR>1 {print $1}' mapping.csv | sort | uniq -d

# Parse access logs for live status/path anomalies post-deploy
awk '{print $9, $7}' access.log | sort | uniq -c | sort -nr | head -20

# Watch 5xx spikes during the transition window
journalctl -u nginx --since "5 min ago" | grep -iE 'error|critical'

Pre-deploy checks: confirm every status_code is exactly 301; audit regex for greedy matching that loops dynamic endpoints; align case-sensitivity between dev and production; and verify UTM preservation via $is_args$args.

FAQ

How do I handle legacy URLs with dynamic query parameters during regex mapping? In Nginx, append $is_args$args to preserve the original query string: return 301 /new/$1$is_args$args;. In Apache, add the QSA flag: RewriteRule ^/old/(.*)$ /new/$1 [R=301,L,QSA]. Strip known session or legacy parameters with a separate RewriteCond before the main rule.

How quickly can I revert to legacy routing if traffic drops more than 15% post-launch? Execute git checkout HEAD~1 /etc/nginx/conf.d/migration.conf && nginx -t && systemctl reload nginx. With DNS TTL pre-set to 300 s, full IP reversion propagates within five minutes globally.

Why are 301 redirects showing up as 302 in Google Search Console after deployment? This usually means a misconfigured proxy_pass or a load balancer rewriting the status code. Verify with curl -I https://example.com/legacy-path directly against the origin, and set proxy_redirect off; so the upstream Location header passes through unmodified.

Related

← Back to Traffic & Conversion Mapping