SEO automation can save real time, but it cannot make a site rank faster. Google's own SEO Starter Guide says there are no secrets that will automatically rank a site first, and that some changes take effect in hours while others take months. What automation can do is find the work: pages with missing titles, duplicate descriptions, broken internal links, or falling clicks. A person then decides what to change.
This guide draws that line. It automates reading and drafting, and it keeps decisions and publishing with a person. The tools are a small audit script you can run on your own built pages, the Search Console API within its documented limits, and an AI assistant that drafts alternatives for review. It does not claim a traffic gain or a time saving, because both depend on your site. For choosing which topics deserve pages in the first place, see the keyword research guide.
What is worth automating
Good candidates share two traits: the task is repetitive, and a mistake is cheap to catch.
- Reading Search Console data on a schedule, so you see which pages gained or lost clicks and impressions.
- Auditing built pages for basics that are easy to get wrong across many pages.
- Listing candidates for a human to look at, such as pages with many impressions and a modest click-through rate.
- Drafting alternatives for titles and descriptions, to review.
Poor candidates are the decisions themselves: what a page should say, whether a claim is true, whether to merge two pages, and whether a change worked.
The Search Console API has limits
If you pull data through the API, plan around its documented usage limits. Search Analytics has load quotas measured in 10-minute and daily chunks, plus a limit of 1,200 queries per minute per site and per user. The page says queries are expensive when they group or filter by page or by query string, and the most expensive group by both. Cost also rises with the date range, and the advice for staying within quota includes avoiding requerying the same data. For the URL Inspection API the page lists 2,000 queries per day and 600 per minute per site. If you hit a quota error, the page says to wait and spread queries out.
The practical design is simple: request only the date ranges you need, store results locally, request the new days only, and run on a schedule, not in a loop.
An on-page audit you can run on built HTML
The script below walks a folder of built .html files and reads them. It never edits anything. It uses Python's standard library, so there is nothing to install. For each page it checks:
- a missing
<title>, a vague title such as "Home", a word repeated three or more times, and a title shared with another page; - a missing or empty meta description, or one shared with another page;
- zero or several
<h1>elements; - images with no alt text;
- a
robotsmeta tag containing noindex or nofollow; - a missing canonical link;
- internal links whose target is not a file in the folder. A link that starts with a slash is read from the site root, not from the folder of the page that holds it. Links to images, stylesheets and PDFs count as found when the file exists. Links with a scheme or a host, bare
#anchors,mailto:andtel:are skipped, and the part after#in a link is not checked, so a link to a missing section of an existing page passes.
The title is read only from a <title> element outside any inline <svg>, because an SVG's own <title> is an accessible name for the graphic and not the page title.
These rules follow Google's title link guidance. The guidance says every page should have a <title> element, titles should be descriptive and concise, there is no length limit but display is truncated, keyword stuffing and repeated or boilerplate titles should be avoided, and the main title should be clear, for instance in the first visible <h1>. It also says Google uses several sources to choose the title link it shows, so a good <title> influences the result but does not fix it.
"""onpage_audit.py: audit a folder of built HTML pages for on-page basics. Standard library only. Reads files, never edits them.
python onpage_audit.py site_dir [--fail-on-noindex]
Per page: missing or boilerplate <title> (an inline <svg> title is ignored), a title word repeated many times,
titles shared with other pages, missing, empty or shared meta description, zero or several <h1>, images without alt,
noindex or nofollow robots meta, canonical link missing, and internal links whose target file is not in the folder
(root-relative links resolve from the site root; images, CSS and PDFs count when the file exists; #fragments are not checked).
Rules come from Google's title link guidance and general hygiene. A clean audit does not mean a page will rank.
Exit code 0 = no flags, 1 = flags, 2 = bad folder.
"""
import os
import re
import sys
from collections import Counter, defaultdict
from html.parser import HTMLParser
from urllib.parse import unquote, urlparse
class Page(HTMLParser):
def __init__(self):
super().__init__()
self.title, self.desc, self.canonical, self.robots = "", None, None, ""
self.h1, self.imgs_no_alt, self.links = 0, 0, []
self._in_title, self._svg = False, 0
def handle_starttag(self, tag, attrs):
a = dict(attrs)
if tag == "svg":
self._svg += 1
elif tag == "title" and not self._svg:
self._in_title = True
elif tag == "meta" and (a.get("name") or "").lower() == "description":
self.desc = (a.get("content") or "").strip()
elif tag == "meta" and (a.get("name") or "").lower() == "robots":
self.robots = (a.get("content") or "").lower()
elif tag == "link" and (a.get("rel") or "").lower() == "canonical":
self.canonical = a.get("href")
elif tag == "h1":
self.h1 += 1
elif tag == "img" and not (a.get("alt") or "").strip() and a.get("alt") != "":
self.imgs_no_alt += 1
elif tag == "a" and a.get("href"):
self.links.append(a["href"])
def handle_endtag(self, tag):
if tag == "svg":
self._svg = max(0, self._svg - 1)
elif tag == "title":
self._in_title = False
def handle_data(self, data):
if self._in_title:
self.title += data
BOILERPLATE = {"home", "untitled", "document", "page", "index"}
def resolve(page_rel, href_path):
"""Map a link path to a path relative to the site root. A leading slash means the site root,
not the folder of the page that holds the link. Returns '' for the root itself."""
path = unquote(href_path)
joined = path.lstrip("/") if path.startswith("/") else os.path.join(os.path.dirname(page_rel), path)
target = os.path.normpath(joined).replace(os.sep, "/")
return "" if target == "." else target
def audit(root):
files, all_files = {}, set()
for dp, _, names in os.walk(root):
for n in names:
rel = os.path.relpath(os.path.join(dp, n), root).replace(os.sep, "/")
all_files.add(rel)
if n.endswith(".html"):
files[rel] = os.path.join(dp, n)
pages = {}
for rel, full in files.items():
p = Page()
p.feed(open(full, encoding="utf-8", errors="replace").read())
pages[rel] = p
titles, descs = defaultdict(list), defaultdict(list)
for rel, p in pages.items():
if p.title.strip():
titles[p.title.strip().lower()].append(rel)
if p.desc:
descs[p.desc.lower()].append(rel)
flags = defaultdict(list)
for rel, p in pages.items():
t = p.title.strip()
if not t:
flags[rel].append("no <title>")
elif t.lower() in BOILERPLATE:
flags[rel].append("title %r is too vague" % t)
else:
top = Counter(re.findall(r"[a-z']{4,}", t.lower())).most_common(1)
if top and top[0][1] >= 3:
flags[rel].append("title repeats %r %d times" % top[0])
if t and len(titles[t.lower()]) > 1:
flags[rel].append("title shared with %s" % ", ".join(x for x in titles[t.lower()] if x != rel))
if not p.desc:
flags[rel].append("no meta description (missing or empty)")
elif p.desc and len(descs[p.desc.lower()]) > 1:
flags[rel].append("meta description shared with another page")
if p.h1 == 0:
flags[rel].append("no <h1>")
elif p.h1 > 1:
flags[rel].append("%d <h1> elements: is the main title clear?" % p.h1)
if p.imgs_no_alt:
flags[rel].append("%d image(s) without alt text" % p.imgs_no_alt)
if "noindex" in p.robots or "nofollow" in p.robots:
flags[rel].append("robots meta says %r" % p.robots)
if not p.canonical:
flags[rel].append("no canonical link")
for href in p.links:
u = urlparse(href)
if u.scheme or u.netloc or href.startswith(("#", "mailto:", "tel:")) or not u.path:
continue
target = resolve(rel, u.path)
index = (target + "/index.html").lstrip("/")
if target not in all_files and target + ".html" not in all_files and index not in all_files:
flags[rel].append("internal link to %s not found" % href)
return pages, flags
def main(argv):
if len(argv) < 2 or not os.path.isdir(argv[1]):
print("usage: onpage_audit.py site_dir [--fail-on-noindex]", file=sys.stderr)
return 2
pages, flags = audit(argv[1])
for rel in sorted(pages):
for f in flags.get(rel, []):
print("%s: %s" % (rel, f))
n = sum(len(v) for v in flags.values())
print("%d pages, %d flags" % (len(pages), n))
if "--fail-on-noindex" not in argv:
n -= sum(1 for v in flags.values() for f in v if f.startswith("robots meta"))
return 1 if n > 0 else 0
if __name__ == "__main__":
sys.exit(main(sys.argv))
What it found on synthetic pages
The script was run on four small synthetic pages built with deliberate problems. It reported 11 flags. The home page and the chain page shared a title, and the home page and the brake page shared a description. The brake page had no title, an image with no alt attribute, and a link to a page that did not exist. The chain page had no canonical link. The draft page repeated the word "brake" four times in its title, had two <h1> elements, and carried a noindex robots tag. A missing folder returned a separate exit code. The noindex flag is informational by default, since a draft is supposed to be excluded from search, and it only fails the run with --fail-on-noindex. That option matters when you are checking that a page you want indexed was not left noindexed by mistake.
A second synthetic test ran the code exactly as printed above on a seven-page built folder with a blog/ subfolder, an image, a PDF and a stylesheet. Root-relative links from pages inside blog/ (such as /blog/b.html, /img/chart.png and /files/guide.pdf), ../ links, a directory link, /, a link ending in #sec and a protocol-relative //cdn link were all treated as found or skipped. The three real misses were flagged: a missing page, a missing PDF and a relative image path that does not exist from inside blog/. A blank content="" description, a whitespace-only description and a page with no description tag were each flagged, and the blank ones were not reported as a shared description. A page whose only <title> sat inside an inline SVG was reported as having no title, and SVG titles did not leak into the titles of other pages. The earlier version of the script, run on the same folder, reported valid links as missing and missed all three description and title cases. The result was 8 flags across 7 pages. Anchor fragments are not checked, so a link to a missing section of an existing page still passes.
The script has limits. It reads static HTML and will not see content that is added by scripts after the page loads. It does not judge whether a title is accurate or appealing, and it does not check structured data or page speed. It finds the cheap mistakes.
Where AI fits: drafting, never publishing
Google's guidance on generative AI content says that models predict likely word sequences instead of retrieving facts, so outputs may contain inaccuracies, and that manual review applies to metadata too, including title elements, meta descriptions, structured data, and image alt text. That is the rule for the whole workflow: an AI draft of a title or description is a suggestion, and a person checks it against the page before it goes live.
A prompt for a rewrite, as plain text:
Here is a page's current title, meta description and the first 300 words of
the page. Suggest three alternative titles and one meta description that
describe what the page actually covers. Do not add claims, numbers or
promises that are not in the text. Keep titles distinct from each other and
avoid repeating a word more than once.
[paste page details]
Then check each suggestion against the page. Does it say what the page delivers? Does it avoid repeating the site name or boilerplate? Does it keep the real topic words? If you have twenty pages to fix, do them in a batch and review the batch, not each one blindly.
Scaling is where the risk sits. The same Google guidance warns that using generative AI tools to produce many pages without adding value may violate its spam policy on scaled content abuse. Rewriting metadata for existing pages is not the same thing, but mass-producing thin new pages to chase queries is.
Measuring a change without fooling yourself
After you change a title or description, resist reading the next few days. The Starter Guide suggests waiting a few weeks to assess whether work had beneficial effects, noting that not all changes produce a noticeable impact. To keep the comparison fair:
- Write down the change and the date.
- Compare equal windows before and after in Search Console, using weekly or monthly granularity to smooth out weekends and holidays.
- Look at the same pages and queries. Impressions can change because demand changed, not because of your edit.
- Change one kind of thing at a time where you can, such as titles for one set of pages.
- Accept a null result. If nothing moved, that is information.
A rise in clicks after a title change can come from seasonality, a news event, or a competitor's change. Association is not causation, and a handful of pages gives you a small sample.
A worked example
A small blog runs the audit and gets 40 flags across 25 pages. The owner sorts them: ten duplicate titles from a template, six missing alt texts, three broken internal links, and the rest minor. The broken links and the template titles are fixed first, since they are plain errors. The AI assistant drafts new titles for the ten pages sharing a template title. The owner rewrites four, rejects three that overstate what the pages cover, and accepts three. The changes are published together, with the date written down. Four weeks later, the owner compares clicks and impressions for those ten pages with the four weeks before, and notes which results are too small to read.
What goes wrong
- Automatic publishing of AI rewrites. A wrong claim in a title is public the moment it ships.
- Over-trusting the audit. A clean report is not a ranking.
- Quota errors from greedy queries. Pull less data, less often.
- Chasing every flag. Fix errors first. Style preferences can wait.
- Noindex left behind. After a staging launch, check what is excluded on purpose.
- Deciding too soon. Weeks, not days.
Limits
This guide describes a way of working. It does not predict results, and Google's pages and the API limits can change. The audit covers static HTML basics only. A site built mostly with scripts needs a different check, such as the URL Inspection tool in Search Console.
A next step
Build your site to a local folder and run the audit. Fix the plain errors by hand first: missing titles, broken links, and duplicate titles. Then choose one small group of pages for an AI-drafted title test, review every draft, publish, write down the date, and look again in a month.
Sources
- Google Search Central, Influencing your title links in search results: title element best practices, no length limit with truncation, stuffing and boilerplate, the main title, and multiple sources for title links.
- Search Console API, Usage limits: Search Analytics load and rate quotas, URL inspection quotas, and advice on reducing load.
- Google Search Central, Using generative AI content: inaccuracies, manual review including metadata, and scaled content abuse.
- Google Search Central, SEO Starter Guide: no secrets to rank first, and waiting a few weeks to assess changes.

