{ "openapi": "3.1.0", "info": { "title": "o2o.dev Agent Data API", "version": "0.1.0", "description": "Invite-only reviewed place data. No reservations or realtime inventory. All prices are observations. REST and MCP tools/call share 1000/day and 30/minute UTC fixed bucket quotas by default." }, "servers": [ { "url": "http://localhost:3000", "description": "Local development; no public production API is implied" } ], "security": [ { "BearerKey": [] } ], "paths": { "/v1/places": { "get": { "operationId": "searchPlaces", "summary": "Search published permitted places", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Case-insensitive name substring, not natural-language intent" }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Z]{2}$" }, "description": "" }, { "name": "city", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Exact published city text" }, { "name": "category", "in": "query", "required": false, "schema": { "enum": [ "restaurant", "hotel" ] }, "description": "" }, { "name": "lat", "in": "query", "required": false, "schema": { "type": "number", "minimum": -90, "maximum": 90 }, "description": "Requires lon and radius_km; WGS84 only" }, { "name": "lon", "in": "query", "required": false, "schema": { "type": "number", "minimum": -180, "maximum": 180 }, "description": "" }, { "name": "radius_km", "in": "query", "required": false, "schema": { "type": "number", "exclusiveMinimum": 0, "maximum": 50 }, "description": "" }, { "name": "parking", "in": "query", "required": false, "schema": { "enum": [ "available", "unavailable", "conditional" ] }, "description": "Matches only fresh non-conflicted evidence" }, { "name": "private_room", "in": "query", "required": false, "schema": { "enum": [ "available", "unavailable", "conditional" ] }, "description": "Matches only fresh non-conflicted evidence" }, { "name": "children_facilities", "in": "query", "required": false, "schema": { "enum": [ "available", "unavailable", "conditional" ] }, "description": "Matches only fresh non-conflicted evidence" }, { "name": "pets", "in": "query", "required": false, "schema": { "enum": [ "available", "unavailable", "conditional" ] }, "description": "Matches only fresh non-conflicted evidence" }, { "name": "fields", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated place fields; identity, evidence, sources and module coverage remain included." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "" } ], "responses": { "200": { "description": "Success; unknown modules are explicitly labelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceList" } } } }, "400": { "description": "Invalid or unsupported parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Browser Origin not permitted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No publicly visible place", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Shared application quota exhausted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/places/{id}": { "get": { "operationId": "getPlace", "summary": "Get one published place", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stable place public UUID" }, { "name": "fields", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated place fields; identity, evidence, sources and module coverage remain included." } ], "responses": { "200": { "description": "Success; unknown modules are explicitly labelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceDetail" } } } }, "400": { "description": "Invalid or unsupported parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Browser Origin not permitted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No publicly visible place", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Shared application quota exhausted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/places/{id}/menu": { "get": { "operationId": "getMenu", "summary": "Observed menu; missing is not an empty real-world menu", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stable place public UUID" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "" } ], "responses": { "200": { "description": "Success; unknown modules are explicitly labelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Menu" } } } }, "400": { "description": "Invalid or unsupported parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Browser Origin not permitted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No publicly visible place", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Shared application quota exhausted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/places/{id}/offers": { "get": { "operationId": "getOffers", "summary": "Reviewed offer observations; not inventory or eligibility", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stable place public UUID" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "" } ], "responses": { "200": { "description": "Success; unknown modules are explicitly labelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Offers" } } } }, "400": { "description": "Invalid or unsupported parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Browser Origin not permitted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No publicly visible place", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Shared application quota exhausted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/coverage": { "get": { "operationId": "getCoverage", "summary": "Actual visible records and module completeness", "parameters": [], "responses": { "200": { "description": "Success; unknown modules are explicitly labelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoverageList" } } } }, "400": { "description": "Invalid or unsupported parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Browser Origin not permitted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No publicly visible place", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Shared application quota exhausted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "BearerKey": { "type": "http", "scheme": "bearer", "description": "Manually issued API key; server stores only a digest" } }, "schemas": { "Price": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d{1,10}(\\.\\d{1,4})?$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "type": { "enum": [ "menu_price", "channel_price", "conditional_price", "starting_price", "market_price" ] }, "unit": { "type": "string" }, "conditions": { "type": "array", "items": { "type": "string" } } }, "required": [ "amount", "currency", "type", "unit", "conditions" ] }, "Evidence": { "type": "object", "properties": { "source_record_id": { "type": "integer" }, "observed_at": { "type": "string", "format": "date-time" }, "valid_until": { "type": "string", "format": "date-time" }, "verification": { "enum": [ "observed", "human_checked", "merchant_confirmed" ] }, "conflict": { "type": "boolean" }, "freshness": { "enum": [ "current", "needs_update" ] } }, "required": [ "source_record_id", "observed_at", "valid_until" ] }, "Source": { "type": "object", "properties": { "source_record_id": { "type": "integer" }, "name": { "type": "string" }, "release_version": { "type": "string" }, "license": { "type": "string" }, "attribution": { "type": "string" }, "source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [] }, "Period": { "type": "object", "properties": { "day": { "type": "integer", "minimum": 1, "maximum": 7 }, "open": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$" }, "close": { "type": "string" }, "end_day_offset": { "enum": [ 0, 1 ] } }, "required": [ "day", "open", "close", "end_day_offset" ] }, "Facility": { "type": "object", "properties": { "state": { "enum": [ "available", "unavailable", "conditional", "unknown", "not_applicable" ] }, "details": { "type": "string" } }, "required": [ "state" ] }, "Place": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "category": { "enum": [ "restaurant", "hotel" ] }, "country_code": { "type": "string" }, "city": { "type": "string" }, "city_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timezone": { "type": "string" }, "address": { "type": "string" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "coordinate_system": { "enum": [ "WGS84", "GCJ02", "BD09", "unknown" ] }, "operating_status": { "enum": [ "operating", "suspended", "closed", "unknown" ] }, "business_hours": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/Period" } }, { "type": "null" } ] }, "business_hours_exceptions": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/Period" } }, { "type": "null" } ] } }, "facilities": { "type": "object", "properties": { "parking": { "$ref": "#/components/schemas/Facility" }, "private_room": { "$ref": "#/components/schemas/Facility" }, "children_facilities": { "$ref": "#/components/schemas/Facility" }, "pets": { "$ref": "#/components/schemas/Facility" } }, "required": [] }, "modules": { "type": "object", "additionalProperties": { "enum": [ "available", "missing", "needs_update", "incomplete" ] } }, "evidence": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Evidence" } }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } }, "published_at": { "type": "string", "format": "date-time" }, "publication_version": { "type": "integer" }, "original_name": { "type": "string", "description": "Name retained in its observed original form" }, "original_language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Explicit source language tag; omitted or null when not known, never inferred from script" } }, "required": [ "id", "modules", "evidence", "sources", "published_at", "publication_version" ] }, "MenuItem": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "source_record_id": { "type": "integer" }, "observed_at": { "type": "string", "format": "date-time" }, "valid_until": { "type": "string", "format": "date-time" }, "freshness": { "enum": [ "current", "needs_update" ] }, "price": { "anyOf": [ { "$ref": "#/components/schemas/Price" }, { "type": "null" } ] }, "kind": { "enum": [ "dish", "category" ] }, "specification": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "verification": { "enum": [ "observed", "human_checked", "merchant_confirmed" ], "description": "Omitted means observed, not confirmed." }, "conflict": { "type": "boolean", "description": "Explicit unresolved conflict; strict current-data use excludes true." }, "sale_status": { "enum": [ "on_sale", "off_sale", "unknown" ], "description": "Observed sale status only, never live stock. Omission means unknown." }, "channel": { "type": "string", "description": "Observed channel, unknown if omitted." } }, "required": [ "id", "name", "kind", "source_record_id", "observed_at", "valid_until" ] }, "Offer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "source_record_id": { "type": "integer" }, "observed_at": { "type": "string", "format": "date-time" }, "valid_until": { "type": "string", "format": "date-time" }, "freshness": { "enum": [ "current", "needs_update" ] }, "price": { "anyOf": [ { "$ref": "#/components/schemas/Price" }, { "type": "null" } ] }, "channel": { "type": "string" }, "validity": { "type": "object", "properties": { "type": { "enum": [ "fixed", "relative", "unknown" ] }, "from": { "type": "string", "format": "date" }, "through": { "type": "string", "format": "date" }, "anchor": { "enum": [ "purchased_at", "activated_at" ] }, "duration_days": { "type": "integer", "minimum": 1 }, "raw_text": { "type": "string" } }, "required": [ "type" ] }, "excluded_dates": { "type": "array", "items": { "type": "string", "format": "date" } }, "use_hours": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/Period" } }, { "type": "null" } ] }, "private_room_policy": { "enum": [ "allowed", "forbidden", "unknown" ] }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PackageItem" } }, "raw_text": { "type": "string" }, "verification": { "enum": [ "observed", "human_checked", "merchant_confirmed" ], "description": "Omitted means observed, not confirmed." }, "conflict": { "type": "boolean", "description": "Explicit unresolved conflict; strict current-data use excludes true." }, "sale_status": { "enum": [ "on_sale", "off_sale", "unknown" ], "description": "Observed sale status only, never live stock. Omission means unknown." }, "package_id": { "type": "string", "description": "Shared content identity, independent of channel sale identity." }, "package": { "$ref": "#/components/schemas/Package" } }, "required": [ "id", "name", "channel", "source_record_id", "observed_at", "valid_until" ] }, "PackageItem": { "type": "object", "properties": { "type": { "enum": [ "fixed", "choice", "service", "gift" ] }, "name": { "type": "string" }, "quantity": { "type": "number", "exclusiveMinimum": 0 }, "unit": { "type": "string" }, "options": { "type": "array", "items": { "type": "string" } }, "min_select": { "type": "integer", "minimum": 0 }, "max_select": { "type": "integer", "minimum": 0 }, "price": { "$ref": "#/components/schemas/Price" }, "percentage_rate": { "type": "string", "pattern": "^\\d{1,3}(?:\\.\\d{1,4})?$", "description": "Service charge percentage 0..100, mutually exclusive with price." } }, "required": [ "type" ] }, "Meta": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "status": { "enum": [ "available", "missing", "needs_update" ] }, "publication_version": { "type": "integer" }, "published_at": { "type": "string", "format": "date-time" }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } }, "scope": { "type": "string" } }, "required": [] }, "Coverage": { "type": "object", "properties": { "country_code": { "type": "string" }, "city": { "type": "string" }, "category": { "enum": [ "restaurant", "hotel" ] }, "total": { "type": "integer" }, "modules": { "type": "object", "additionalProperties": { "type": "integer" } }, "completeness": { "type": "object", "additionalProperties": { "type": "number", "minimum": 0, "maximum": 1 } }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [] }, "Error": { "type": "object", "properties": { "schema_version": { "const": "0.1" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "schema_version", "error" ] }, "PlaceList": { "type": "object", "properties": { "schema_version": { "const": "0.1" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Place" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "schema_version", "data", "meta" ] }, "PlaceDetail": { "type": "object", "properties": { "schema_version": { "const": "0.1" }, "data": { "$ref": "#/components/schemas/Place" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "schema_version", "data", "meta" ] }, "Menu": { "type": "object", "properties": { "schema_version": { "const": "0.1" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MenuItem" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "schema_version", "data", "meta" ] }, "Offers": { "type": "object", "properties": { "schema_version": { "const": "0.1" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Offer" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "schema_version", "data", "meta" ] }, "CoverageList": { "type": "object", "properties": { "schema_version": { "const": "0.1" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Coverage" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "schema_version", "data", "meta" ] }, "Package": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PackageItem" } }, "source_record_id": { "type": "integer" }, "observed_at": { "type": "string", "format": "date-time" }, "valid_until": { "type": "string", "format": "date-time" }, "verification": { "enum": [ "observed", "human_checked", "merchant_confirmed" ], "description": "Omitted means observed, not confirmed." }, "conflict": { "type": "boolean", "description": "Explicit unresolved conflict; strict current-data use excludes true." }, "freshness": { "enum": [ "current", "needs_update" ] } }, "required": [ "id", "name", "items", "source_record_id", "observed_at", "valid_until" ] } } } }