⚡ Quick start

pip install facebook-page-info-scraper

from facebook_page_info_scraper import scrape_page

scrape_page("https://www.facebook.com/examplepage")

That is everything. One install, no extras to pick.

📦 What's in the box

from facebook_page_info_scraper import scrape_pages, enrich_records

records = scrape_pages(urls, threads=16)   # scrape
records = enrich_records(records)          # fill in the missing emails

_{Ships with requests, scrapy-playwright, openai (serves OpenAI and DeepSeek) and curl_cffi. The AI step is opt-in and needs only an API key — everything else works without one.}

🎯 What it solves

Getting the data. Give it a Facebook page URL, get back the page's public details — name, category, email, phone, website, address, likes, ratings, opening status. This used to mean driving a real browser: slow, heavy, and it broke every time Facebook changed its CSS. Both engines here read Facebook's own page payload instead, so neither depends on how the page looks.

The holes in it. Facebook pages very often list a website but no email — so a scraped list comes back empty in exactly the column you needed. Contact enrichment visits the website Facebook did list, finds the address there, and scores how much to trust it. In testing that turned about half of those otherwise-dead records into usable contacts.

🚀 Two engines, one result

Both take the same URLs, return the same fields, and run the same extraction. They differ only in how the page is requested.

# 🌐 HTTP — one page or many
from facebook_page_info_scraper import scrape_page, scrape_pages

page  = scrape_page("https://www.facebook.com/examplepage")
pages = scrape_pages(urls, threads=16)

print(page["email"])        # hello@example.com
print(page["page_likes"])   # 12,480

# 🎭 Browser — always a batch, never one at a time
from facebook_page_info_scraper.spider import run

run(urls, threads=8)                    # -> pages_browser.jsonl
run(urls, threads=8, headless=False)    # watch it work

From the command line:

python scrape.py urls.txt --threads 24 --out output.json
python -m facebook_page_info_scraper.spider urls.txt --threads 8 --headed

All options:

scrape_page(url,   want_about=True, timeout=25)
scrape_pages(urls, threads=16, want_about=True, timeout=25)

run(urls, threads=8,                   # pages rendered at once, no cap
    out="pages_browser.jsonl",
    settle_ms=2000,                    # pause after load before reading
    headless=True)

want_about=False reads only the page header — faster, but no email or phone.

The browser engine downloads Chromium (~150 MB) the first time it runs — pip cannot fetch browser binaries, so it happens on first use. One time only.

📧 Contact enrichment

Facebook pages very often list a website but no email. Enrichment visits that website and recovers the missing contact.

from facebook_page_info_scraper import scrape_pages, enrich_records

records = scrape_pages(urls, threads=16)
records = enrich_records(records, threads=8)

records[0]["enriched_email"]        # hello@example.com
records[0]["enriched_confidence"]   # high

It only touches records that need it — a page that already has an email is skipped, and sites shared by several pages are fetched once.

How it works

flowchart TD
    A["Records with a website<br/>but no email"] --> B["Fetch the homepage"]
    B --> C{"Blocked by a<br/>bot challenge?"}
    C -->|yes| D["Retry with a browser<br/>TLS fingerprint<br/>(automatic)"]
    C -->|no| E{"Any email<br/>on the page?"}
    D --> E
    E -->|yes| I["Company inbox,<br/>or a person?<br/>(opt-in, needs a key)"]
    E -->|no| F["Try /contact, /kontakt,<br/>/contacto, /impressum ..."]
    F --> G{"Found now?"}
    G -->|yes| I
    G -->|no| H["no_contact_found"]
    I --> J["Score every candidate"]
    J --> K["enriched_email<br/>+ confidence + reasons"]

    style A fill:#e8f0fe,stroke:#4285f4,color:#111
    style K fill:#e6f4ea,stroke:#34a853,color:#111
    style H fill:#fce8e6,stroke:#ea4335,color:#111
    style D stroke-dasharray: 5 5
    style I stroke-dasharray: 5 5

Both dashed steps ship with the package. The fingerprint retry happens on its own; the LLM step is the only thing you switch on, and it needs just an API key. Leave it off and every address is still found and scored — only the role / personal label is left as unknown.

Nothing is thrown away

Every address found comes back with its score and the reasons behind it, so you pick your own threshold rather than trusting ours:

{
  "email": "hello@example.se",
  "type": "role",              # role | personal | unknown
  "type_source": "deepseek",   # who decided that: provider | shape | none
  "confidence": "high",
  "score": 9,
  "source": "mailto",          # mailto | text
  "found_on": "https://example.se/kontakt",
  "reasons": [
    "mailto link",
    "same brand, different TLD",
    "role address (via deepseek)"
  ]
}

That matters because the obvious filters are wrong. Rejecting a different TLD would discard hello@example.se found on example.com — which is the same company.

high ≥ 6 · medium ≥ 3 · low below that.

Company inbox, or a person?

info@example.com is a company inbox. anna@example.com is a person. Mailing the first is ordinary business; the second is personal data under GDPR — so enrichment labels which is which, and never guesses when it cannot tell.

There is no word list, in any language. A list can never cover them all — an early version of this package missed customerservice, and would never have contained the Finnish asiakaspalvelu or the Dutch klantenservice. A language model answers the question directly instead.

Nothing extra to install — set an API key and switch it on:

enrich_records(records, use_llm=True)                       # picks up your key
enrich_records(records, use_llm=True, provider="deepseek", model="deepseek-v4-flash")  # or choose

Whichever key is present is used. One request covers a whole batch, nothing is written to disk, and if the call fails the run continues with the type reported as unknown. With no key at all, enrichment still finds and scores every address — only the role / personal label is left as unknown.

What you get back

from facebook_page_info_scraper import summarise_enrichment

summarise_enrichment(records)

{
  "records": 40,
  "attempted": 40,
  "found_email": 22,
  "by_confidence": {"high": 13, "medium": 5, "low": 4},
  "by_tier": {"requests": 39, "curl_cffi": 1},
  "unreachable": 11,        # dead domain, expired cert, 404 …
  "no_contact": 7,          # site loaded, no email anywhere
  "challenged": 0,
  "hint": None              # set when something in the environment is missing
}

Fields added to each record

Your original fields are never overwritten — enrichment only adds.

The enrichment dict holds everything, not just the winner:

fetch_outcome is the one to read when a site fails — it separates a dead domain (dns) from an expired certificate (error), a missing page (not_found) and a site that is up and refusing you (challenged).

Options

enrich_records(records,
               threads=8,
               timeout=12,
               only_missing_email=True,
               follow_contact_pages=True,
               use_fingerprint=True,
               use_llm=False,
               provider=None,
               model=None)

One site at a time, if you prefer:

from facebook_page_info_scraper import enrich_site

enrich_site("https://example.com")
enrich_site("https://example.com", use_llm=True, provider="openai")

enrich_site takes the same options as enrich_records, minus threads and only_missing_email — plus session= if you want to supply your own requests.Session. It returns the result dict directly instead of attaching it to a record.

📊 Speed

Measured on the same 183-page list, same machine.

Both engines beat the old Selenium version by a wide margin — HTTP by roughly 50×, the browser engine by about 6× while still running JavaScript.

📥 Input

Any Facebook page URL. These all work with either engine:

https://www.facebook.com/examplepage
https://facebook.com/examplepage                        (no www)
https://www.facebook.com/examplepage/                   (trailing slash)
https://www.facebook.com/pages/Example-Page/100000000000000
https://www.facebook.com/profile.php?id=100000000000000
http://sv-se.facebook.com/pages/Example-Page/100000000000000   (locale subdomain)

📤 Output

Identical from either engine.

{
  "page_name": "Example Store",
  "page_id": "100000000000000",
  "page_category": "Bakery",
  "email": "hello@example.com",
  "phone_number": "+33 1 23 45 67 89",
  "page_website": "https://example.com",
  "address": "1 Example Street\n12345 Sampletown",
  "page_likes": "12,480",
  "talking_about": "215",
  "were_here": "33",
  "recommend_percent": "94",
  "page_review_number": "18",
  "open_status": "Closed now",
  "price_range": "Price Range - $",
  "bio": "Example Store. 12,480 likes ...",
  "image": "https://scontent.xx.fbcdn.net/...",
  "canonical": "https://www.facebook.com/examplepage",
  "locale": "en_US",
  "ok": True
}

Always check ok:

page = scrape_page(url)
print(page.get("page_name")if page.get("ok") else page.get("error"))

One thing to know. email, phone_number and page_website are a string when the page lists one, and a list when it lists several.

"email": "hello@example.com"                          # one
"email": ["sales@example.com", "press@example.com"]   # several
"email": None                                         # none

def as_list(v):
    return [] if v is None else (v if isinstance(v, list) else [v])

🩺 Check your run

One call tells you how a batch went. Works on records from either engine.

from facebook_page_info_scraper import scrape_pages, summarise

records = scrape_pages(urls, threads=16)
summarise(records)

{
  "total": 213,          # records in
  "ok": 211,             # scraped successfully
  "failed": 2,
  "with_about": 164,     # found the About panel
  "with_email": 150,
  "with_phone": 115,
  "with_website": 161,
  "wrong_locale": 0,     # pages Facebook served in another language
  "avg_seconds": 1.44,
  "avg_kb": 533          # bytes actually read, not page size
}

Field counts are measured against ok, not total — dead URLs never drag your extraction numbers down. That makes the two problems easy to tell apart:

Handy as a guard in scheduled jobs:

stats = summarise(records)
if stats["with_email"] / stats["ok"] < 0.60:
    raise SystemExit("email extraction dropped — check for changes")

🔮 Roadmap

The first piece of the AI layer has landed: enrichment can ask a model whether an address is a company inbox or a person, in any language. It sits behind the deterministic work, not in front of it — every address is found and scored by rules, and the model answers only the one question rules cannot: what a word means in a language nobody enumerated.

Next along the same line is free-text extraction for unlabelled About rows in languages whose formatting conventions vary. Rules first, model only where rules come up empty.

⬆️ Upgrading from 1.x

The old Selenium class still works:

pip install facebook-page-info-scraper[selenium]

from facebook_page_info_scraper import FacebookPageInfoScraper
FacebookPageInfoScraper(url).get_page_info()

Either new engine is a recommended replacement — same idea, much faster.

Two output differences:

• page_rate and page_review_number used to be swapped. They are correct now.
• location was a country name; the new address is the full street address.

🤝 Contributing

Contributions are welcome. If you find an issue or have a suggestion, please open an issue or submit a pull request on GitHub.

📝 Notes

• Only public pages. Nothing behind a login.
• Be reasonable with threads — this hits Facebook from your IP.
• Scraping Facebook is against their Terms of Service. Use accordingly.

License

MIT — see LICENSE.txt.