group.py

"""
Facebook Group - 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/group.py

Returns GROUP-LEVEL metadata only: name, description, cover image, and
(intermittently) members_count and privacy. It does not return members, member
posts, or any personal data.

Field coverage, measured on 2026-07-16 over 10 identical calls to one public group:
    name / description / cover_image   10/10
    members_count / privacy             7/10   <- Facebook serves a reduced
                                                  variant about a third of the time
    category                            0/10   <- no logged-out surface at all
Code for the nulls.

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

import requests

API = "https://api.chocodata.com/api/v1/facebook/group"
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 group. "
                 "Retryable, and you were not charged.")
    r.raise_for_status()


def get_group(group: str) -> dict:
    """Fetch a public group's about surface by slug or numeric id."""
    r = requests.get(API, params={"api_key": KEY, "id": group}, timeout=90)
    _check(r)
    return r.json()


if __name__ == "__main__":
    slug = sys.argv[1] if len(sys.argv) > 1 else "InstantPotCommunity"
    g = get_group(slug)
    print(json.dumps(g, indent=2, ensure_ascii=False)[:1200])
    print()
    members = f"{g['members_count']:,}" if g["members_count"] is not None else "null (reduced variant)"
    print(f"{g['name']} | members: {members} | privacy: {g['privacy']} | category: {g['category']}")
    if g["members_count"] is None:
        print("members_count came back null on this call. That happens on roughly 3 of 10 "
              "calls; retry if you need it.")