{"openapi":"3.0.0","info":{"title":"Private Clubs API","version":"1.2.0","description":"Private membership club directory worldwide, with club profiles, waitlist status, amenities and membership data for 46,435+ clubs. Fees follow the caller's access (see Club.fee_views): signed-out callers get no fee figures, free accounts get ranges, and paying members get exact club-verified fees. The anonymous Private Clubs MCP server at /api/mcp returns no fees. Errors use RFC 9457 problem details, and each problem's type URI is a page that explains it (https://www.theprivateclubs.com/problems). The platform supports 15 UI languages and 49 currencies. All API responses return English text and USD fees by default; client-side currency conversion is available on the website.","contact":{"name":"Private Clubs","email":"support@theprivateclubs.com","url":"https://www.theprivateclubs.com/data"},"license":{"name":"Private Clubs data license","url":"https://www.theprivateclubs.com/data/license"},"termsOfService":"https://www.theprivateclubs.com/legal/terms","x-logo":{"url":"https://www.theprivateclubs.com/logo.png","altText":"Private Clubs"}},"servers":[{"url":"https://www.theprivateclubs.com","description":"Production"}],"tags":[{"name":"Clubs","description":"Search the club directory"},{"name":"Discovery","description":"Files that describe the site to AI tools"}],"components":{"parameters":{"ClubType":{"name":"type","in":"query","description":"A club type, in lower case (a hyphen reads as an underscore). Some types also match the types grouped under them: golf matches country_club; city matches social, arts, cigar and dining; athletic matches tennis and wellness; outdoor matches hunting, fishing, shooting and adventure; dining matches wine, and wine reads as dining. Any other value matches that exact stored type.","schema":{"type":"string","example":"golf"}},"State":{"name":"state","in":"query","description":"A state, province or region, by full name or two-letter code: FL and Florida match the same clubs. With no country, the search stays in the United States and Canada; for a region elsewhere, such as Scotland, send country as well.","schema":{"type":"string","example":"Florida"}},"Country":{"name":"country","in":"query","description":"A country, by name or ISO code: GB and United Kingdom match the same clubs. Omit it, or send all, to search every country.","schema":{"type":"string","example":"GB"}},"Query":{"name":"q","in":"query","description":"Part of the club name, matched in any case.","schema":{"type":"string","example":"yacht"}},"Waitlist":{"name":"waitlist","in":"query","description":"Waitlist statuses, comma separated, such as open,waitlist. by_invitation also matches clubs stored as invite_only.","style":"form","explode":false,"schema":{"type":"array","items":{"type":"string","enum":["open","waitlist","by_invitation","invite_only","closed","unknown"]}}},"Page":{"name":"page","in":"query","description":"The page to return, from 1. A value that is not a whole number from 1, such as 0, answers 400 invalid_page. A page past the last one, however large, answers 200 with an empty clubs array and the real total.","schema":{"type":"integer","minimum":1,"default":1}},"Limit":{"name":"limit","in":"query","description":"Clubs per page, from 1. A value above 200 is clamped to 200. A value that is not a whole number from 1, such as 0, answers 400 invalid_limit.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}},"headers":{"X-Total-Clubs":{"description":"Clubs that match the filters across all pages, the same number as total.","schema":{"type":"integer"}},"X-Request-Id":{"description":"A new id for each request: req_ followed by 16 hex characters.","schema":{"type":"string","example":"req_0123456789abcdef"}},"RateLimit":{"description":"Advertises the rate limit policy. Every response carries the same value, so remaining is not a live count.","schema":{"type":"string","example":"limit=120, remaining=119, reset=60"}},"RateLimit-Policy":{"description":"The advertised policy: 120 requests per 60 seconds. Keep within it.","schema":{"type":"string","example":"120;w=60"}}},"schemas":{"Problem":{"type":"object","description":"RFC 9457 problem details, sent as application/problem+json.","required":["type","title","status","detail","code","hint"],"properties":{"type":{"type":"string","format":"uri","description":"https://www.theprivateclubs.com/problems/{code}, a page that explains the code."},"title":{"type":"string","description":"A short summary of the problem."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"What went wrong with this request."},"code":{"type":"string","description":"A stable code to branch on.","enum":["invalid_page","invalid_limit","not_found","clubs_unavailable"]},"hint":{"type":"string","description":"How to fix the request."},"instance":{"type":"string","description":"The path that was called, or /api/v1 for an unknown /api/v1 path."}}},"ClubList":{"type":"object","required":["clubs","total","fee_access"],"properties":{"clubs":{"type":"array","description":"The clubs on this page.","items":{"$ref":"#/components/schemas/Club"}},"total":{"type":"integer","description":"Clubs that match the filters, across all pages."},"fee_access":{"type":"string","enum":["locked","band","exact"],"description":"The caller's fee visibility: locked without a site session, band for a free account, exact for a paying member."}}},"FeeView":{"type":"object","required":["kind"],"properties":{"kind":{"type":"string","enum":["none","locked","band","exact"],"description":"none: no figure on file. locked: a figure exists but this caller may not see it. band: a range. exact: the club-verified figure."},"label":{"type":"string","description":"Present for band and exact: the range or the figure as text, such as $72,000."},"estimate":{"type":"boolean","description":"Present for band: true when the figure behind the range is an estimate."}}},"Club":{"type":"object","required":["id","name","slug","city","state","country","type","status","verified","hero_image_url","initiation_fee","annual_dues","monthly_dues","fee_tier","waitlist_status","holes","par","yardage","course_architect","founded_year","opened_year","currency","amenities","description","google_rating","google_review_count","fee_views"],"properties":{"id":{"type":"string","format":"uuid","description":"The club's id."},"name":{"type":"string","description":"The club's name."},"slug":{"type":"string","description":"The club's identifier in profile links and MCP tool arguments."},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true,"description":"The state, province or region, as a full name."},"country":{"type":"string","nullable":true,"description":"The country, as a full name."},"type":{"type":"string","nullable":true,"description":"The stored club type, such as golf or country_club."},"status":{"type":"string","nullable":true,"description":"The listing's status on the site, such as published, unclaimed or coming_soon."},"verified":{"type":"boolean","nullable":true,"description":"Whether the listing is marked verified."},"hero_image_url":{"type":"string","nullable":true,"description":"The URL of the club's main image."},"initiation_fee":{"type":"number","nullable":true,"description":"Returned only to paying members for club-verified fees; null otherwise (see fee_views)."},"annual_dues":{"type":"number","nullable":true,"description":"Same visibility as initiation_fee."},"monthly_dues":{"type":"number","nullable":true,"description":"Same visibility as initiation_fee."},"fee_tier":{"type":"string","nullable":true,"enum":["verified","estimate","none",null],"description":"Where the club's fees come from. A label, never a figure."},"waitlist_status":{"type":"string","nullable":true,"enum":["open","waitlist","by_invitation","invite_only","closed","unknown",null],"description":"by_invitation and invite_only both mean membership is by invitation. unknown or null means the listing does not say."},"holes":{"type":"integer","nullable":true},"par":{"type":"integer","nullable":true},"yardage":{"type":"integer","nullable":true,"description":"Course length in yards."},"course_architect":{"type":"string","nullable":true},"founded_year":{"type":"integer","nullable":true},"opened_year":{"type":"integer","nullable":true,"description":"For a coming_soon club, the year it expects to open."},"currency":{"type":"string","description":"A three-letter ISO 4217 code, such as USD.","example":"USD"},"amenities":{"type":"array","nullable":true,"items":{"type":"string"}},"description":{"type":"string","nullable":true,"description":"Editorial text about the club."},"google_rating":{"type":"number","nullable":true},"google_review_count":{"type":"integer","nullable":true},"fee_views":{"type":"object","description":"Fees as this caller may see them. Signed out: kind locked when a figure exists. Free account: kind band (a range; estimate is true for estimates). Paying member: kind exact for club-verified fees, band otherwise.","required":["initiation","annual","monthly","firstYear"],"properties":{"initiation":{"$ref":"#/components/schemas/FeeView"},"annual":{"$ref":"#/components/schemas/FeeView"},"monthly":{"$ref":"#/components/schemas/FeeView"},"firstYear":{"$ref":"#/components/schemas/FeeView"}}}}}},"examples":{"invalid_page":{"summary":"page is not a whole number from 1","value":{"type":"https://www.theprivateclubs.com/problems/invalid_page","title":"Invalid page","status":400,"detail":"The page query parameter must be a positive integer.","code":"invalid_page","hint":"Call GET /api/v1/clubs?page=1&limit=50","instance":"/api/v1/clubs"}},"invalid_limit":{"summary":"limit is not a whole number from 1","value":{"type":"https://www.theprivateclubs.com/problems/invalid_limit","title":"Invalid limit","status":400,"detail":"The limit query parameter must be a positive integer.","code":"invalid_limit","hint":"Call GET /api/v1/clubs?page=1&limit=50. Maximum limit is 200.","instance":"/api/v1/clubs"}},"clubs_unavailable":{"summary":"The directory could not be read","value":{"type":"https://www.theprivateclubs.com/problems/clubs_unavailable","title":"Clubs unavailable","status":500,"detail":"The club directory could not be read. Try again in a moment.","code":"clubs_unavailable","hint":"Retry GET /api/v1/clubs. If this persists, email support@theprivateclubs.com.","instance":"/api/v1/clubs"}}},"responses":{"Problem":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"BadRequest":{"description":"invalid_page or invalid_limit: page or limit is not a whole number from 1","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_page":{"$ref":"#/components/examples/invalid_page"},"invalid_limit":{"$ref":"#/components/examples/invalid_limit"}}}}},"ServerError":{"description":"clubs_unavailable: the directory could not be read. Retry after a short wait.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"clubs_unavailable":{"$ref":"#/components/examples/clubs_unavailable"}}}}}}},"x-versioning":{"strategy":"URL path","current":"v1","policy":"Breaking changes ship under a new /api/vN path. Deprecated versions send Deprecation and Sunset headers for at least 90 days."},"paths":{"/api/v1/clubs":{"get":{"operationId":"getClubsV1","tags":["Clubs"],"summary":"Search clubs","description":"Searches the Private Clubs directory by type, place, name and waitlist status, with paging. Rows come sorted by name. A page past the last one answers 200 with an empty clubs array and the real total. Fees follow the caller's access (see Club.fee_views). Errors use RFC 9457 application/problem+json, and each problem's type URI is a page that explains the code. Responses carry the advisory RateLimit and RateLimit-Policy headers (120 requests per 60 seconds) and an X-Request-Id.","x-mint":{"href":"/api-reference/clubs/search-clubs"},"parameters":[{"$ref":"#/components/parameters/ClubType"},{"$ref":"#/components/parameters/State"},{"$ref":"#/components/parameters/Country"},{"$ref":"#/components/parameters/Query"},{"$ref":"#/components/parameters/Waitlist"},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"A page of clubs","headers":{"X-Total-Clubs":{"$ref":"#/components/headers/X-Total-Clubs"},"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClubList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/clubs":{"get":{"operationId":"getClubsApi","tags":["Clubs"],"summary":"Search clubs (unversioned path)","description":"The unversioned path of GET /api/v1/clubs: the same parameters, payload and problem codes, without the X-Request-Id header. New integrations use /api/v1/clubs.","parameters":[{"$ref":"#/components/parameters/ClubType"},{"$ref":"#/components/parameters/State"},{"$ref":"#/components/parameters/Country"},{"$ref":"#/components/parameters/Query"},{"$ref":"#/components/parameters/Waitlist"},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"A page of clubs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClubList"}}}},"400":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}}}},"/api/mcp":{"post":{"operationId":"postMcp","summary":"Private Clubs MCP server (Streamable HTTP)","description":"Model Context Protocol server over Streamable HTTP. POST JSON-RPC messages with Accept: application/json, text/event-stream. No account needed. Setup for each AI app: https://www.theprivateclubs.com/mcp","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"A JSON-RPC 2.0 request or notification"}}}},"responses":{"200":{"description":"JSON-RPC response","content":{"application/json":{"schema":{"type":"object"}},"text/event-stream":{"schema":{"type":"string"}}}}}}},"/ai/context.md":{"get":{"operationId":"getAiContext","tags":["Discovery"],"summary":"Get the platform context summary for AI","description":"A Markdown summary sized for AI context windows: the club count, golf and yacht club counts, how fees are shown, waitlist shares and key URLs. It carries no fee figures. English only.","responses":{"200":{"description":"Markdown context document","content":{"text/markdown":{"schema":{"type":"string"}}}}}}},"/llms.txt":{"get":{"operationId":"getLlmsTxt","tags":["Discovery"],"summary":"Get the llms.txt context file","description":"A plain text guide to the site for AI tools: what the directory holds, how fees are shown, the 15 UI languages and 49 currencies, the MCP setup, stable URLs and how to cite the site.","responses":{"200":{"description":"Plain text context file","content":{"text/plain":{"schema":{"type":"string"}}}}}}}},"x-i18n":{"description":"Private Clubs supports 15 UI languages and 49 currencies. The website auto-detects language from the user's browser and currency from their location. API responses are currently English/USD only.","supportedLanguages":["en","es","fr","de","it","pt","ar","he","zh","ja","ko","hi","th","tr","vi"],"supportedCurrencies":["USD","EUR","GBP","CAD","AUD","JPY","CNY","CHF","HKD","SGD","NZD","SEK","NOK","DKK","MXN","BRL","INR","KRW","THB","TRY","ZAR","PLN","CZK","HUF","RON","BGN","ISK","IDR","MYR","PHP","VND","CLP","COP","PEN","UYU","AED","SAR","QAR","KWD","BHD","EGP","MAD","ILS","KES","GHS","UGX","UAH","KZT","TWD"],"defaultLanguage":"en","defaultCurrency":"USD","currencyConversionNote":"All fees stored in USD. Client-side conversion uses daily rates from open.er-api.com. Converted values are approximate."}}