Skip to main content

​
Overview

The Facebook Client integration retrieves public page metadata using the Facebook Graph API v19.0. It does not use HTML scraping or login flows, and operates entirely through official API endpoints.

​
Authentication

The client requires Facebook API credentials configured via environment variables:
  • FACEBOOK_APP_ID - Facebook App ID
  • FACEBOOK_APP_SECRET - Facebook App Secret
  • FACEBOOK_ACCESS_TOKEN - (Optional) Access token. If not provided, will auto-generate using {APP_ID}|{APP_SECRET} format
Missing credentials will result in an error response. Ensure all required environment variables are set before making requests.

​
Core Function

​
get_facebook_page_data()

Retrieves public Facebook Page metadata for a given URL.
​
url
str
required
Facebook page URL. Supports formats:
  • https://facebook.com/SomeBusiness
  • https://www.facebook.com/SomeBusiness/
The function extracts the page identifier (username or ID) using regex pattern matching.

​
Returns

​
platform
str
Always returns "facebook"
​
page_id
str
Unique Facebook Page ID from Graph API
​
name
str
Business or page name
​
description
str
Page description. Falls back from about field to description field
​
category
str
Page category (e.g., “Local Business”, “Restaurant”)
​
followers
int
Total follower count (from fan_count field)
​
website
str
Associated website URL if provided on the page
​
source_url
str
Original URL that was analyzed
​
text
str
Synthesized text field for AI Evaluator compatibility. Combines all metadata into formatted string:
Business Name: {name}
Category: {category}
About: {description}
Followers: {followers}
Website: {website}
​
error
str
Present only when an error occurs. Contains error message

​
Error Handling

The function returns structured error responses instead of raising exceptions: Missing Credentials 
{
  "platform": "facebook",
  "error": "Missing Facebook API credentials (ID, Secret, or Token).",
  "source_url": "https://facebook.com/example"
}
Invalid URL Format 
{
  "platform": "facebook",
  "error": "Could not extract Page identifier from URL: {url}",
  "source_url": "https://facebook.com/example"
}
Graph API Errors (e.g., invalid page, permissions issues) 
{
  "platform": "facebook",
  "error": "Graph API Error (404): ...",
  "source_url": "https://facebook.com/example"
}
Internal Errors 
{
  "platform": "facebook",
  "error": "Internal Error: {exception_message}",
  "source_url": "https://facebook.com/example"
}
All errors are logged to logs/extraction.log with ERROR level severity.

​
Implementation Details

​
Graph API Request

The function queries these specific fields from the Graph API: 
params = {
    "fields": "id,name,about,description,category,fan_count,link,website",
    "access_token": access_token
}

​
URL Pattern Matching

Page identifier extraction uses regex: 
match = re.search(r"facebook\.com/([^/?#]+)", url)
page_identifier = match.group(1).strip()
This pattern handles various URL formats and extracts the username or page ID segment.

​
Timeout Configuration

Requests have a 10-second timeout: 
response = requests.get(graph_url, params=params, timeout=10)
Graph API requests may fail due to rate limits, invalid access tokens, or page privacy settings. Always check for the error field in responses.

​
Integration with Lead Engine

The function integrates with the main extraction system by:
  1. Accepting URLs from the Lead Engine’s URL router
  2. Returning normalized data structure compatible with AI Evaluator
  3. Providing text field for LLM analysis
  4. Maintaining consistent error format across all extractors

​
Example Usage

from facebook_client import get_facebook_page_data

url = "https://www.facebook.com/YourBusiness"
result = get_facebook_page_data(url)

if "error" in result:
    print(f"Error: {result['error']}")
else:
    print(f"Business: {result['name']}")
    print(f"Category: {result['category']}")
    print(f"Followers: {result['followers']}")
    print(f"Description: {result['description']}")

​
Source Reference

Implementation: ~/workspace/source/facebook_client.py:20

Build docs developers (and LLMs) love

Get started for freeTalk to us