{ "openapi": "3.1.0", "info": { "title": "HomePulse API", "description": "Global home intelligence API. AI-synthesized home maintenance checklists, improvement ROI analysis, neighborhood research, smart home integration, energy efficiency guidance, contractor vetting, home value estimation, and rental market analysis. Serves homeowners, renters, real estate investors, and property managers in any country \u2014 pass `location` (postal code or city) and `country` (e.g. US, UK, CA, DE, AU) to get jurisdiction-correct currency, incentive programs, licensing authorities, and legal terminology. `zip` is accepted as a legacy alias for `location`. Amazon, Angi/Thumbtack (US), and country-specific equivalents (Checkatrade UK, HomeStars CA, hipages AU, MyHammer/Aroundhome DE) plus home warranty, home insurance, and home security affiliate links auto-appended where applicable. All endpoints support any language via ?lang=. Pricing: $0.08\u2013$0.10 USDC/call via x402 micropayment.", "version": "1.3.0", "contact": { "url": "https://homepulse.theaslangroupllc.com" } }, "servers": [ { "url": "https://homepulse.theaslangroupllc.com" } ], "components": { "securitySchemes": { "x402": { "type": "apiKey", "in": "header", "name": "PAYMENT-SIGNATURE", "description": "x402 payment signature. Omit to receive a 402 with payment requirements." } } }, "paths": { "/api/home/value": { "get": { "summary": "Home value estimate", "description": "Estimated market value range (low/mid/high) with confidence rating, comparable sales, market trend, and best time to act. Works for any country \u2014 pass country to get the right currency and local property portals.", "operationId": "homeValue", "security": [ { "x402": [] } ], "parameters": [ { "name": "address", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Street address" }, { "name": "location", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Postal code or city (e.g. 90210, M5V 2T6, SW1A)" }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Country (e.g. US, UK, CA, DE, AU) \u2014 selects local currency and property portals" }, { "name": "zip", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Legacy alias for location (ZIP/postal code)" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Home value estimate with market context and comparable sales" }, "402": { "description": "Payment required" } }, "x-price-usd": 0.1, "x-agent-use-case": "on-demand", "x-agent-chaining": "Run before listing or refinancing; pairs with PropPulse /api/prop/refi for refinance decision; pairs with /api/home/improve for pre-sale improvements with highest ROI" } }, "/api/home/neighborhood": { "get": { "summary": "Neighborhood analysis", "description": "School ratings, relative safety, walkability score, neighborhood character, and best-for/not-ideal-for breakdown, for any country. Pass country to get the right local terminology (HOA-equivalent, flood-risk authority, school-rating source).", "operationId": "homeNeighborhood", "security": [ { "x402": [] } ], "parameters": [ { "name": "location", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Postal code or area (e.g. 90210, M5V 2T6, SW1A)" }, { "name": "city", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string" }, "description": "State/province/region" }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Country (e.g. US, UK, CA, DE, AU)" }, { "name": "zip", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Legacy alias for location (ZIP/postal code)" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Neighborhood profile with schools, safety, walkability, and character" }, "402": { "description": "Payment required" } }, "x-price-usd": 0.1, "x-agent-use-case": "on-demand", "x-agent-chaining": "Run before buying or renting; pairs with PropPulse /api/prop/refi and /api/prop/mortgage for purchase decision; pairs with /api/home/value" } }, "/api/home/improve": { "get": { "summary": "Home improvement ROI analysis", "description": "ROI summary (cost, value added, recoup rating), best-for analysis (selling/staying/both), DIY vs contractor breakdown, permit/planning-permission guidance, and materials list with Amazon links, for any country.", "operationId": "homeImprove", "security": [ { "x402": [] } ], "parameters": [ { "name": "project", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Project type (e.g. kitchen-remodel, deck-addition, new-roof)" }, { "name": "home_value", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Current estimated home value, in local currency" }, { "name": "location", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Postal code or city (e.g. 90210, M5V 2T6, SW1A, Berlin)" }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Country (e.g. US, UK, CA, DE, AU) \u2014 sets currency and permit/planning-permission terminology" }, { "name": "zip", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Legacy alias for location (ZIP/postal code)" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Improvement ROI analysis with materials list and DIY guidance" }, "402": { "description": "Payment required" } }, "x-price-usd": 0.1, "x-agent-use-case": "on-demand", "x-agent-chaining": "ROI-ranked improvements \u2014 chain to /api/home/roi for specific project; pairs with PropPulse /api/prop/valuate for home value impact; Angi/Thumbtack contractor links auto-appended" } }, "/api/home/maintain": { "get": { "summary": "Seasonal maintenance checklist", "description": "Prioritized task list (urgent/high/medium/low) with cost estimates, DIY feasibility, time estimates, tools/supplies with Amazon links, and total season cost range. Pass country for correct hemisphere/season handling (seasons run six months opposite in the Southern Hemisphere) and local currency.", "operationId": "homeMaintain", "security": [ { "x402": [] } ], "parameters": [ { "name": "season", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "spring", "summer", "fall", "winter" ] }, "description": "Defaults to current season (hemisphere-corrected when country is given)" }, { "name": "region", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Region or state/province (e.g. Northeast, Pacific Northwest, Bavaria, New South Wales)" }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Country (e.g. US, UK, CA, DE, AU) \u2014 corrects season/hemisphere and local terminology" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Seasonal maintenance checklist with costs and supplies" }, "402": { "description": "Payment required" } }, "x-price-usd": 0.08, "x-agent-use-case": "on-demand", "x-agent-chaining": "Run seasonally \u2014 Amazon + Angi contractor affiliate links auto-appended; pairs with /api/home/improve for items that reveal larger upgrade opportunities; pairs with /api/home/energy for efficiency maintenance items" } }, "/api/home/rent": { "get": { "summary": "Rental market analysis", "description": "Rent ranges by bedroom count, market trend, official government fair-market-rent data where available (US HUD FMR), best neighborhoods to rent, and renting vs buying comparison, for any country.", "operationId": "homeRent", "security": [ { "x402": [] } ], "parameters": [ { "name": "location", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Postal code or city (e.g. 90210, M5V 2T6, SW1A)" }, { "name": "city", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string" }, "description": "State/province; 2-letter US state code required for HUD FMR data" }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Country (e.g. US, UK, CA, DE, AU) \u2014 HUD FMR only applies when country is US/unspecified" }, { "name": "zip", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Legacy alias for location (ZIP/postal code)" }, { "name": "bedrooms", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "county", "in": "query", "required": false, "schema": { "type": "string" }, "description": "County name hint for HUD FMR matching (US only)" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Rental market analysis with price ranges and official benchmark data where available" }, "402": { "description": "Payment required" } }, "x-price-usd": 0.08, "x-agent-use-case": "on-demand", "x-agent-chaining": "Rental market analysis \u2014 pairs with PropPulse /api/prop/landlord for landlord operations; pairs with /api/home/neighborhood for location context" } }, "/api/home/contractor": { "get": { "summary": "Contractor vetting guide", "description": "Licensing/registration authority, insurance requirements, red flags, and contract checklist by trade, for any country's regulatory regime.", "operationId": "homeContractor", "security": [ { "x402": [] } ], "parameters": [ { "name": "trade", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Trade (plumber, electrician, roofer, etc.)" }, { "name": "location", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Postal code or city (e.g. 90210, M5V 2T6, SW1A, Berlin)" }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Country/jurisdiction (e.g. US, UK, CA, DE, AU) \u2014 determines the correct licensing authority" }, { "name": "zip", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Legacy alias for location (ZIP/postal code)" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Response language (default en)" } ], "responses": { "200": { "description": "Contractor vetting guide" }, "402": { "description": "Payment required" } }, "x-price-usd": 0.1, "x-agent-use-case": "on-demand", "x-agent-chaining": "Run before hiring a trade; pairs with /api/home/improve and /api/home/roi for project scoping" } }, "/api/home/energy": { "get": { "summary": "Home energy efficiency", "description": "Improvements ranked by payback period with the country-correct incentive program applied (US IRA 30% tax credits, UK ECO4/Boiler Upgrade Scheme, DE BEG grants, CA Greener Homes, AU state rebates).", "operationId": "homeEnergy", "security": [ { "x402": [] } ], "parameters": [ { "name": "home_type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Home type (single-family, condo, etc.)" }, { "name": "location", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Postal code or city (e.g. 90210, M5V 2T6, SW1A, Berlin)" }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Country (e.g. US, UK, CA, DE, AU) \u2014 determines which incentive programs apply" }, { "name": "zip", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Legacy alias for location (ZIP/postal code)" }, { "name": "age", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Home age (years)" }, { "name": "sqft", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Square footage (or square meters \u2014 state units)" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Response language (default en)" } ], "responses": { "200": { "description": "Home energy efficiency" }, "402": { "description": "Payment required" } }, "x-price-usd": 0.1, "x-agent-use-case": "on-demand", "x-agent-chaining": "Pairs with /api/home/maintain for efficiency maintenance items; pairs with /api/home/improve for financed retrofits" } }, "/api/home/maintenance": { "get": { "summary": "Personalized home maintenance calendar", "description": "Seasonal maintenance schedule by region, home age, and features, for any country (hemisphere-corrected seasons).", "operationId": "homeMaintenance", "security": [ { "x402": [] } ], "parameters": [ { "name": "region", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Region or state/province (e.g. Northeast, Bavaria, New South Wales)" }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Country (e.g. US, UK, CA, DE, AU) \u2014 corrects hemisphere/season and terminology" }, { "name": "home_age", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Home age (years)" }, { "name": "season", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Season (spring, summer, fall, winter, all)" }, { "name": "features", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Home features (pool, well, etc.)" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Response language (default en)" } ], "responses": { "200": { "description": "Personalized home maintenance calendar" }, "402": { "description": "Payment required" } }, "x-price-usd": 0.08, "x-agent-use-case": "on-demand", "x-agent-chaining": "Full-year variant of /api/home/maintain; pairs with /api/home/energy for efficiency items" } }, "/api/home/roi": { "get": { "summary": "Home improvement resale ROI", "description": "Cost-vs-value resale return by project, region, and country. Uses NAR Cost vs Value data for the US; for other countries uses the closest available local benchmark and states its data basis.", "operationId": "homeRoi", "security": [ { "x402": [] } ], "parameters": [ { "name": "project", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Project (kitchen remodel, deck, etc.)" }, { "name": "region", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Region" }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Country (e.g. US, UK, CA, DE, AU) \u2014 NAR Cost vs Value is a US-specific benchmark; other countries get local guidance" }, { "name": "home_value", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Current home value, in local currency" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Response language (default en)" } ], "responses": { "200": { "description": "Home improvement resale ROI" }, "402": { "description": "Payment required" } }, "x-price-usd": 0.1, "x-agent-use-case": "on-demand", "x-agent-chaining": "Pairs with /api/home/improve for a broader project shortlist" } }, "/api/home/smart": { "get": { "summary": "Smart home ecosystem advisor", "description": "Matter compatibility, device recommendations, ecosystem fit, and local plug/voltage/availability notes, for any country.", "operationId": "homeSmart", "security": [ { "x402": [] } ], "parameters": [ { "name": "ecosystem", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Ecosystem (Alexa, HomeKit, Google Home)" }, { "name": "room", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Room" }, { "name": "budget", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Budget, in local currency" }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Country (e.g. US, UK, CA, DE, AU) \u2014 affects plug type/voltage, currency, and regional device availability" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Response language (default en)" } ], "responses": { "200": { "description": "Smart home ecosystem advisor" }, "402": { "description": "Payment required" } }, "x-price-usd": 0.08, "x-agent-use-case": "on-demand", "x-agent-chaining": "Pairs with /api/home/energy for efficiency-focused device picks" } } } }