Extract and Check Open Graph and Twitter Card Meta Tags with Python (Standard Library Only)

#!/usr/bin/env python3
"""Extract Open Graph and Twitter Card meta tags from a URL or local HTML file.

Standard library only. Usage:
    python3 og_meta_check.py https://example.com/page
    python3 og_meta_check.py /path/to/page.html
    python3 og_meta_check.py https://example.com/page --json
"""
import argparse
import json
import sys
import urllib.error
import urllib.request
from html.parser import HTMLParser
from urllib.parse import urljoin

UA = "og-meta-check/1.0 (+https://example.com/contact)"

# Preview checklist used by this script (not identical to every platform's rules).
# Open Graph protocol (ogp.me) requires og:title, og:type, og:image, og:url.
# This checker also treats og:description as required for useful link previews,
# and twitter:card as required for X/Twitter Cards (OG tags may fill in the rest).
REQUIRED = (
    "og:title",
    "og:description",
    "og:image",
    "og:url",
    "twitter:card",
)


class MetaParser(HTMLParser):
    """Collect og:* and twitter:* meta tags from <head>."""

    def __init__(self):
        super().__init__()
        self.tags = {}  # property/name -> list of content values (order preserved)
        self._in_head = False
        self._done = False

    def handle_starttag(self, tag, attrs):
        if self._done:
            return
        name = tag.lower()
        attr = {k.lower(): (v or "") for k, v in attrs}
        if name == "head":
            self._in_head = True
            return
        if name == "body":
            self._done = True
            return
        if not self._in_head or name != "meta":
            return
        prop = attr.get("property") or attr.get("name") or ""
        prop = prop.strip().lower()
        if not (prop.startswith("og:") or prop.startswith("twitter:")):
            return
        content = attr.get("content", "").strip()
        self.tags.setdefault(prop, []).append(content)

    def handle_endtag(self, tag):
        if tag.lower() == "head":
            self._in_head = False
            self._done = True


def fetch_html(src, timeout):
    if src.startswith(("http://", "https://")):
        req = urllib.request.Request(src, headers={"User-Agent": UA})
        with urllib.request.urlopen(req, timeout=timeout) as resp:
            charset = resp.headers.get_content_charset() or "utf-8"
            return resp.read().decode(charset, errors="replace"), resp.geturl()
    with open(src, "r", encoding="utf-8", errors="replace") as fh:
        return fh.read(), src


def first(tags, key):
    vals = tags.get(key) or []
    return vals[0] if vals else None


def analyze(tags, page_url):
    missing = [k for k in REQUIRED if not first(tags, k)]
    warnings = []
    og_image = first(tags, "og:image")
    if og_image and page_url.startswith(("http://", "https://")):
        abs_img = urljoin(page_url, og_image)
        if abs_img != og_image and not og_image.startswith(("http://", "https://")):
            warnings.append(
                f"og:image is relative ({og_image}); resolved as {abs_img}"
            )
    if first(tags, "og:title") and not first(tags, "og:type"):
        warnings.append(
            "og:type is missing; Open Graph protocol lists it as required "
            "(this script still treats the page as checkable without it)."
        )
    card = first(tags, "twitter:card")
    if card and card not in {
        "summary",
        "summary_large_image",
        "app",
        "player",
    }:
        warnings.append(
            f"twitter:card value {card!r} is unusual; common values are "
            "summary, summary_large_image, app, player"
        )
    return {
        "url": page_url,
        "tags": {k: v for k, v in sorted(tags.items())},
        "missing_required": missing,
        "warnings": warnings,
        "ok": not missing,
    }


def print_report(result):
    print(f"URL: {result['url']}")
    print()
    if result["tags"]:
        print("Found tags:")
        for key, values in result["tags"].items():
            for val in values:
                print(f"  {key}: {val}")
    else:
        print("Found tags: (none)")
    print()
    if result["missing_required"]:
        print("Missing required:")
        for key in result["missing_required"]:
            print(f"  - {key}")
    else:
        print("Missing required: (none)")
    if result["warnings"]:
        print()
        print("Warnings:")
        for w in result["warnings"]:
            print(f"  - {w}")
    print()
    print("Status:", "OK" if result["ok"] else "INCOMPLETE")


def main(argv=None):
    p = argparse.ArgumentParser(description=__doc__)
    p.add_argument("source", help="URL or path to an HTML file")
    p.add_argument("--timeout", type=float, default=15.0)
    p.add_argument("--json", action="store_true", help="Print JSON instead of text")
    args = p.parse_args(argv)
    try:
        html, final_url = fetch_html(args.source, args.timeout)
    except urllib.error.HTTPError as e:
        print(f"HTTP error: {e.code} {e.reason}", file=sys.stderr)
        return 2
    except urllib.error.URLError as e:
        print(f"URL error: {e.reason}", file=sys.stderr)
        return 2
    except OSError as e:
        print(f"File error: {e}", file=sys.stderr)
        return 2
    parser = MetaParser()
    parser.feed(html)
    result = analyze(parser.tags, final_url)
    if args.json:
        print(json.dumps(result, indent=2))
    else:
        print_report(result)
    return 0 if result["ok"] else 1


if __name__ == "__main__":
    sys.exit(main())

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>Fallback Title</title>
  <meta property="og:title" content="Sample Product Launch" />
  <meta property="og:description" content="A short description for link previews." />
  <meta property="og:image" content="https://example.com/og.png" />
  <meta property="og:url" content="https://example.com/launch" />
  <meta property="og:type" content="article" />
  <meta name="twitter:card" content="summary_large_image" />
  <meta name="twitter:title" content="Sample Product Launch" />
</head>
<body><h1>Hello</h1></body>
</html>

python3 og_meta_check.py sample.html

URL: sample.html

Found tags:
  og:description: A short description for link previews.
  og:image: https://example.com/og.png
  og:title: Sample Product Launch
  og:type: article
  og:url: https://example.com/launch
  twitter:card: summary_large_image
  twitter:title: Sample Product Launch

Missing required: (none)

Status: OK

<!DOCTYPE html>
<html><head>
<title>Only a title</title>
<meta property="og:title" content="Incomplete page" />
</head><body></body></html>

python3 og_meta_check.py incomplete.html; echo "exit: $?"

URL: incomplete.html

Found tags:
  og:title: Incomplete page

Missing required:
  - og:description
  - og:image
  - og:url
  - twitter:card

Warnings:
  - og:type is missing; Open Graph protocol lists it as required (this script still treats the page as checkable without it).

Status: INCOMPLETE
exit: 1

python3 og_meta_check.py https://example.com/
python3 og_meta_check.py https://example.com/ --json

<meta property="og:title" content="Your page title" />
<meta property="og:description" content="One or two sentences for the preview." />
<meta property="og:image" content="https://example.com/images/og.png" />
<meta property="og:url" content="https://example.com/your-page" />
<meta property="og:type" content="website" />
<meta name="twitter:card" content="summary_large_image" />