Data access
JSON catalogue · Full dataset · JSON record schema · Markdown version
WineStays is a travel directory with read-only accommodation data for AI agents and developers. Its visitor pages are designed for travellers; the same factual information is available in structured formats. WineStays is published at https://winestays.co.za. Its directory and evidence-backed data are available publicly.
Discovery
- Start with /catalogue.json. It contains up to 25 compact entries, total_properties and a next link when another page exists.
- Fetch individual /data/properties/{slug}.json records for the facts and field-level evidence needed for a recommendation.
- /directory.json is a complete snapshot for bulk processing; it is not needed for every query.
- /franschhoek/index.md, /stellenbosch/index.md and each listing's index.md provide the same information in plain text.
- /llms.txt is a proposed discovery convention, not an access policy or ranking guarantee.
- /sitemap.xml enumerates the intended HTML URLs. The production robots policy permits crawling; the separate private preview remains excluded.
Identity and field semantics
Each record has an immutable id, a stable canonical_url, a schema_entity_id, a source review date and separate official/booking links. Published identities use the intended winestays.co.za origin; local checks may substitute a loopback origin for testing. IDs remain unchanged if names change; future URL changes need redirects.
The JSON format is version 1.0. Facts use value, status, scope, source_ids and source_checked_on. source_ids refer to that record's sources list. A true value with property_reported status is a positive official-site report, not an independent inspection. null with not_confirmed status is unknown and must not be treated as false. Country/village setting is an editorial classification. Editorial suitability notes are separate from factual attributes.
The record contract is available at /data/agent-record.schema.json (JSON Schema Draft 2020-12). It describes the agent JSON format; this is separate from the Schema.org JSON-LD embedded in HTML. Known amenities in schema_amenities match the positive, sourced facts and visible table; unknown amenities are omitted from JSON-LD.
Pool facts specify shared-property or selected-room scope. Breakfast inclusion applies only to published rates. Room- and date-dependent prices, availability, pet rules, minimum age, accessibility and room counts remain unknown unless evidence is recorded. No absence or capability should be inferred from omitted or null data.
Example task
For a Franschhoek heated-pool shortlist, read pool_heated from the compact catalogue, select only true values, then fetch the detailed records and inspect the source IDs and review date. In this collection that yields Les Chambres and La Cabrière Country Estate. Other Franschhoek pool-heating records are unknown. Cite the listing and the underlying official source, and retain the exact room/rate checks.
Supported actions and limits
Discovery, comparison, citation and following official booking links are supported. WineStays has no live room inventory, live price query, reservation endpoint or payment capability. Booking URLs are source-observed handoff links, not tested transactions. No MCP endpoint, OAuth flow, API key, checkout or content-negotiation API is advertised.
All formats are generated from the same local property register. The compact catalogue is paginated at build time; next is null on the final page. There are no query-parameter search endpoints. The same HTML content is served regardless of user agent; no bot-only claims or hidden recommendation instructions are used.