post.py

"""
Facebook Post - Chocodata Facebook Scraper API

Runnable example. It calls the LIVE API and prints the real JSON response.

    pip install requests
    export CHOCODATA_API_KEY="your_key"      # free: 1,000 requests, one-time
    python facebook_scraper_api_codes/post.py

Reads posts published BY PUBLIC BRAND / BUSINESS pages only.

Note: reactions_count, comments_count and shares_count are ALWAYS null. Facebook
does not render post engagement counts to a logged-out request, so the API returns
null rather than a number.

Docs: https://chocodata.com/docs
"""
import json
import os
import sys

import requests

API = "https://api.chocodata.com/api/v1/facebook/post"
KEY = os.environ.get("CHOCODATA_API_KEY")

if hasattr(sys.stdout, "reconfigure"):
    sys.stdout.reconfigure(encoding="utf-8", errors="replace")

if not KEY:
    sys.exit("Set CHOCODATA_API_KEY first. Free key (1,000 requests, one-time): https://chocodata.com")


def _check(r) -> None:
    """Map the API's documented errors onto actionable messages instead of a traceback."""
    if r.status_code == 400:
        issues = r.json().get("issues", [])
        msg = issues[0].get("message") if issues else "check your query string"
        sys.exit(f"400 invalid_params: {msg}")
    if r.status_code == 401:
        sys.exit("401 INVALID_API_KEY: key missing or not recognised. Get one: https://chocodata.com")
    if r.status_code == 402:
        sys.exit("402 INSUFFICIENT_CREDITS: balance exhausted. Top up or upgrade: https://chocodata.com/pricing")
    if r.status_code == 429:
        sys.exit("429 RATE_LIMITED: over your plan's concurrency. Back off and retry.")
    if r.status_code == 502:
        sys.exit("502 extraction_failed: Facebook served no public data for this post. "
                 "Retryable, and you were not charged.")
    r.raise_for_status()


def get_post(url: str = None, page: str = None, post_id: str = None) -> dict:
    """Fetch one public post by permalink, or by page + post_id."""
    params = {"api_key": KEY}
    if url:
        params["url"] = url
    else:
        params["page"], params["post_id"] = page, post_id
    r = requests.get(API, params=params, timeout=90)
    _check(r)
    return r.json()


if __name__ == "__main__":
    permalink = sys.argv[1] if len(sys.argv) > 1 else \
        "https://www.facebook.com/designrush/posts/1858081705614138/"
    post = get_post(url=permalink)
    print(json.dumps(post, indent=2, ensure_ascii=False)[:1400])
    print()
    caption = (post.get("caption") or "").replace("\n", " ")
    print(f"{post['author']} | post {post['post_id']} | {caption[:60]}...")
    print(f"engagement: reactions={post['reactions_count']} comments={post['comments_count']} "
          f"shares={post['shares_count']}  <- always null logged-out, by Facebook's design")