SerpX SEO Tools

Technical SEO audits and competitor keyword gap analysis for Python and the command line.

SerpX SEO Tools is an open-source utility for developers, SEO consultants, site owners, and agencies who want reproducible checks and transparent keyword comparisons. It includes a page inspector, a small robots-aware website crawler, and offline CSV keyword gap analysis.

The package does not scrape Google, claim live SERP positions, fabricate keyword volumes, or assign arbitrary ranking scores. It works without a SerpX account or API key.

Created by SerpX, an AI-powered SEO platform with website analysis, keyword research, and content optimization tools.

Features

• On-page technical audits: title, meta description, robots, canonical, H1/H2 headings, language, hreflang, Open Graph, JSON-LD presence, image alt attributes, and internal/external/nofollow link inventory.
• Small site crawler: explores same-host HTML links with a page cap, configurable delay and robots.txt checks on by default.
• Competitor keyword gap: merges CSV exports from your own rankings and one or more competitors, categorizing keywords as missing, weak, shared, and unique.
• Automation-ready output: readable terminal summary, JSON for audits/crawls and JSON/CSV for keyword gaps.
• Python API: re-use the analysis functions inside your existing scripts.
• Privacy: keyword exports are processed locally; no upload to SerpX or another analytics endpoint. Only audit/crawl requests contact the URLs you specify.

Installation

Requires Python 3.10 or newer.

python -m pip install serpx-seo-tools
serpx-seo --help

Until the package has been published to PyPI, install from this source directory:

python -m pip install -e .

Quick start

Inspect a web page

serpx-seo audit https://example.com
serpx-seo audit https://example.com --format json --output audit.json

Findings are diagnostic hints. They are not proof of Google indexing, rendering, ranking, or search traffic. Initial HTML can differ from client-rendered HTML.

Crawl a small website

serpx-seo crawl https://example.com --limit 10 --delay 1 --format json --output crawl.json

• Use a conservative rate and respect site policies.
• robots.txt is read before crawling; if it cannot be fetched, the crawl aborts by default.
• Only use --ignore-robots on websites you control or have permission to crawl.
• This is a small HTML link crawler, not a full JavaScript renderer, sitemap indexer, or enterprise auditing service.

Competitor keyword research from CSV exports

Supply CSV exports from a ranking tool or your own datasets. This tool does not access ranking databases; it compares only the data you provide.

CSV input example:

keyword,position,volume,url
seo analysis tools,12,900,https://my-site.example/tools
technical seo audit,4,500,https://my-site.example/audit

Recognized header aliases include keyword / query, position / rank, volume / search volume, and url / page.

serpx-seo gap --own examples/own.csv --competitor examples/competitor.csv
serpx-seo gap --own own.csv --competitor agency-a.csv --competitor agency-b.csv --format csv --output gaps.csv
serpx-seo gap --own own.csv --competitor competitor.csv --weak-threshold 10 --format json --output gaps.json

Categories:

Missing rows do not necessarily mean your site never ranks. They mean only that the keyword is absent from the supplied export. Missing positions stay unknown; estimated search volumes are taken from the input data and are not verified.

For a fuller research workflow covering search competitors, ranking URLs, search intent, keyword gaps, and prioritization, read the SerpX Competitor Keyword Research guide. The article explains how to validate export data and turn gaps into an editorial plan.

Python API

from serpx_seo_tools import analyze_html, audit_url, compare_keyword_exports, read_keyword_csv

report = analyze_html('<html lang="en"><title>Example</title><h1>Hello</h1></html>',
                      'https://example.com/')
print(report['issues'])

# Network requests are made only when you explicitly audit a URL:
# report = audit_url('https://example.com/')

ours = read_keyword_csv('examples/own.csv')
rival = read_keyword_csv('examples/competitor.csv')
gap = compare_keyword_exports(ours, {'competitor': rival})
print(gap['summary'])

Technical scope and limitations

This release checks server-delivered HTML, not a rendered Chrome DOM. It does not fetch Google Search Console or competitor keywords; bring your own lawful CSV exports. It does not provide rankings, click estimates, backlink authority metrics, or Google index status. Canonical tags are hints, not proof of Google's selected canonical. Empty image alt values may be appropriate for decorative images. Multiple H1 elements are not necessarily an SEO fault.

When accessing third-party domains, comply with applicable laws, terms, and robots.txt rules. This is a client-side developer utility and is not intended as a public endpoint for unrestricted URL fetching.

Development

python -m pip install -e '.[dev]'
python -m pytest -q
python -m build
python -m twine check dist/*

Publish distribution artifacts (.whl and .tar.gz), not the ZIP source archive, through PyPI. See PUBLISHING.md for full instructions.

Resources

• SerpX: AI-powered SEO platform
• Competitor Keyword Research: methodology and examples
• SerpX SEO tools

License

MIT. See LICENSE.