Metadata-Version: 2.4
Name: serpx-seo-tools
Version: 1.0.0
Summary: Practical technical SEO audits and offline competitor keyword gap analysis for Python and the CLI.
Author: SerpX
License-Expression: MIT
Project-URL: Homepage, https://serpx.ai
Project-URL: Competitor Keyword Research, https://serpx.ai/blog/competitor-keyword-research
Project-URL: SEO Tools, https://serpx.ai/tools
Keywords: seo,technical-seo,seo-audit,keyword-gap,competitor-keyword-research,meta-tags,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests<3,>=2.31
Requires-Dist: beautifulsoup4<5,>=4.12
Provides-Extra: dev
Requires-Dist: pytest<10,>=8; extra == "dev"
Requires-Dist: build<3,>=1.2; extra == "dev"
Requires-Dist: twine<7,>=5; extra == "dev"
Dynamic: license-file

# 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](https://serpx.ai)**, 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.

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

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

```bash
python -m pip install -e .
```

## Quick start

### Inspect a web page

```bash
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

```bash
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:

```csv
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`.

```bash
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:

| Category | Definition |
| --- | --- |
| Missing | Competitor has the keyword, your CSV does not |
| Weak | Your reported ranking is worse than the threshold and a competitor outranks you |
| Shared | Keyword appears in both datasets and is not marked weak |
| Unique | Your CSV has a keyword that no supplied competitor CSV contains |

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](https://serpx.ai/blog/competitor-keyword-research)**. The article explains how to validate export data and turn gaps into an editorial plan.

## Python API

```python
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

```bash
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](https://pypi.org/). See `PUBLISHING.md` for full instructions.

## Resources

- [SerpX: AI-powered SEO platform](https://serpx.ai)
- [Competitor Keyword Research: methodology and examples](https://serpx.ai/blog/competitor-keyword-research)
- [SerpX SEO tools](https://serpx.ai/tools)

## License

MIT. See [LICENSE](LICENSE).
