# Booksy Scraper — Salon, Barber & Beauty Business Data (`haketa/booksy-scraper`) Actor

Scrape Booksy local business listings by service and city. Extract salon, barber, spa, nail and beauty business name, full address, GPS coordinates, rating, review count, category, photos and booking badges. Export to JSON/CSV/Excel for local lead generation and market research.

- **URL**: https://apify.com/haketa/booksy-scraper.md
- **Developed by:** [Haketa](https://apify.com/haketa) (community)
- **Categories:** Lead generation, Business
- **Features:** Limited permissions
- **Stats:** 16 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.50 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Booksy Scraper — Salon, Barber, Spa & Beauty Business Lead Extractor

> **Extract structured local-business leads from [Booksy (booksy.com)](https://booksy.com/en-us/) — the leading appointment-booking marketplace for hair salons, barbershops, nail studios, spas, massage therapists, and beauty & wellness professionals across the United States.** This **Booksy scraper** turns any service + US state search (or city search URL) into a clean, deduplicated dataset: **business name, category, full street address, city, GPS coordinates (`latitude`/`longitude`), star rating, review count, cover photo, parent salon-suite/venue name, and booking/payment badges** — with no login and no coding.

Export every result to **JSON, CSV, Excel, or API** with **1,000+ results pagination** unlocked.

[![Apify Actor](https://img.shields.io/badge/Apify-Actor-blue)](https://apify.com/haketa/booksy-scraper)
[![Region](https://img.shields.io/badge/Coverage-All%2050%20US%20States%20%2B%20DC%20%F0%9F%87%BA%F0%9F%87%B8-red)]()
[![Data](https://img.shields.io/badge/Data-Salons%20%C2%B7%20Barbers%20%C2%B7%20Spas-purple)]()
[![Lead Gen](https://img.shields.io/badge/Use%20Case-B2B%20Beauty%20Lead%20Gen-success)]()
[![Speed](https://img.shields.io/badge/Architecture-Fast%20Pure%20HTTP-brightgreen)]()
[![Export](https://img.shields.io/badge/Export-JSON%20%C2%B7%20CSV%20%C2%B7%20Excel-lightgrey)]()

***

### ⚡ At a glance

| Feature | Details |
| :--- | :--- |
| **Target Platform** | [Booksy US (`booksy.com/en-us`)](https://booksy.com/en-us/) |
| **Business Categories** | Hair Salon, Barber, Nail Salon, Eyelashes & Eyebrows, Massage, Spa, Waxing, Makeup, Skin Care, Hair Removal, Braids, Tattoo & Piercing, Wellness (plus All Services) |
| **Geographic Coverage** | Dropdown for **all 50 US States + Washington DC**, nationwide sample mode, or exact city/neighborhood via `startUrls` |
| **Core Data Extracted** | `businessId`, `name`, `category`, `rating` (0–5), `reviewsCount`, `reviewsStars`, `address`, `city`, `latitude`, `longitude`, `imageUrl`, `venueName`, `url` |
| **Commercial Signals** | `isPromoted` (paid placement), `acceptsBooksyPay`, `travelingService` (mobile pros), `bestOfBooksy`, `venueName` (salon suites like Sola Salon) |
| **Pagination & Scale** | 20 businesses/page, up to **10,000 businesses per single search** and **1,000+ multi-state/category expansion** |
| **Deduplication** | Global deduplication by `businessId` across all pages, states, and URLs |
| **Export Formats** | JSON, CSV, Excel (XLSX), HTML, XML, RSS, and Apify REST API |

***

### 📋 Table of contents

- [Why scrape Booksy?](#-why-scrape-booksy)
- [What this Booksy scraper does](#-what-this-booksy-scraper-does)
- [High-value B2B use cases](#-high-value-b2b-use-cases)
- [Input configuration](#-input-configuration)
- [Output sample & field reference](#-output-sample--field-reference)
- [Pagination & 1,000+ scale](#-pagination--1000-scale)
- [How to use (Console & API)](#️-how-to-use-console--api)
- [Pro tips for beauty & wellness lead generation](#-pro-tips-for-beauty--wellness-lead-generation)
- [Honest limitations](#-honest-limitations)
- [FAQ](#-faq)
- [Related scrapers](#-related-scrapers)
- [Changelog](#-changelog)

***

### 🔎 Why scrape Booksy?

**Booksy** powers online appointment scheduling for hundreds of thousands of independent beauty, grooming, and wellness businesses across the United States — barbershops, hair salons, nail bars, med-spas, lash and brow studios, massage therapists, waxing specialists, estheticians, and tattoo artists. Every listing on Booksy represents an active, revenue-generating local business with verified customer reviews, a physical or mobile service area, and digital payment adoption.

Collecting this B2B intelligence manually is tedious. Booksy displays only **20 businesses per page** and spreads state-level and metro-level directories across hundreds of paginated views. Copy-pasting business names, street addresses, GPS coordinates, and review counts by hand simply cannot scale when building regional or nationwide prospect lists.

This **Booksy data extractor** automates the entire workflow. Choose a service category and a US state from the dropdowns — or paste any city-level Booksy search URL — and export a clean, deduplicated table ready for CRM enrichment, territory mapping, or market analysis.

**Common reasons teams scrape Booksy:**

- 💈 **Build Targeted B2B Lead Lists** — source active barbershops, hair salons, nail salons, and spas for wholesale beauty supplies, professional cosmetics, equipment financing, or commercial insurance.
- 💳 **SaaS, POS & FinTech Prospecting** — segment businesses by `isPromoted`, `acceptsBooksyPay`, and `reviewsCount` to identify high-volume merchants paying for growth tools.
- 🏢 **Identify Salon-Suite Tenants (`venueName`)** — spot independent stylists operating inside franchise studio suites (e.g., *Sola Salon Studios*, *Phenix Salon Suites*, *Salons by JC*).
- 🗺️ **Competitor Density & Site Selection** — map every competitor by exact `latitude` and `longitude` before opening a new salon, barbershop, or med-spa location.
- ⭐ **Reputation & Market Benchmarking** — analyze average star ratings (`rating`) and customer review volume (`reviewsCount`) across cities and states.
- 🚐 **Mobile vs. Brick-and-Mortar Segmentation** — filter by `travelingService: true` to separate mobile beauty professionals from fixed storefronts.

***

### ✨ What this Booksy scraper does

- ✅ **No-Code Service & State Dropdowns** — pick from **13 beauty & wellness categories** (or *All services*) and **all 50 US states + DC** (or *All states nationwide sample*) without looking up location codes.
- ✅ **Advanced City URL Mode (`startUrls`)** — paste any Booksy search URL from your browser (e.g., `https://booksy.com/en-us/s/hair-salon/18229_chicago`) to target a specific city, metro area, or neighborhood.
- ✅ **Deep 1,000+ Pagination** — steps through Booksy's business directory at 20 businesses per page (up to Booksy's ~10,000-business cap per query) and automatically expands across state×service combinations on nationwide runs so 1,000+ targets are reached effortlessly.
- ✅ **Global Deduplication** — deduplicates every record by `businessId` across all pages and multiple `startUrls`, guaranteeing 0% duplicate businesses in your dataset.
- ✅ **Rich Reputation Metrics** — captures exact decimal `rating` (e.g., `4.99`), rounded `reviewsStars` (`5`), and total `reviewsCount` (`147`).
- ✅ **Full Location & Geospatial Coordinates** — outputs `address` (street, city, ZIP), `city`, and WGS84 `latitude` / `longitude`.
- ✅ **Salon-Suite & Commercial Flags** — extracts `venueName` (umbrella studio/suite brand), `isPromoted`, `acceptsBooksyPay`, `travelingService`, `bestOfBooksy`, `hasOnlineBooking`, and `staffCount`.
- ✅ **Canonical Business Profile Links** — constructs the direct `https://booksy.com/en-us/...` profile URL for every business.

***

### 🎯 High-value B2B use cases

#### 1. Beauty Supply Distributors & Cosmetics Brands

Filter by `category` (`Hair Salon`, `Barber`, `Nail Salon`, `Eyelashes & Eyebrows`) and sort by `reviewsCount` descending to prioritize established, high-foot-traffic shops with proven client demand.

#### 2. Local Marketing Agencies & B2B SaaS Sales

Businesses with `isPromoted: true` are already spending money on customer acquisition inside Booksy. Combine `isPromoted: true` with `reviewsCount` between 10 and 100 to target growing salons actively investing in marketing.

#### 3. Real Estate & Salon-Suite Franchise Developers

Use `venueName` and GPS coordinates (`latitude`, `longitude`) to map how many independent stylists in a given metro area rent booths inside salon suites versus operating standalone storefronts.

#### 4. Multi-Unit Franchise & Private Equity Roll-Up Screening

Private equity groups, MSOs (Management Services Organizations), and multi-unit salon consolidators use Booksy's review volume (`reviewsCount`), star score (`rating`), and `city`/`address` data to identify independent local market leaders with strong customer retention across high-growth states like Florida, Texas, California, North Carolina, and Georgia.

#### 5. Local SEO, Reputation Management & Web Design Prospecting

Identify talented barbers and stylists who have 100+ glowing customer reviews (`rating >= 4.9`, `reviewsCount >= 100`) on Booksy so you can pitch them website development, Google Business Profile optimization, or social media management.

***

### 📥 Input configuration

All fields are optional. You can run the actor using the dropdowns, paste specific city search URLs into `startUrls`, or leave everything blank for a diverse nationwide sample.

| Field | Type | Default / Prefill | Description |
| :--- | :--- | :--- | :--- |
| `service` | `string` | `""` (All services) | Business category to collect: `hair-salon`, `barber`, `nail-salon`, `eyelashes-eyebrows`, `massage`, `spa`, `waxing`, `makeup`, `skin-care`, `hair-removal`, `braids`, `tattoo-piercing`, `wellness`, or `""` for all services. |
| `location` | `string` | `""` (Nationwide sample) | US state to collect businesses from (covers all 50 states + Washington DC, e.g., `10009_florida`, `10043_texas`, `100003_california`, `9_new-york`). |
| `maxItems` | `integer` | Default: `0` (Prefill: `60`) | Maximum number of unique businesses to collect. Set `0` for no limit (an empty run with no filters defaults to a fast 100-business sample). |
| `startUrls` | `array` | `[]` | Optional list of Booksy search URLs (e.g., `https://booksy.com/en-us/s/hair-salon/18229_chicago`). Overrides `service` and `location` dropdowns when provided. |
| `proxyConfiguration` | `object` | US Apify Proxy | Proxy settings. Apify Proxy (`US`) is enabled by default for reliable US directory access. |

#### Example 1 — Hair salons across California (1,000+ scale)

```json
{
  "service": "hair-salon",
  "location": "100003_california",
  "maxItems": 1000,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyCountry": "US"
  }
}
```

#### Example 2 — Specific US cities via `startUrls` (Chicago & Miami barbershops)

```json
{
  "startUrls": [
    "https://booksy.com/en-us/s/barber/18229_chicago",
    "https://booksy.com/en-us/s/barber/13063_miami"
  ],
  "maxItems": 500,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyCountry": "US"
  }
}
```

#### Example 3 — Nationwide multi-state barber directory (1,200+ leads)

```json
{
  "service": "barber",
  "location": "",
  "maxItems": 1200,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyCountry": "US"
  }
}
```

***

### 📤 Output sample & field reference

Each business is saved as a structured JSON object. Below is a real record from a live California run:

```json
{
  "businessId": "1337219",
  "name": "Hairbykaylamizuta",
  "category": "Hair Salon",
  "rating": 4.99,
  "reviewsCount": 147,
  "reviewsStars": 5,
  "address": "2676 bechelli lane, Redding, 96002",
  "city": "Redding",
  "latitude": 40.56833,
  "longitude": -122.36337,
  "imageUrl": "https://d2zdpiztbgorvt.cloudfront.net/region1/us/1337219/biz_photo/62a6485284c04b6aa45bf7c1953402-hairbykaylamizuta-biz-photo-50ec1cf449cf48d6847760081c4560-booksy.jpeg",
  "staffCount": 0,
  "bestOfBooksy": false,
  "acceptsBooksyPay": false,
  "hasOnlineBooking": false,
  "isPromoted": true,
  "travelingService": false,
  "venueName": "Revive hair studio",
  "url": "https://booksy.com/en-us/1337219_hairbykaylamizuta_hair-salon_134755_redding",
  "searchUrl": "https://booksy.com/en-us/s/hair-salon/100003_california",
  "scrapedAt": "2026-11-10T02:30:00.000Z"
}
```

#### 🗂️ Field reference & coverage table

##### 💈 Core Business Identity & Reputation Fields

| Field | Type | Coverage | Description |
| :--- | :--- | :--- | :--- |
| `businessId` | `string` | 🟢 High (100%) | Unique Booksy numeric business ID (primary deduplication key). |
| `name` | `string` | 🟢 High (100%) | Public business or stylist name. |
| `category` | `string` | 🟢 High (100%) | Primary business category (e.g., `Hair Salon`, `Barber`, `Nail Salon`, `Day Spa`). |
| `rating` | `number` | 🟢 High (~97%) | Exact average review rating on a 0–5 scale (null only for brand-new businesses with 0 reviews). |
| `reviewsCount` | `number` | 🟢 High (~97%) | Total number of verified customer reviews. |
| `reviewsStars` | `number` | 🟢 High (100%) | Rounded star score (`0`–`5`). |
| `imageUrl` | `string` | 🟢 High (~99%) | High-resolution storefront or portfolio cover photo URL. |
| `url` | `string` | 🟢 High (100%) | Canonical Booksy business profile URL (`https://booksy.com/en-us/...`). |

##### 📍 Location & Geospatial Fields

| Field | Type | Coverage | Description |
| :--- | :--- | :--- | :--- |
| `address` | `string` | 🟢 High (100%) | Street address, city, and postal/ZIP code as published on Booksy. |
| `city` | `string` | 🟢 High (100%) | City name. |
| `latitude` | `number` | 🟢 High (100%) | WGS84 GPS latitude for mapping and radius queries. |
| `longitude` | `number` | 🟢 High (100%) | WGS84 GPS longitude for mapping and radius queries. |
| `venueName` | `string` | 🟡 Conditional (~33%) | Parent venue or salon-suite brand (e.g., `"Sola Salon"`, `"Revive hair studio"`). |

##### 🏷️ Commercial Badges & Run Metadata

| Field | Type | Coverage | Description |
| :--- | :--- | :--- | :--- |
| `isPromoted` | `boolean` | 🟢 High (100%) | `true` if the business is running promoted/boosted placement on Booksy. |
| `travelingService` | `boolean` | 🟢 High (100%) | `true` if the provider offers mobile/traveling appointments. |
| `acceptsBooksyPay` | `boolean` | 🟢 High (100%) | `true` if Booksy Pay is flagged on the search listing. |
| `bestOfBooksy` | `boolean` | 🟡 Conditional | Search-feed flag for the "Best of Booksy" badge. |
| `hasOnlineBooking` | `boolean` | 🟡 Conditional | Search-feed online-booking indicator. |
| `staffCount` | `number` | 🟡 Conditional | Staff list count exposed in the bulk search feed. |
| `searchUrl` | `string` | 🟢 High (100%) | The Booksy search URL that yielded this business. |
| `scrapedAt` | `string` | 🟢 High (100%) | ISO 8601 extraction timestamp. |

***

### 🔁 Pagination & 1,000+ scale

- **20 Businesses per Page, Up to 500 Pages per Search** — each search query paginates up to Booksy's 500-page (~10,000-business) ceiling, stopping automatically when your `maxItems` cap is reached or no further pages exist.
- **Multi-State & Multi-Category Expansion for 1,000+ Runs** — when `maxItems > 100` is requested on a nationwide sample run (or an unfiltered state search), the scraper automatically expands across state×service combinations and removes per-URL sample caps so 1,000+ runs never stall early.
- **Global Cross-URL Deduplication** — a global `seen` set tracks every `businessId` across all URLs, states, and categories, ensuring 0% duplicates even when combining overlapping searches.

***

### ⚙️ How to use (Console & API)

#### In Apify Console

1. Open **[Booksy Scraper](https://apify.com/haketa/booksy-scraper)** in Apify Console.
2. Select a **Service / category** (e.g., `Barber`, `Hair salon`, `Nail salon`) and a **Location (US state)** — or paste city search URLs in **Advanced: Booksy search URLs**.
3. Set **Max businesses** (`60` for a quick test, `1000` for a deep pull, or `0` for unlimited).
4. Click **Start** and export your leads to **CSV, Excel, or JSON**.

#### Via Apify API (Python)

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")

run_input = {
    "service": "barber",
    "location": "10009_florida",
    "maxItems": 1000,
}

run = client.actor("haketa/booksy-scraper").call(run_input=run_input)

for biz in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(f"{biz['name']} ({biz['city']}) — ⭐ {biz['rating']} ({biz['reviewsCount']} reviews)")
```

#### Via Apify API (JavaScript / Node.js)

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: 'YOUR_APIFY_TOKEN' });

const run = await client.actor('haketa/booksy-scraper').call({
    service: 'hair-salon',
    location: '10043_texas',
    maxItems: 500,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(`Collected ${items.length} unique Booksy businesses.`);
```

***

### 💡 Pro tips for beauty & wellness lead generation

- **Target a single city with `startUrls`** — search your target city on `booksy.com/en-us` (e.g., Austin, Atlanta, Phoenix, Seattle), copy the URL from your browser's address bar (`https://booksy.com/en-us/s/...`), and paste it into `startUrls`.
- **Parse ZIP codes from `address`** — Booksy formats US addresses as `"Street, City, ZIP"` (e.g., `"2676 bechelli lane, Redding, 96002"`). A simple regex (`/\b\d{5}\b$/`) extracts the 5-digit US ZIP code for territory assignment.
- **Combine `venueName` with `address`** — multiple stylists sharing the same `venueName` and `address` are booth renters inside a salon suite, whereas businesses with `venueName: null` are typically standalone storefronts.

***

### ⚠️ Honest limitations

- **US Market (`booksy.com/en-us`)** — the built-in state dropdown and endpoint target Booksy's United States directory.
- **Search-Feed Scope** — to extract 500–1,000+ businesses in seconds at minimal cost, the actor reads Booksy's structured directory feed rather than visiting each business's individual profile page. Fields like phone number or full price menus (which require per-profile requests) are not included, and compact search-feed flags (`staffCount`, `bestOfBooksy`, `hasOnlineBooking`) often report default `0`/`false` values in the bulk feed.

***

### ❓ FAQ

#### How many businesses can I scrape in a single run?

A single state or metro search on Booksy can return up to **10,000 businesses** (500 pages × 20 per page), and multi-URL or nationwide runs scale even higher. Set `maxItems: 1000` (or `0` for unlimited) to collect full directories.

#### How fast is the Booksy Scraper?

Because it uses pure HTTP requests against structured directory pages without launching a heavy browser, collecting 60–100 businesses typically takes **5–15 seconds**, and 500–1,000 businesses takes **30–90 seconds**.

#### Do I need a Booksy account or API key?

No. All extracted records come from public Booksy directory listings. No login or credentials are required.

#### Can I scrape a specific city instead of a whole US state?

Yes! Search for any city or neighborhood on [booksy.com](https://booksy.com/en-us/), copy the URL from your browser (e.g., `https://booksy.com/en-us/s/nail-salon/18229_chicago`), and paste it into `startUrls`.

#### What export formats are supported?

You can download results as **JSON, CSV, Excel (XLSX), HTML, XML, or RSS**, or push them into **HubSpot, Salesforce, Google Sheets, Make, Zapier, or n8n** via the Apify API.

#### Can I run a nationwide sample across multiple states and services?

Yes. Leave both `service` and `location` set to their default (`""` = All services / Nationwide sample). On a quick run (`maxItems <= 100`), the scraper collects a balanced sample across top US states and beauty categories; when you set `maxItems: 1000+`, it automatically expands across state×service combinations to deliver a large, deduplicated national dataset.

#### How does deduplication work when I provide multiple `startUrls`?

Every business on Booksy has a unique numeric `businessId`. The scraper tracks all seen business IDs across the entire run in memory, so even if two city searches or service categories overlap, each business appears only once in your output dataset.

#### Why are `hasOnlineBooking`, `bestOfBooksy`, or `staffCount` sometimes `false` or `0`?

Those fields are passed through directly from Booksy's compact directory search feed, where Booksy frequently omits detailed per-profile arrays to keep search responses lightweight. Core fields (`businessId`, `name`, `category`, `rating`, `reviewsCount`, `address`, `city`, `latitude`, `longitude`, `imageUrl`, `url`, `isPromoted`) are populated with ~97–100% coverage.

***

### 🔌 Integrations, CRM sync & automation workflows

Connect the **Booksy Scraper** directly to your sales and marketing stack:

| Integration | B2B Lead-Gen Workflow |
| :--- | :--- |
| **HubSpot / Salesforce / Pipedrive** | Route newly discovered salons, barbershops, and med-spas (`isPromoted: true`, `reviewsCount > 25`) directly into regional sales pipelines via Make, Zapier, or n8n. |
| **Google Sheets & Airtable** | Maintain an always-fresh territory directory of beauty & wellness businesses across all 50 US states. |
| **Clay / Apollo Enrichment** | Use `name`, `address`, `city`, and `url` as seed inputs in Clay or Apollo to enrich owner emails, Instagram handles, and phone numbers. |
| **Snowflake / BigQuery / Postgres** | Schedule monthly nationwide pulls to track franchise salon-suite (`venueName`) expansion and review velocity across US metros. |
| **cURL / REST API** | Trigger on-demand scrapes from any backend application or webhook pipeline. |

#### cURL REST API Example

```bash
curl -X POST "https://api.apify.com/v2/acts/haketa~booksy-scraper/runs?token=YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "service": "hair-salon",
    "location": "10009_florida",
    "maxItems": 1000,
    "proxyConfiguration": {
      "useApifyProxy": true,
      "apifyProxyCountry": "US"
    }
  }'
```

***

### 🔗 Related scrapers

Pair Booksy data with our other B2B local-business and directory scrapers:

- [BBB Scraper — Better Business Bureau Leads](https://apify.com/haketa/bbb-scraper)
- [Dun & Bradstreet (D\&B) Scraper](https://apify.com/haketa/dnb-scraper)
- [StyleSeat Scraper — Hair & Beauty Professionals](https://apify.com/haketa/styleseat-scraper)
- [ Vagaro / Salon Directory Scrapers](https://apify.com/haketa)

***

### 📋 Changelog

#### v1.2 (2026-11) — Unlocked 1,000+ Multi-State Pagination & Global Deduplication

- **Unlocked 1,000+ Pagination**: Removed per-URL sample caps when `maxItems > 100` and added automatic multi-service/multi-state URL expansion so 1,000+ business runs never stall on smaller categories.
- **Global Cross-URL Deduplication**: Moved `seen` business ID tracking to the global run scope so multi-URL and multi-state runs guarantee 0% duplicate records.
- **Faster Prefill (`maxItems: 60`)**: Tuned default prefill to 60 businesses (3 pages) for rapid `<15s` verification runs while setting schema default to `0` (unlimited, with 100-item sample cap on empty runs).
- **Documentation Upgrade**: Added `⚡ At a glance` table, emoji-grouped field coverage tables, and changelog.

#### v1.1 (2026-10) — Nuxt 3 `__NUXT_DATA__` Resolver & Canonical URL Builder

- Added deterministic URL location ID extraction with Nuxt 3 dehydrated state fallback.
- Improved canonical business profile URL construction.

#### v1.0 (2026-07) — Initial Release

- Initial release with 13 beauty/wellness service categories and all 50 US states + DC dropdowns.

# Changelog

This Actor's version history is a separate document: https://apify.com/haketa/booksy-scraper/changelog.md

# Actor input Schema

## `service` (type: `string`):

Pick the type of business to collect. Choose "All services" to pull every kind of local beauty & wellness business in the selected location.

## `location` (type: `string`):

Pick a US state to collect businesses from. Choose "All states (nationwide sample)" for a fast, mixed sample across popular states. Covers all 50 states plus DC. For a specific city, use the Advanced start URLs field below.

## `maxItems` (type: `integer`):

Maximum number of businesses to collect. Set 0 for no limit (Booksy caps a single search at ~10,000, and multi-state runs scale higher). Default 0 (an empty run with no limit defaults to a fast 100-business sample).

## `startUrls` (type: `array`):

Optional. Power users can paste specific Booksy search-result URLs (e.g. a single city) to scrape instead of the dropdowns above. Search on booksy.com, then copy the browser URL here — for example https://booksy.com/en-us/s/hair-salon/18229_chicago. When set, these URLs take priority over the Service and Location dropdowns.

## `proxyConfiguration` (type: `object`):

Booksy serves US business data — a US proxy is recommended. Apify Proxy (US) is on by default.

## Actor input object example

```json
{
  "service": "",
  "location": "",
  "maxItems": 60,
  "startUrls": [
    "https://booksy.com/en-us/s/hair-salon/18229_chicago"
  ],
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyCountry": "US"
  }
}
```

# Actor output Schema

## `businessId` (type: `string`):

Booksy business ID

## `name` (type: `string`):

Business name

## `category` (type: `string`):

Searched service/category

## `rating` (type: `string`):

Average review rating (0-5)

## `reviewsCount` (type: `string`):

Number of reviews

## `reviewsStars` (type: `string`):

Rounded star rating

## `address` (type: `string`):

Street address

## `city` (type: `string`):

City

## `latitude` (type: `string`):

GPS latitude

## `longitude` (type: `string`):

GPS longitude

## `imageUrl` (type: `string`):

Cover photo URL

## `staffCount` (type: `string`):

Number of staff

## `bestOfBooksy` (type: `string`):

Best of Booksy award

## `acceptsBooksyPay` (type: `string`):

Accepts Booksy Pay

## `hasOnlineBooking` (type: `string`):

Offers online booking

## `isPromoted` (type: `string`):

Promoted listing

## `travelingService` (type: `string`):

Traveling/mobile service

## `venueName` (type: `string`):

Parent venue / salon-suite brand (when present)

## `url` (type: `string`):

Business page URL

## `searchUrl` (type: `string`):

Booksy search URL used

## `scrapedAt` (type: `string`):

Extraction timestamp

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "maxItems": 60,
    "startUrls": [],
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyCountry": "US"
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("haketa/booksy-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "maxItems": 60,
    "startUrls": [],
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyCountry": "US",
    },
}

# Run the Actor and wait for it to finish
run = client.actor("haketa/booksy-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "maxItems": 60,
  "startUrls": [],
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyCountry": "US"
  }
}' |
apify call haketa/booksy-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,haketa/booksy-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/cCFTokmiqvqLYixQP/builds/ygqBeV0OxLczElala/openapi.json