booksy_businesses
List and filter Booksy salon and barber businesses in a chosen country by category, treatment, free-text query, or location, with pagination, sorting, open-now, offers, and bulk ID lookup.
Instructions
List and filter Booksy businesses in one market. Returns one page of Booksy's (booksy.com) salon and barber marketplace for a country, filtered by a top-level category, a treatment id or a free-text query, and optionally scoped to a location. This reads the Android customer app's own JSON API (https://{country}.booksy.com/core/v2/customer_api/businesses/), which is offset-paginated: page_size is honoured up to 100 (larger values are silently clamped, so they are rejected here) and total is the marketplace's own match count. total saturates at 10000, and total_capped reports when the number is a ceiling rather than an exact count. category and treatment are INTEGER ids — a slug is rejected upstream — taken from booksy-categories and booksy-treatment-hints respectively; they may be combined. The listing filters the app's own client sends are supported as well: sort_order (distance, score, top_rated, by_ids — by_ids requires business_ids and returns the businesses in the order supplied; score is the default ranking and returns the same order as no sort_order), gender (M, F, R — it reorders the page for a stated client gender but does not filter it, so total is unchanged, and an unrecognised value is rejected here because Booksy silently ignores it), open_now and has_special_offers (booleans that restrict the page to businesses open now or running an offer; open_now is sent upstream as 1/0 because Booksy rejects true/false on it), and business_ids (a comma-separated bulk lookup of at most 100 ids, which also satisfies the requirement for one of category, treatment or query). location_id and location_name are alternatives, and an unknown location_name is not an error: the server silently falls back to the whole country, so read the response's location node instead of assuming the name was applied. A page past the end is an honest empty businesses array with total intact; page 0 is rejected. Records carry catalogue metadata, geo, promotion flags and aggregate review scores only — never reviews, reviewer identities, staff or availability.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "booksy_businesses"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-based page number, default 1 | |
| query | No | Free-text search term; at least one of category, treatment or query is required | |
| gender | No | Ranking personalisation for a stated client gender; reorders but does not filter | |
| country | No | Market host | |
| category | No | Top-level category id from booksy-categories (integer, not a slug) | |
| open_now | No | Only businesses open now | |
| page_size | No | Records per page, default 20, maximum 100 | |
| treatment | No | Treatment id from booksy-treatment-hints (integer, not a slug) | |
| sort_order | No | Listing order; distance needs a location, score is the default ranking, by_ids requires business_ids | |
| location_id | No | Booksy location id, e.g. 30067 for New York City | |
| business_ids | No | Comma-separated business ids for a bulk lookup, at most 100; required with sort_order=by_ids | |
| location_name | No | Location name for the server to resolve, e.g. New York City | |
| has_special_offers | No | Only businesses running a special offer |