Booksy scraper with Python and Apify

Run Booksy Business Data Scraper from Apify's web interface without writing code, or call it from Python, JavaScript or cURL to collect structured Booksy business listings and profiles across 16 countries plus an optional New York regional profile.

Open Booksy Business Data Scraper on Apify

What this repository helps you do

• Discover Booksy businesses by country profile and category.
• Collect listing records or full business profiles with ratings, services, prices, opening hours, locations and photos when Booksy returns them.
• Export the Dataset to JSON or CSV for directories, market research, enrichment and local-business analysis.

The hosted Actor refreshes active categories at run time, deduplicates businesses across regional results and uses regional fan-out for high-volume categories when Booksy exposes the required facets.

Example result

The repository includes a sanitized example in data/sample-output.json and a flat tabular version in data/sample-output.csv.

{
  "status": "success",
  "profile": "us",
  "country": "USA",
  "category": "hair-salon",
  "mode": "listing",
  "businessId": 900001,
  "recordKey": "us:1:900001",
  "business": {
    "name": "Example Booksy Studio",
    "location": {"city": "Example City"},
    "reviews_count": 43,
    "reviews_stars": 5,
    "service_categories": [{"services": [{"name": "Signature haircut", "price": 35}]}]
  }
}

Run without code

You can run the hosted Actor directly from the Apify web interface.

1. Open Booksy Business Data Scraper on Apify.
2. In the Input tab, choose one or more country profiles and optionally enter category slugs such as hair-salon for the US profile.
3. Choose listings for search records or details to fetch each discovered business profile. Add a per-category limit for a small first run.
4. Click Start and monitor the progress log.
5. Open the Dataset tab and export the results as JSON or CSV.

Use docs/no-code-guide.md for the field-by-field walkthrough and data/sample-input.json for a small first test.

Try it with Apify's free plan

Apify's Free plan includes $5 in monthly prepaid usage for the Apify Store or your own Actors and does not require a credit card to start. A small test of Booksy Business Data Scraper can use that credit while it is available; it is not unlimited free usage. Unused credits expire at the end of the billing cycle. Check current Apify pricing before a larger run.

Quick start for developers

Install the Apify client, set APIFY_API_TOKEN, and run the example:

pip install -r examples/python/requirements.txt
python examples/python/booksy_search.py

The example reads data/sample-input.json, starts the hosted Actor and prints the returned Dataset items. The examples call the hosted Actor only; they do not require this repository to contain the Actor source code.

Input example

{
  "countryCodes": ["us"],
  "mode": "listings",
  "categories": ["hair-salon"],
  "maxBusinessesPerCategory": 1,
  "requestDelayMs": 100,
  "regionSplitThreshold": 9000,
  "maxPagesPerRegion": 1,
  "datasetBatchSize": 1,
  "includeErrors": true,
  "resume": false
}

Omit countryCodes to use the 16 default country profiles. Add ny explicitly for the optional New York regional profile. Category slugs are profile-specific and are refreshed by the Actor at run time. There is no direct city field in the public input: the Actor discovers and traverses the available Booksy regional facets automatically.

See the complete field guide in docs/input-reference.md.

Request examples

cURL

See examples/curl-request.md for a synchronous API request.

Python

See examples/python/booksy_search.py and examples/python/booksy_details.py.

JavaScript

See examples/javascript/request.mjs.

All examples use the hosted Apify Actor. They do not expose a proxy, bypass access controls or require private Actor source code locally.

Output fields

Field	Meaning
status	success for a delivered business row or error for a reported failure item.
profile, country	The Booksy country or regional profile used for the row.
categoryId, category	The resolved Booksy category context.
mode	listing for search output or detail for a profile response.
businessId, recordKey	Booksy business identity and deterministic downstream deduplication key.
business	The business object returned by Booksy; nested fields vary by country and record.
sourceUrl, scrapedAt	Source endpoint context and UTC emission time.
error	Failure status and message when status is error.

Nested business data can include location and coordinates, regions, ratings, review counts, services and variants, prices, durations, opening hours, photos, logos, venue/treatment metadata and other fields returned by Booksy. See docs/output-reference.md for the complete documented contract.

Common use cases

See docs/use-cases.md for complete examples covering:

• building a country- or category-specific business directory;
• comparing beauty, wellness, health and professional-service coverage;
• enriching a local-business workflow with services, prices and ratings;
• exporting repeatable JSON or CSV datasets for analysis.

How to scrape Booksy business listings with Python

Set countryCodes and categories in data/sample-input.json, keep maxBusinessesPerCategory small for the first run, and execute examples/python/booksy_search.py. The script calls the hosted Actor and iterates over its Dataset.

How to collect Booksy salon data by country and category

Use one or more country codes such as us, es, gb or fr, then pass category slugs valid for those profiles. Leave categories empty when you want the Actor to discover the active category catalog. A full all-country details run can be much larger than a bounded listings run, so estimate volume with a per-category limit first.

FAQ

See docs/faq.md for questions derived from the current Actor behavior, including country coverage, city selection, listings versus details, empty results and partial errors.

Limits and pricing

The Actor accepts up to 100,000 for maxBusinessesPerCategory, but the practical result volume depends on the live Booksy category catalog and regional facets. Categories at or above Booksy's national 10,000-result boundary are split by available regional roots when possible. The Actor deduplicates businesses after regional collection and can emit error items without charging them.

Billing uses one business-result event per successfully delivered business Dataset row. The currently configured tiered prices are:

Apify tier	Price per result	Equivalent per 1,000 successful results
FREE	$0.001000	$1.00
BRONZE	$0.000900	$0.90
SILVER	$0.000800	$0.80
GOLD	$0.000750	$0.75
PLATINUM	$0.000750	$0.75
DIAMOND	$0.000750	$0.75

Pricing is time-sensitive. The final charge depends on successful rows and the account tier; check the hosted Actor page before running a large batch.

Hosted version

Use the hosted version for repeatable execution, scheduling, API access and Dataset storage without managing scraping infrastructure:

Open Booksy Business Data Scraper on Apify

Responsible use

Use returned data lawfully and respect Booksy's terms, access rules and applicable privacy obligations. The Actor returns data available through the hosted service and does not grant permission to use personal or business data for a purpose that is not otherwise lawful. Never commit API tokens or other credentials to this repository.

Support

For a problem with the examples, open a GitHub issue with the command, sanitized input and error message. For an execution problem, include the Apify run ID but never include your token. For the hosted Actor, use the Booksy Business Data Scraper support page.

License

This repository is released under the MIT License. See LICENSE.