Use Facebook Business Page Finder by Keyword & City with Python

Find Facebook business pages by direct URL, or discover them by keyword and city, and get names, categories, addresses, follower counts, contact details, business hours, ratings, and reviews. A Facebook login cookie is recommended for full coverage.

1. Choose the data you need

Review the published README for supported collection modes, examples, and limits. The recipe below uses the current published input definition.

2. Prepare a source-based input

This JSON contains published prefills and required-field defaults. Review every value for your task before running it; it is not a promise of successful collection.

{
  "categoryFilter": [],
  "contactFilter": "any",
  "failOnEmpty": false,
  "includeFailedPages": true,
  "includeReviews": false,
  "locations": [],
  "maxItems": 1,
  "minFollowers": 0,
  "pageIds": [],
  "proxyConfiguration": {
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "useApifyProxy": true
  },
  "searchTerms": [],
  "startUrls": [
    {
      "url": "https://www.facebook.com/nike"
    }
  ],
  "strictLocation": false,
  "verifiedOnly": false
}

Download input.example.json and save your reviewed copy as input.json.

Field	Type	Required	Description
`startUrls`	array	optional	Direct Facebook page URLs to enrich, for example https://www.facebook.com/ozonecoffeeuk. Can be combined with pageIds and searchTerms.
`pageIds`	array	optional	Facebook numeric Page IDs, usernames, or page URLs. Numeric IDs are fetched through https://www.facebook.com/<id>.
`searchTerms`	array	optional	Keywords for Facebook page discovery, for example Coffee Shop or Dentist. Each term is combined with each location as a text query. Facebook keyword search requires a cookie containing both c_user and xs.
`locations`	array	optional	City or region names added to the search query as a soft hint. Facebook does not expose a reliable city filter, so always verify the enriched address. Use strictLocation to drop rows whose address does not contain the location.
`strictLocation`	boolean	optional	Drop pages whose enriched address does not contain the search location. This is a best-effort post-filter, not an exact city boundary.
`categoryFilter`	array	optional	Keep pages whose enriched category contains any of these terms (case-insensitive). Filtering happens after enrichment.
`minFollowers`	integer	optional	Keep pages with at least this many followers. Pages with no follower count are dropped when this is above 0.
`verifiedOnly`	boolean	optional	Keep only pages whose public payload explicitly marks them as verified.
`contactFilter`	string	optional	Keep only lead-ready pages that expose the selected contact field.
`includeReviews`	boolean	optional	Fetch the public reviews tab and include reviews when Facebook exposes them. Adds one request per page. Review coverage is partial.
`includeFailedPages`	boolean	optional	Emit diagnostic rows with errorCode, detailsError, and fieldsFound for pages that cannot be enriched. This prevents silent empty runs.
`failOnEmpty`	boolean	optional	Fail the run when zero page rows are produced. Leave off to finish successfully with diagnostic rows explaining why nothing was found.
`maxItems`	integer	optional	Maximum number of successful page rows. Failed rows do not consume this limit.
`cookies`	string	optional	Optional. Needed only for keyword discovery. c_user and xs are enough. Accepts a JSON array of cookie objects or a raw name=value; name2=value2 Cookie header. Page enrichment works without cookies.
`proxyConfiguration`	object	optional	Used only for keyword discovery. Defaults to Apify residential proxy because Facebook search blocks datacenter IPs. Public page enrichment does not use it.

3. Start an Actor run

Set APIFY_TOKEN in your environment. Python 3.10 or newer is sufficient; this recipe uses no third-party packages.

Execution may incur charges. Review current pricing on Apify. The request asks for a 120-second timeout and a charge limit; these settings are subject to Apify’s pricing and do not guarantee an all-inclusive spending cap.

import json
import os
import urllib.request

# Save the schema-derived example as input.json; review and edit it first.
with open("input.json", encoding="utf-8") as stream:
    actor_input = json.load(stream)

token = os.environ["APIFY_TOKEN"]
request = urllib.request.Request(
    "https://api.apify.com/v2/acts/MBGiwo5b4i8oo7LJo/runs?timeout=120&maxTotalChargeUsd=0.50",
    data=json.dumps(actor_input).encode("utf-8"),
    headers={"Authorization": "Bearer " + token, "Content-Type": "application/json"},
    method="POST",
)
# This starts a potentially billable run. Do not automatically retry this POST.
with urllib.request.urlopen(request, timeout=40) as response:
    run = json.load(response)["data"]
print("Run ID:", run["id"])
print("Status:", run["status"])
# Inspect and download results in Apify Console once the run succeeds.

4. Inspect the actual results

Open the run in Apify Console and wait for a successful completion. Use the published output schema to locate results and the dataset schema to understand declared views. Missing or optional record fields must not be treated as guaranteed values.

One record per Facebook business Page with identity, public contact details, social links, followers, recommendation metrics, open status, business details, Page Transparency data, images, and reviews.

Questions before you run

Which inputs are required?

No top-level fields are marked required in the published schema. Conditional requirements can still apply; check the README.

What does this guide verify?

The fields, prefills, and schema links are rendered from the published build. This is a usage recipe, not a paid live extraction test. Source availability and collection results can vary.

What if the run request times out?

Check Apify Console before retrying. The first request may already have created a run. Do not automatically repeat a run-creation POST.

Open on Apify Full Actor reference

Generated from source build wCZFF2vROhTOg2WsB and its README and schemas. Source changes regenerate this guide; no third-party editorial claims are inferred.