SEO report API with cURL: audit a site and read the findings

#!/usr/bin/env bash
# Audit one site with the SEOReport API and print its top three fixes.
# Usage: SEOREPORT_API_KEY=... bash recipe.sh [https://example.com]
# Needs bash, curl 7.55 or later (for -H @file) and jq.
set -euo pipefail

API="https://seoreport.dev/api/v1/reports"
MAX_WAIT_SECONDS=300 # stop waiting after five minutes
DEFAULT_POLL_MS=5000 # used only when the API sends no pollAfterMs
TARGET="${1:-https://example.com}"

if [ -z "${SEOREPORT_API_KEY:-}" ]; then
  echo "Set SEOREPORT_API_KEY to an API key from your SEOReport plan." >&2
  exit 2
fi

# Send the key as a header file so it never sits in curl's argv, where ps shows
# it to every local user. printf is a shell builtin, so it spawns no process.
auth() { printf 'Authorization: Bearer %s\n' "$SEOREPORT_API_KEY"; }

WORK=$(mktemp -d)
trap 'rm -rf "$WORK"' EXIT

# call METHOD URL [curl args...]: body to $WORK/body, headers to $WORK/headers,
# and the HTTP status on stdout.
call() {
  local method=$1 url=$2
  shift 2
  curl -sS -X "$method" "$url" -H @<(auth) -H "Accept: application/json" \
    -A "seoreport-recipe-curl/1" --max-time 60 \
    -o "$WORK/body" -D "$WORK/headers" -w '%{http_code}' "$@"
}

# refuse STATUS: print the API's own code and message, then stop.
refuse() {
  if ! jq -e . "$WORK/body" >/dev/null 2>&1; then
    echo "SEOReport: HTTP $1: not JSON: $(head -c 200 "$WORK/body")" >&2
    exit 1
  fi
  local line retry
  line=$(jq -r --arg s "$1" '"\(.code // .errorCode // ("HTTP_" + $s)) (HTTP \($s)): \(.error // "no message")"
    + (if .ctaUrl then " -> https://seoreport.dev\(.ctaUrl)" else "" end)' "$WORK/body")
  retry=$(awk 'tolower($1) == "retry-after:" { print $2 }' "$WORK/headers" | tr -d '\r')
  if [ -n "$retry" ]; then line="$line [retry after ${retry}s]"; fi
  echo "SEOReport: $line" >&2
  exit 1
}

# 1. Create the report (or reuse the one this account already has).
STATUS=$(call POST "$API" -H "Content-Type: application/json" \
  --data-binary "$(jq -nc --arg url "$TARGET" '{url: $url}')")
if [ "$STATUS" -ge 400 ] || [ "$(jq -r '.success' "$WORK/body" 2>/dev/null)" != true ]; then
  refuse "$STATUS"
fi
JOB_ID=$(jq -r '.report.jobId' "$WORK/body")
STATE=$(jq -r '.report.status' "$WORK/body")
POLL_MS=$(jq -r --argjson d "$DEFAULT_POLL_MS" 'if (.pollAfterMs // 0) > 0 then .pollAfterMs else $d end' "$WORK/body")
echo "job $JOB_ID: $STATE"

# 2. Poll politely until the job leaves queued/running, with a hard cap.
DEADLINE=$((SECONDS + MAX_WAIT_SECONDS))
while [ "$STATE" = queued ] || [ "$STATE" = running ]; do
  WAIT=$(((POLL_MS + 999) / 1000))
  if [ $((SECONDS + WAIT)) -gt "$DEADLINE" ]; then
    echo "SEOReport: gave up after ${MAX_WAIT_SECONDS}s; job $JOB_ID is still $STATE" >&2
    exit 1
  fi
  sleep "$WAIT"
  STATUS=$(call GET "$API/$JOB_ID")
  if [ "$STATUS" -ge 400 ] || [ "$(jq -r '.success' "$WORK/body" 2>/dev/null)" != true ]; then
    refuse "$STATUS"
  fi
  STATE=$(jq -r '.report.status' "$WORK/body")
  if [ "$(jq -r '.stuck // false' "$WORK/body")" = true ]; then
    echo "SEOReport: job $JOB_ID stopped making progress; start a new report" >&2
    exit 1
  fi
  POLL_MS=$(jq -r --argjson d "$DEFAULT_POLL_MS" 'if (.pollAfterMs // 0) > 0 then .pollAfterMs else $d end' "$WORK/body")
done

if [ "$STATE" != completed ]; then
  jq -r --arg st "$STATE" '"SEOReport: report \($st): \(.error.code // $st): \(.error.message // "")"
    + (if .error.retryable then " (retryable)" else "" end)' "$WORK/body" >&2
  exit 1
fi

# 3. Download the JSON diagnosis and keep a copy.
STATUS=$(call GET "$API/$JOB_ID/download?format=json")
if [ "$STATUS" -ge 400 ]; then refuse "$STATUS"; fi
OUT="seoreport-$JOB_ID.json"
cp "$WORK/body" "$OUT"

# 4. Print the score, the band and the first three open findings.
jq -r '
  "\(.targetUrl): \(.score.overall)/100 (\(.score.band))",
  "open issues: \(.openIssues.total), pages analysed: \(.pagesAnalyzed)",
  ([.findings[] | select(.status == "fail" or .status == "warn")][:3][]
    | "\n#\(.rank) [\(.severity // .status)] \(.title) (\(.area.name))\n   Fix: \(.fix)"),
  (.message // empty)
' "$OUT"
echo
echo "full diagnosis saved to $OUT"

job 3f6c2a1e-8d4b-4c7a-9e21-5b0d7f4a6c18: queued
https://example.com: 64/100 (mixed)
open issues: 9, pages analysed: 24

#1 [high] Canonical tag missing (URLs & Redirects)
   Fix: Add a canonical link element or Link HTTP header pointing to the preferred URL for this page. This is a strong canonicalization signal that helps search systems understand which version represents duplicate or very similar content; the declared URL remains a preference, not a guarantee.

#2 [high] Meta description missing (On-Page SEO)
   Fix: Add a concise, page-specific meta description that accurately describes the visible content. Search systems may use it for a result snippet when it is more helpful than text taken from the page.

#3 [high] Render parity mismatch (Crawl & Index)
   Fix: Ensure raw HTML and rendered DOM contain the same critical SEO elements (title, H1, canonical, meta description, structured data). If content is injected by JavaScript, move it to server-side rendering so crawlers see it immediately.

full diagnosis saved to seoreport-3f6c2a1e-8d4b-4c7a-9e21-5b0d7f4a6c18.json