{ "openapi": "3.1.0", "info": { "title": "Luxstay datasets API", "version": "1.0.0", "description": "Public, downloadable Southeast Asia travel datasets — destinations, head-to-head comparisons, climate windows, and tool usage. Released under CC BY 4.0; please attribute Luxstay and the underlying source projects.", "license": { "name": "CC BY 4.0", "url": "https://creativecommons.org/licenses/by/4.0/" }, "contact": { "name": "Luxstay", "url": "https://luxstay.com" } }, "servers": [ { "url": "https://luxstay.com" } ], "paths": { "/api/data/vietnam-destinations": { "get": { "summary": "Download the Vietnam destinations dataset", "description": "One row per destination. Geographic fields are sourced from GeoNames; climate and budget bands are extracted from public sources via Claude and validated against a Zod schema before storage.", "tags": [ "Datasets" ], "parameters": [ { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "csv" ], "default": "json" }, "description": "Response format. Defaults to JSON." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "dataset": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "license": { "type": "string" }, "license_url": { "type": "string" }, "attribution": { "type": "string" }, "columns": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string" }, "description": { "type": "string" } } } } } }, "rows": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string", "description": "URL-safe identifier (English)." }, "name_en": { "type": "string", "description": "English display name." }, "country_code": { "type": "string", "description": "ISO 3166-1 alpha-2." }, "region_code": { "type": "string", "description": "Admin region code (e.g. VN-44)." }, "lat": { "type": "number", "description": "Decimal latitude." }, "lng": { "type": "number", "description": "Decimal longitude." }, "tier": { "type": "number", "description": "Editorial priority tier (1–3)." }, "population": { "type": "number", "description": "Population from GeoNames." }, "timezone": { "type": "string", "description": "IANA timezone identifier." }, "climate_zone": { "type": "string", "description": "Köppen-style climate descriptor." }, "best_visit_months": { "type": "array", "items": { "type": "number" }, "description": "Months (1–12) considered best to visit." }, "currency_code": { "type": "string", "description": "Local ISO 4217 currency." }, "languages_spoken": { "type": "array", "items": { "type": "string" }, "description": "ISO 639 language codes." }, "travel_style_tags": { "type": "array", "items": { "type": "string" }, "description": "Lower-kebab style tags." }, "avg_daily_budget_usd": { "type": "object", "description": "{ budget, mid, premium } USD per traveler per day." } }, "required": [ "slug", "name_en", "country_code", "region_code", "lat", "lng", "tier", "population", "timezone", "climate_zone", "best_visit_months", "currency_code", "languages_spoken", "travel_style_tags", "avg_daily_budget_usd" ] } } } } }, "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid format query parameter." }, "404": { "description": "Unknown dataset." }, "500": { "description": "Fetch failed." } } } }, "/api/data/vietnam-comparisons": { "get": { "summary": "Download the Vietnam destination comparisons dataset", "description": "One row per published comparison. Slugs are stable across regenerations; data_points and intros live on each row but are out of scope for this CSV — use the JSON download for the full structured payload.", "tags": [ "Datasets" ], "parameters": [ { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "csv" ], "default": "json" }, "description": "Response format. Defaults to JSON." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "dataset": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "license": { "type": "string" }, "license_url": { "type": "string" }, "attribution": { "type": "string" }, "columns": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string" }, "description": { "type": "string" } } } } } }, "rows": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string", "description": "URL slug (e.g. da-nang-vs-nha-trang)." }, "type": { "type": "string", "description": "Comparison type." }, "a_slug": { "type": "string", "description": "First destination slug." }, "b_slug": { "type": "string", "description": "Second destination slug." }, "target_keywords": { "type": "array", "items": { "type": "string" }, "description": "SEO target keywords." }, "search_volume": { "type": "number", "description": "Indicative monthly search volume." } }, "required": [ "slug", "type", "a_slug", "b_slug", "target_keywords", "search_volume" ] } } } } }, "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid format query parameter." }, "404": { "description": "Unknown dataset." }, "500": { "description": "Fetch failed." } } } }, "/api/data/luxstay-tool-usage-daily": { "get": { "summary": "Download the Luxstay tool usage — daily counts dataset", "description": "One row per (tool, locale, day) over the trailing 90 days. Useful for tracking which tools resonate with which audiences. No personally identifiable information — session ids, input bodies, and output bodies are intentionally omitted.", "tags": [ "Datasets" ], "parameters": [ { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "csv" ], "default": "json" }, "description": "Response format. Defaults to JSON." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "dataset": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "license": { "type": "string" }, "license_url": { "type": "string" }, "attribution": { "type": "string" }, "columns": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string" }, "description": { "type": "string" } } } } } }, "rows": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "format": "date", "description": "UTC date the uses were recorded." }, "tool_slug": { "type": "string", "description": "Slug of the tool (matches /tools/{slug})." }, "locale": { "type": "string", "description": "Locale of the request (e.g. \"en\"). Null = unknown." }, "uses": { "type": "number", "description": "Count of tool invocations that day." } }, "required": [ "day", "tool_slug", "locale", "uses" ] } } } } }, "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid format query parameter." }, "404": { "description": "Unknown dataset." }, "500": { "description": "Fetch failed." } } } }, "/api/data/vietnam-climate-windows": { "get": { "summary": "Download the Vietnam best-visit climate windows dataset", "description": "Useful for plotting heatmaps or computing month-overlap matches across destinations. Recommended = 1 means the month is inside best_visit_months for that destination.", "tags": [ "Datasets" ], "parameters": [ { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "csv" ], "default": "json" }, "description": "Response format. Defaults to JSON." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "dataset": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "license": { "type": "string" }, "license_url": { "type": "string" }, "attribution": { "type": "string" }, "columns": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string" }, "description": { "type": "string" } } } } } }, "rows": { "type": "array", "items": { "type": "object", "properties": { "destination_slug": { "type": "string", "description": "Destination slug." }, "destination_name": { "type": "string", "description": "English name." }, "month": { "type": "number", "description": "Month integer 1–12." }, "recommended": { "type": "number", "description": "1 if best-visit, 0 otherwise." } }, "required": [ "destination_slug", "destination_name", "month", "recommended" ] } } } } }, "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid format query parameter." }, "404": { "description": "Unknown dataset." }, "500": { "description": "Fetch failed." } } } } }, "tags": [ { "name": "Datasets", "description": "One row per dataset. Each row is downloadable as JSON or CSV via a stable URL." } ] }