seoextract 0.1.0

A lightweight Python SEO audit engine that returns Pydantic structured output.

SEOExtractHF

A lightweight Python SEO audit engine with built-in Google Safe Browsing support.

Returns validated Pydantic structured output that can be directly consumed by AI agents, dashboards, APIs, report generators, and automation pipelines.

---

Features

• Website crawler
• Google Safe Browsing validation
• Technical SEO auditing
• Pydantic structured output
• Page-level SEO metrics
• Site-level SEO scoring
• Severity-based issue detection
• Duplicate title detection
• Duplicate meta description detection
• Canonical tag detection
• Viewport detection
• Schema.org detection
• Image alt-text validation
• Internal linking analysis
• Thin content detection

---

Installation

pip install seoextracthf

or install from source

pip install -e .

---

Requirements

• Python 3.10+
• Google Safe Browsing API Key

---

Google Safe Browsing Setup

SEOExtractHF checks every website against Google's Safe Browsing service before crawling.

If Google reports the website as unsafe, crawling is stopped automatically.

If no Google Safe Browsing API key is provided, safe_browsing.is_safe will be None.

Option 1 (Recommended)

Create a .env file.

.env

Add your API key.

GOOGLE_SAFE_BROWSING_API_KEY=YOUR_API_KEY

SEOExtractHF automatically loads the API key.

No additional code is required.

---

Option 2

Pass the API key manually.

from seoextracthf import SEOExtract

result = SEOExtract.audit(
    "https://example.com",
    safe_browsing_api_key="YOUR_API_KEY"
)

When an API key is supplied manually, the .env file is not used.

---

Quick Start

from seoextracthf import SEOExtract

result = SEOExtract.audit(
    "https://example.com"
)

print(result.model_dump_json(indent=2))

---

Returned Object

SEOExtractHF returns a validated Pydantic model.

AuditResult
│
├── url
├── audit_date
├── pages_crawled
├── site_score
├── grade
├── total_issues
├── critical_count
├── warning_count
├── info_count
├── pages
├── issues
└── safe_browsing

---

Example

from seoextracthf import SEOExtract

result = SEOExtract.audit("https://example.com")

print(result.site_score)
print(result.grade)
print(result.safe_browsing)

for issue in result.issues:
    print(issue.issue_type)

---

Safe Browsing Result

{
    "is_safe": True,
    "threats": [],
    "error": None
}

If Google reports a threat:

{
    "is_safe": False,
    "threats": [
        "MALWARE"
    ],
    "error": None
}

SEOExtractHF immediately stops crawling unsafe websites.

---

Current SEO Checks

Page Quality

• Title validation
• Meta description validation
• H1 validation
• Thin content detection

Technical SEO

• Canonical tag
• Viewport meta tag
• Schema.org JSON-LD
• HTTP status validation

Images

• Missing ALT attributes

Links

• Internal link analysis

Site-wide Checks

• Duplicate titles
• Duplicate meta descriptions

Security

• Google Safe Browsing validation

---

Example Output

AuditResult(
    site_score=91.0,
    grade="A",
    total_issues=4,
    pages_crawled=15
)

---

Project Structure

seoextracthf/
│
├── crawler.py
├── parser.py
├── rules.py
├── scorer.py
├── safe_browsing.py
├── models.py
└── __init__.py

---

Designed For

SEOExtractHF is designed to be used inside:

• AI SEO Agents
• LangGraph workflows
• FastAPI applications
• Streamlit dashboards
• Report generators
• CI/CD quality checks
• Data pipelines
• SEO automation tools

---

Dependencies

• beautifulsoup4
• lxml
• requests
• pydantic
• python-dotenv

---

License

MIT License

---

Author

Britto K

GitHub:

https://github.com/Britto1221# seoextract