{ "openapi": "3.1.0", "info": { "title": "El Segundo Oracle", "version": "1.0.0", "description": "Public, credential-free, read-only resources and official conditions for El Segundo. This community site is not an official City service. Discovery is available at /agents.json and /llms.txt." }, "servers": [ { "url": "https://elsegundo.xyz" } ], "security": [], "paths": { "/api/v1/manifest": { "get": { "summary": "Discover the public Oracle API", "description": "Lists capabilities, data links, limits, categories and unsupported actions.", "parameters": [], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid, duplicate or unknown query parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Only GET, HEAD and OPTIONS are supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getManifest" } }, "/api/v1/resources": { "get": { "summary": "Search the dated resource directory", "description": "Search combines meaningful query tokens with AND; each token may match one of its curated synonyms. Exact title matches rank first. No query lists the directory. All results retain source dates and verification limits.", "parameters": [ { "name": "q", "in": "query", "description": "Specific topic, place or service. Case-insensitive whole-word matching with category synonyms. Queries containing only stop words are rejected.", "schema": { "type": "string", "minLength": 2, "maxLength": 200 } }, { "name": "category", "in": "query", "description": "Category from the manifest; exact name, normalized slug, or an unambiguous category synonym.", "schema": { "type": "string", "maxLength": 80 } }, { "name": "area", "in": "query", "description": "Area from the manifest, for example local or nearby.", "schema": { "type": "string", "maxLength": 80 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourcePage" } } } }, "400": { "description": "Invalid, duplicate or unknown query parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Only GET, HEAD and OPTIONS are supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "searchResources" } }, "/api/v1/conditions": { "get": { "summary": "Read independently dated official conditions", "description": "Fixed read-only NWS and NOAA sources; callers cannot supply upstream URLs. NWS LAX weather is stale after 120 minutes, forecast after 1080 minutes, NWS alerts after 30 minutes, Santa Monica water temperature after 120 minutes, and tide predictions after 360 minutes from retrieval. No successful reading is substituted for a failed feed. Inspect each feed status. A 200 response may include partial failures.", "parameters": [], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conditions" } } } }, "400": { "description": "Invalid, duplicate or unknown query parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Only GET, HEAD and OPTIONS are supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "All five official feeds are unavailable; each feed has an error and null data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conditions" } } } } }, "operationId": "getConditions" } }, "/api/v1/ask": { "get": { "summary": "Match a plain-language question to directory sources", "description": "Deterministic source matching; no LLM generation, booking, payments, accounts or message sending. Results do not confirm real-time hours, eligibility, prices or availability.", "parameters": [ { "name": "q", "in": "query", "description": "Specific topic, place or service. Case-insensitive whole-word matching with category synonyms. Queries containing only stop words are rejected.", "schema": { "type": "string", "minLength": 2, "maxLength": 200 }, "required": true }, { "name": "category", "in": "query", "description": "Category from the manifest; exact name, normalized slug, or an unambiguous category synonym.", "schema": { "type": "string", "maxLength": 80 } }, { "name": "area", "in": "query", "description": "Area from the manifest, for example local or nearby.", "schema": { "type": "string", "maxLength": 80 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 5 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ResourcePage" }, { "type": "object", "required": [ "mode", "usesLLM", "canBook", "status", "answer", "sources" ], "properties": { "mode": { "const": "deterministic_source_matching" }, "usesLLM": { "const": false }, "canBook": { "const": false }, "status": { "type": "string", "enum": [ "matched", "no_match" ] }, "answer": { "type": "string" }, "sources": { "type": "array", "items": { "type": "object" } }, "relatedEndpoints": { "type": "array", "items": { "type": "string", "format": "uri" } } } } ] } } } }, "400": { "description": "Invalid, duplicate or unknown query parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Only GET, HEAD and OPTIONS are supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "matchQuestion" } }, "/api/v1/economy": { "get": { "operationId": "getMonthlyEconomy", "summary": "Read monthly local employment and unemployment estimates", "description": "Fixed California EDD LAUS sources for El Segundo city (Sub-County Place) and Los Angeles County (County), not seasonally adjusted. Fetches 24 recent rows per area, verifies exact geography and adjustment fields, sorts numeric year/month, and retains provider preliminary/final status. Values older than 100 days from period end are stale. Monthly, not real-time. No Census or commercial-property values are refreshed or substituted. No query parameters. Successful responses may be cached for 3600 seconds; partial failures for 60 seconds.", "responses": { "200": { "description": "Both or at least one area returned usable monthly data. Inspect each area and metric status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Economy" } } } }, "400": { "description": "Unsupported query parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Both EDD areas unavailable. Metrics are null with unavailable status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Economy" } } } } } } }, "/api/v1/businesses": { "get": { "operationId": "searchBusinesses", "summary": "Search the dated 25-mile OpenStreetMap business directory", "description": "Public read-only map data under ODbL. Listings are a dated snapshot, not verified operating status, current hours, endorsements or a complete business registry. Preserve source links, snapshot dates, attribution and limitations. Business records are separate from the curated 80-record resource register. Text terms are matched with AND using case-insensitive substrings. Category and city filters use case-insensitive exact matching; empty or all means no filter. Unknown and repeated parameters return HTTP 400. Results retain distance ordering. GET, HEAD and OPTIONS are supported; successful responses may be cached for one hour. Empty or single-character q values are allowed.", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 200, "minLength": 0 }, "description": "Text to match against the dated map listings." }, { "name": "category", "in": "query", "schema": { "type": "string", "maxLength": 80 }, "description": "Business category filter." }, { "name": "radius", "in": "query", "schema": { "type": "number", "minimum": 1, "maximum": 25, "default": 25 }, "description": "Straight-line miles from central El Segundo, within the 25-mile dataset; not travel distance." }, { "name": "city", "in": "query", "schema": { "type": "string", "maxLength": 120 }, "description": "Mapped locality name, when present." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Number of records per page, within the endpoint limit." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 100000, "default": 0 }, "description": "Pagination offset." } ], "responses": { "200": { "description": "Source-attributed page of matching dated map records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessPage" } } } }, "400": { "description": "Invalid query parameter or pagination bounds.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "405": { "description": "Read-only endpoint; mutation methods are unsupported.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/briefing": { "get": { "operationId": "getDailySourceBriefing", "summary": "Compact source briefing for Grok Bot and other readers", "description": "No query parameters. Current LA date; generatedAt is assembly time. Conditions and monthly economy retain individual timestamps and statuses. Editorial picks are evergreen, not an event calendar. HTTP200 can contain unavailable live feeds: inspect sourceStatus and per-feed status. contentFingerprint excludes retrieval times for change detection. Public and read-only; no posting connection or scheduled job.", "responses": { "200": { "description": "Assembled source briefing, including partial-source results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Briefing" } } } }, "400": { "description": "Query parameters are unsupported" }, "405": { "description": "Only GET, HEAD and OPTIONS are allowed" } } } }, "/today.md": { "get": { "operationId": "getMarkdownBriefing", "summary": "Readable Markdown version of the current source briefing", "description": "Same sources and date semantics as /api/v1/briefing. No JavaScript, login, API key or query parameters. All source dates and warnings remain visible.", "responses": { "200": { "description": "Markdown source briefing, including explicit unavailable feed states", "content": { "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "Query parameters are unsupported" }, "405": { "description": "Only GET, HEAD and OPTIONS are allowed" } } } } }, "components": { "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } }, "Resource": { "type": "object", "required": [ "id", "title", "category", "description", "url", "locality", "area", "sourceDate", "verification", "warnings" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "category": { "type": "string" }, "description": { "type": "string" }, "locality": { "type": "string" }, "area": { "type": "string" }, "verification": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "sourceDate": { "type": [ "string", "null" ], "description": "Research date; never a promise of current opening hours or eligibility." }, "warnings": { "type": "array", "items": { "type": "string" } }, "subcategory": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } } } }, "ResourcePage": { "type": "object", "required": [ "query", "items", "total", "limit", "offset", "nextOffset" ], "properties": { "version": { "type": "string" }, "query": { "type": "string" }, "filters": { "type": "object" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Resource" } }, "total": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "offset": { "type": "integer", "minimum": 0, "maximum": 10000 }, "nextOffset": { "type": [ "integer", "null" ] } } }, "Feed": { "type": "object", "required": [ "id", "status", "observedAt", "issuedAt", "retrievedAt", "maxAgeMinutes", "freshnessBasis", "stale", "data", "sourceUrl" ], "properties": { "id": { "type": "string", "enum": [ "weather", "forecast", "alerts", "waterTemperature", "tides" ] }, "source": { "type": "string" }, "sourceUrl": { "type": "string", "format": "uri" }, "location": { "type": "string" }, "kind": { "type": "string", "enum": [ "observation", "forecast", "alerts", "prediction" ] }, "status": { "type": "string", "enum": [ "fresh", "partial", "stale", "unavailable" ] }, "observedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Actual observation time; null for forecasts, tide predictions and alert collections." }, "issuedAt": { "type": [ "string", "null" ], "format": "date-time" }, "retrievedAt": { "type": "string", "format": "date-time" }, "maxAgeMinutes": { "type": "number" }, "freshnessBasis": { "type": "string", "enum": [ "observedAt", "issuedAt", "retrievedAt" ] }, "ageMinutes": { "type": [ "number", "null" ] }, "stale": { "type": [ "boolean", "null" ], "description": "Null when feed unavailable; true when source timestamp is missing, too old or over five minutes in the future." }, "data": { "type": [ "object", "null" ] }, "warnings": { "type": "array", "items": { "type": "string" } }, "error": { "type": "object" } } }, "Conditions": { "type": "object", "required": [ "version", "location", "generatedAt", "status", "feeds", "limitations" ], "properties": { "version": { "type": "string" }, "location": { "type": "object" }, "generatedAt": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "fresh", "partial", "unavailable" ] }, "feeds": { "type": "array", "items": { "$ref": "#/components/schemas/Feed" } }, "limitations": { "type": "array", "items": { "type": "string" } } } }, "EconomyMetric": { "type": "object", "required": [ "id", "metric", "title", "geography", "value", "unit", "period", "periodLabel", "status", "stale", "frequency", "seasonallyAdjusted", "retrievedAt", "sourceUrl" ], "properties": { "id": { "type": "string" }, "metric": { "type": "string", "enum": [ "unemploymentRate", "employment", "unemployment", "laborForce" ] }, "title": { "type": "string" }, "geography": { "type": "string", "enum": [ "El Segundo city", "Los Angeles County" ] }, "value": { "type": [ "number", "null" ] }, "unit": { "type": "string", "enum": [ "%", "people" ] }, "period": { "type": [ "string", "null" ], "description": "Reporting period as YYYY-MM." }, "periodLabel": { "type": [ "string", "null" ] }, "periodEnd": { "type": [ "string", "null" ] }, "dataStatus": { "type": [ "string", "null" ], "description": "Provider status, for example Preliminary or Final." }, "preliminary": { "type": [ "boolean", "null" ] }, "status": { "type": "string", "enum": [ "fresh", "partial", "stale", "unavailable" ] }, "stale": { "type": [ "boolean", "null" ] }, "frequency": { "const": "monthly" }, "seasonallyAdjusted": { "const": false }, "retrievedAt": { "type": "string", "format": "date-time" }, "sourceUrl": { "type": "string", "format": "uri" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "Economy": { "type": "object", "required": [ "version", "generatedAt", "status", "frequency", "realTime", "areas", "metrics", "limitations" ], "properties": { "version": { "type": "string" }, "generatedAt": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "fresh", "partial", "unavailable" ] }, "frequency": { "const": "monthly" }, "realTime": { "const": false }, "source": { "type": "string" }, "dataset": { "type": "string" }, "areas": { "type": "array", "items": { "type": "object", "description": "Exact city/county source records, period, provider status, benchmark year, per-area freshness and errors." } }, "metrics": { "type": "array", "items": { "$ref": "#/components/schemas/EconomyMetric" } }, "limitations": { "type": "array", "items": { "type": "string" } } } }, "BusinessRecord": { "type": "object", "description": "Dated OpenStreetMap record. Preserve attribution, original source and verification limits.", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" }, "type": { "type": "string" }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "distanceMiles": { "type": "number" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "website": { "type": [ "string", "null" ] }, "sourceUrl": { "type": "string", "format": "uri" }, "sourceDate": { "type": "string" }, "postcode": { "type": [ "string", "null" ] }, "verification": { "type": "string" } } }, "BusinessPage": { "type": "object", "required": [ "version", "dataset", "query", "sort", "total", "limit", "offset", "nextOffset", "items" ], "properties": { "version": { "type": "string" }, "dataset": { "type": "object", "description": "Full ODbL attribution, license, retrievedAt, sourceSnapshotAt, center, radius, limitations and downloadUrl; recordCount is the full dataset size." }, "query": { "type": "object", "properties": { "q": { "type": "string" }, "category": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "radiusMiles": { "type": "number" } } }, "sort": { "type": "string" }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "nextOffset": { "type": [ "integer", "null" ] }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessRecord" } } } }, "Briefing": { "type": "object", "required": [ "version", "localDate", "timezone", "generatedAt", "contentFingerprint", "status", "sourceStatus", "conditions", "economy", "editorial", "publishingConnected" ], "properties": { "version": { "type": "string" }, "localDate": { "type": "string", "format": "date" }, "timezone": { "const": "America/Los_Angeles" }, "generatedAt": { "type": "string", "format": "date-time" }, "contentFingerprint": { "type": "string", "pattern": "^[a-f0-9]{24}$" }, "status": { "enum": [ "complete", "partial" ] }, "sourceStatus": { "type": "object", "properties": { "conditions": { "type": "string" }, "economy": { "type": "string" } } }, "nextSuggestedCheckAt": { "type": "string", "format": "date-time" }, "scheduledByThisSite": { "const": false }, "publishingConnected": { "const": false }, "readOnly": { "const": true }, "usesLLM": { "const": false }, "conditions": { "type": "object", "properties": { "status": { "type": "string" }, "feeds": { "type": "array", "items": { "$ref": "#/components/schemas/Feed" } }, "fullDataUrl": { "type": "string", "format": "uri" } } }, "economy": { "type": "object", "properties": { "status": { "type": "string" }, "frequency": { "const": "monthly" }, "realTime": { "const": false }, "metrics": { "type": "array", "items": { "$ref": "#/components/schemas/EconomyMetric" } } } }, "editorial": { "type": "object", "description": "Daily rotating resource, sports source, lesson, art, PointCast project and dated Space Dirt reading. Each contains stable ID, source link and relevant caveats.", "properties": { "kind": { "const": "evergreen_suggestions" }, "isEventCalendar": { "const": false }, "selectionDate": { "type": "string", "format": "date" } } }, "discovery": { "type": "object" }, "usageNotes": { "type": "array", "items": { "type": "string" } } } } } }, "externalDocs": { "description": "Human-readable resource guide", "url": "https://elsegundo.xyz" } }