API Documentation
Welcome to the Homesage.ai API documentation. Our comprehensive real estate APIs provide access to property data, investment analysis, and rental calculations for properties across the United States.
Quick Start
Get started with Homesage.ai APIs in just a few steps:
Sign up for a developer account and generate your JWT token through our Developer Portal.
const token = 'YOUR_JWT_TOKEN';
fetch('https://developers.homesage.ai/api/properties/info/?property_address=123+Main+St,Austin,TX+78701', {
method: 'GET',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
}
})
.then(response => response.json())
.then(data => console.log(data));
Use our interactive API playground below to test endpoints and see responses in real-time.
Authentication
Homesage.ai uses JWT (JSON Web Token) authentication for API access. All API requests must include a valid JWT token in the Authorization header.
Algorithm: HS256 (HMAC with SHA-256)
Token Format: Bearer YOUR_JWT_TOKEN
Header Example:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
- Register for a developer account at our Developer Portal
- Navigate to the API Keys section
- Generate a new JWT token
- Store the token securely
JWT tokens are valid for 30 days by default. You can configure custom expiration times in the Developer Portal. When a token expires, you'll receive a 401 Unauthorized response.
Base URL
All API requests should be made to:
https://developers.homesage.ai
Property APIs
Property Info
/api/properties/info/
Get comprehensive property details including characteristics, ownership, tax information, and market data.
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
property_address | string | Required* | Full property address (URL encoded) |
property_id | string | Required* | Base64 encoded property ID |
* Either property_address or property_id is required
Example Request
curl -X GET "https://developers.homesage.ai/api/properties/info/?property_address=123+Main+St,Austin,TX+78701" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
const response = await fetch('https://developers.homesage.ai/api/properties/info/?property_address=123+Main+St,Austin,TX+78701', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_JWT_TOKEN'
}
});
const data = await response.json();
console.log(data);
import requests
url = "https://developers.homesage.ai/api/properties/info/"
headers = {"Authorization": "Bearer YOUR_JWT_TOKEN"}
params = {"property_address": "123 Main St, Austin, TX 78701"}
response = requests.get(url, headers=headers, params=params)
print(response.json())
Response Example
{
"address": {
"street": "123 Main St",
"city": "Austin",
"state": "TX",
"zip": "78701"
},
"list_date": "2023-10-01",
"status": "for_sale",
"listing_price": 425000,
"estimated_value": 420000,
"sf": 1850,
"psf": 229.73,
"dom": 15,
"property_features": {
"bedrooms": 3,
"bathrooms": 2,
"year_built": 1998,
"property_type": "Single Family"
},
"location_community": {
"community_name": "Downtown Austin"
},
"building_info": {
"stories": 2,
"construction": "Frame",
"roof": "Composition"
},
"lot": {
"size": 6500,
"dimensions": "65x100"
},
"parking": {
"garage_spaces": 2,
"covered_spaces": 0
},
"interior_features": [...],
"home_value": {...},
"utilities": {...},
"listing_office": {...},
"listing_details": {...},
"property_history": [...],
"school_ratings": {...},
"photos": [...]
}
Property Comps
/api/properties/comps/
Get comparable properties for valuation and market analysis, including recently sold, for sale, and off-market properties.
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
property_address | string | Required | Full property address |
radius | float | Optional | Search radius in miles (default: 0.5) |
limit | integer | Optional | Number of comparables to return (default: 10) |
Example Request
curl -X GET "https://developers.homesage.ai/api/properties/comps/?property_address=123+Main+St,Austin,TX+78701&limit=5" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
Response Example
{
"subject_property": {
"address": "123 Main St, Austin, TX 78701"
},
"comparables": [
{
"address": "246 Oak Ave, Austin, TX 78701",
"distance_miles": 0.2,
"status": "sold",
"sold_date": "2023-11-15",
"sold_price": 415000,
"sf": 1800,
"bedrooms": 3,
"bathrooms": 2
},
{
"address": "789 Pine Ln, Austin, TX 78701",
"distance_miles": 0.4,
"status": "for_sale",
"listing_price": 435000,
"sf": 1900,
"bedrooms": 3,
"bathrooms": 2.5
}
]
}
Property Condition
/api/properties/property-condition/
Get AI-powered property condition assessment based on available data and images. Useful for estimating renovation needs.
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
property_address | string | Required | Full property address |
Example Request
curl -X GET "https://developers.homesage.ai/api/properties/property-condition/?property_address=123+Main+St,Austin,TX+78701" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
Response Example
{
"condition_score": 7.8,
"summary": "Property appears to be in good condition with some signs of aging. Roof and HVAC may need inspection.",
"details": {
"exterior": "Good",
"roof": "Fair",
"interior": "Good",
"kitchen": "Excellent (recently updated)",
"bathrooms": "Good"
},
"estimated_repair_costs": 7500
}
SQFT Analysis
/api/properties/sqft-per-floor/
Get detailed square footage breakdown for each floor of the property.
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
property_address | string | Required | Full property address |
Example Request
curl -X GET "https://developers.homesage.ai/api/properties/sqft-per-floor/?property_address=123+Main+St,Austin,TX+78701" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
Response Example
{
"total_living_area_sf": 1850,
"breakdown": [
{ "floor": "1st Floor", "sf": 1050 },
{ "floor": "2nd Floor", "sf": 800 }
],
"other_areas": {
"basement_sf": 0,
"garage_sf": 400
}
}
Address Autocomplete
/api/properties/auto-complete/
Autocomplete property addresses as users type for better UX.
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
input | string | Required | Partial address to search for (minimum 2 characters) |
Example Request
curl -X GET "https://developers.homesage.ai/api/properties/auto-complete/?input=123+Main+St" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
Response Example
{
"outcome": "success",
"data": [
{
"text": "123 Main St, Austin, TX 78701, USA",
"address": "123 Main St, Austin, TX 78701, USA",
"city": "Austin",
"postal_code": "78701",
"state_code": "TX"
}
]
}
Price Flexibility Score
/api/properties/pfs/
Get the Price Flexibility Score (PFS) for a property, indicating how negotiable the listing price might be.
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
property_address | string | Required* | Full property address |
property_id | string | Required* | Base64 encoded property ID |
* Either property_address or property_id is required
Example Request
curl -X GET "https://developers.homesage.ai/api/properties/pfs/?property_address=123+Main+St,Austin,TX+78701" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
Response Example
{
"pfs": 7.5
}
Note: PFS ranges from 0-10, where higher scores indicate greater price flexibility.
TLC Analysis
/api/properties/tlc/
Determine if a property needs "Tender Loving Care" (TLC) based on its condition and characteristics.
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
property_address | string | Required* | Full property address |
property_id | string | Required* | Base64 encoded property ID |
* Either property_address or property_id is required
Example Request
curl -X GET "https://developers.homesage.ai/api/properties/tlc/?property_address=123+Main+St,Austin,TX+78701" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
Response Example
{
"is_tlc": true
}
Property Condition with Photos
/api/properties/property-condition-custom-photos/
Advanced property condition assessment using AI image analysis. Supports both database lookup and custom photo analysis.
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
address | string | Optional* | Full property address |
image_urls | string | Optional* | Comma-separated image URLs (GET) or array (POST) |
images | files | Optional* | Image file uploads (POST only) |
* Either address or images (URLs/files) must be provided
Example Requests
curl -X GET "https://developers.homesage.ai/api/properties/property-condition-custom-photos/?address=123+Main+St,Austin,TX+78701&image_urls=https://example.com/photo1.jpg,https://example.com/photo2.jpg" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
curl -X POST "https://developers.homesage.ai/api/properties/property-condition-custom-photos/" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-F "address=123 Main St, Austin, TX 78701" \
-F "images=@/path/to/photo1.jpg" \
-F "images=@/path/to/photo2.jpg"
const formData = new FormData();
formData.append('address', '123 Main St, Austin, TX 78701');
formData.append('images', photoFile1);
formData.append('images', photoFile2);
const response = await fetch('https://developers.homesage.ai/api/properties/property-condition-custom-photos/', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_JWT_TOKEN'
},
body: formData
});
const data = await response.json();
Response Example
{
"address": "123 Main St, Austin, TX 78701",
"property_condition": "Good",
"confidence_score": 0.85,
"details": {
"exterior": "Good - Well-maintained siding and paint",
"roof": "Good - Shingles appear in good condition",
"landscaping": "Excellent - Professional landscaping visible",
"overall_impression": "Property shows signs of regular maintenance"
}
}
Possible conditions: Excellent, Good, Outdated, Poor, Very Poor, Unpredictable
Bulk Property Info
/api/properties/bulk-info/
Get property information for multiple properties filtered by location criteria.
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
city | string | Optional* | City name |
state | string | Optional* | State code (e.g., TX, CA) |
zip | string | Optional* | ZIP code |
status | string | Required | Property status: "active" or "sold" |
listing_age | string | Optional | Max days on market (e.g., "30", "90") |
updated_since | string | Optional | ISO 8601 date (YYYY-MM-DDTHH:MM:SSZ) |
limit | integer | Optional | Max results to return (default: 10, max: 100) |
* At least one location parameter (city, state, or zip) is required
Example Request
curl -X GET "https://developers.homesage.ai/api/properties/bulk-info/?state=TX&city=Austin&status=active&limit=5" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
Response Example
{
"count": 5,
"results": [
{
"address": "123 Main St, Austin, TX 78701",
"property_type": "Single Family",
"bedrooms": 3,
"bathrooms": 2,
"square_feet": 1850,
"listing_price": 425000,
"year_built": 1998,
"status": "active"
}
]
}
Full Report
/api/properties/full-report/
Generate a complete property report with all available data and analysis.
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
property_address | string | Required | Full property address |
Response Example
{
"report_id": "rep_12345",
"generated_at": "2023-10-27T10:00:00Z",
"property_info": { "...": "..." },
"comparables": { "...": "..." },
"investment_analysis": { "...": "..." },
"rental_analysis": { "...": "..." }
}
Investment Analysis APIs
Investment Potential
/api/properties/investment_potential/
Analyze investment potential with cash flow, ROI, and cap rate calculations.
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
property_address | string | Required | Full property address |
purchase_price | float | Optional | Override purchase price |
down_payment_percent | float | Optional | Down payment percentage (default: 20) |
interest_rate | float | Optional | Loan interest rate (default: current market rate) |
Response Example
{
"investment_potential": "High Potential"
}
Flip Return
/api/properties/flip_return/
Calculate potential returns for house flipping investments.
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
property_address | string | Required* | Full property address |
property_id | string | Required* | Base64 encoded property ID |
cash_or_financed | string | Optional | Purchase method: "cash" or "financed" (default: "cash") |
downpayment | float | Optional | Down payment percentage if financed (default: 20) |
interest_rate | float | Optional | Interest rate if financed (default: 4.5) |
loan_term | integer | Optional | Loan term in years if financed (default: 30) |
sqft | float | Optional | Override property square footage |
* Either property_address or property_id is required
Response Example
{
"total_project_cost": 350000.00,
"profit": 64000.00,
"resale_roi": 18.28,
"max_recommended_renovation_budget": 50000.00
}
Renovation Return
/api/properties/renovation_return/
Calculate return on investment for specific renovation projects.
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
property_address | string | Required* | Full property address |
property_id | string | Required* | Base64 encoded property ID |
cash_or_financed | string | Optional | Purchase method: "cash" or "financed" (default: "cash") |
downpayment | float | Optional | Down payment percentage if financed (default: 20) |
interest_rate | float | Optional | Interest rate if financed (default: 4.5) |
loan_term | integer | Optional | Loan term in years if financed (default: 30) |
sqft | float | Optional | Override property square footage |
* Either property_address or property_id is required
Example Request
curl -X GET "https://developers.homesage.ai/api/properties/renovation_return/?property_address=123+Main+St,Austin,TX+78701" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
Response Example
{
"daily_gross": 106.67,
"daily_net": 73.33,
"monthly_gross": 3200.00,
"monthly_net": 2200.00,
"annual_gross": 38400.00,
"annual_net": 26400.00,
"irr": 12.50,
"cash_flow": 15000.00,
"cap_rate": 5.80,
"noi": 26400.00,
"cash_on_cash": 7.50
}
Long-Term Rental
/api/properties/rental/long_term/
Analyze long-term rental income potential and cash flow.
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
property_address | string | Required* | Full property address |
property_id | string | Required* | Base64 encoded property ID |
cash_or_financed | string | Optional | Purchase method: "cash" or "financed" (default: "cash") |
downpayment | float | Optional | Down payment percentage if financed (default: 20) |
interest_rate | float | Optional | Interest rate if financed (default: 4.5) |
loan_term | integer | Optional | Loan term in years if financed (default: 30) |
sqft | float | Optional | Override property square footage |
* Either property_address or property_id is required
Response Example
{
"Daily Gross": 83.33,
"Daily Net": 56.67,
"Monthly Gross": 2500,
"Monthly Net": 1700,
"Annual Gross": 30000,
"Annual Net": 20400,
"Rental IRR": 12.5,
"Long-Term Cash Flow": 15000,
"Long-Term Cap Rate": 5.8,
"Net Operating Income (NOI)": 20400,
"Cash-on-Cash": 7.5
}
Short-Term Rental
/api/properties/rental/short_term/
Analyze short-term rental (Airbnb) income potential.
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
property_address | string | Required* | Full property address |
property_id | string | Required* | Base64 encoded property ID |
* Either property_address or property_id is required
Response Example
{
"irr_percentage": 15.2,
"cash_flow_monthly": 1200,
"cash_flow_annually": 14400,
"cap_rate": 6.5,
"short_term_monthly_gross": 4050,
"short_term_annual_gross": 48600,
"short_term_noi_monthly": 3200,
"short_term_noi_annual": 38400,
"short_term_daily_gross": 135.0,
"short_term_monthly_net": 2800,
"short_term_daily_net": 93.33,
"short_term_annual_net": 33600,
"short_term_cash_on_cash": 8.5
}
Renovation Cost
/api/properties/renovation/cost/
Estimate renovation costs based on property condition and scope.
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
property_address | string | Required* | Full property address |
property_id | string | Required* | Base64 encoded property ID |
cash_or_financed | string | Optional | Purchase method: "cash" or "financed" (default: "cash") |
downpayment | float | Optional | Down payment percentage if financed (default: 20) |
interest_rate | float | Optional | Interest rate if financed (default: 4.5) |
loan_term | integer | Optional | Loan term in years if financed (default: 30) |
sqft | float | Optional | Override property square footage |
* Either property_address or property_id is required
Response Example
{
"renovation_cost": 45000.00,
"full_potential": 520000.00,
"spread": 70000.00,
"value_gap": 15.56,
"estimated_value_increase": 70000.00
}
Home Value Graph
/api/properties/home_value_graph/
Get historical home value data and trend analysis.
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
property_address | string | Required* | Full property address |
property_id | string | Required* | Base64 encoded property ID |
* Either property_address or property_id is required
Response Example
{
"home_value_graph": [
{"date": "2023-12", "value": 420000},
{"date": "2023-11", "value": 418000},
{"date": "2023-10", "value": 415000},
{"date": "2023-09", "value": 412000},
{"date": "2023-08", "value": 410000}
]
}
Interactive API Playground
API Recipes
Ready-to-use code examples that combine multiple API endpoints to solve real-world real estate problems. These recipes demonstrate best practices and show how to build powerful applications with Homesage.ai APIs.
Complete Property Analyzer
Property AnalysisGet a comprehensive analysis of any property including details, comparables, and investment potential. Perfect for real estate agents creating listing presentations or buyers doing due diligence.
async function analyzeProperty(address, token) {
const baseUrl = 'https://developers.homesage.ai';
const headers = { 'Authorization': `Bearer ${token}` };
try {
// 1. Get property details
const propertyInfo = await fetch(
`${baseUrl}/api/properties/info/?property_address=${encodeURIComponent(address)}`,
{ headers }
).then(res => res.json());
// 2. Get comparable properties
const comps = await fetch(
`${baseUrl}/api/properties/comps/?property_address=${encodeURIComponent(address)}`,
{ headers }
).then(res => res.json());
// 3. Get investment analysis
const investment = await fetch(
`${baseUrl}/api/properties/investment_potential/?property_address=${encodeURIComponent(address)}`,
{ headers }
).then(res => res.json());
return {
property: propertyInfo,
comparables: comps,
investment: investment
};
} catch (error) {
console.error('Error analyzing property:', error);
throw error;
}
}
// Usage
const analysis = await analyzeProperty('123 Main St, Austin, TX 78701', 'YOUR_JWT_TOKEN');
console.log(analysis);
Investment Calculator
FinancialBuild a flexible investment calculator that allows users to input their own financial assumptions to analyze a property's long-term rental performance.
async function calculateInvestmentReturns(address, financialParams, token) {
const baseUrl = 'https://developers.homesage.ai';
const headers = { 'Authorization': `Bearer ${token}` };
// Build query parameters for financial assumptions
const queryParams = new URLSearchParams({
property_address: address,
cash_or_financed: financialParams.purchaseMethod || 'financed',
downpayment: financialParams.downPaymentPercent || 20,
interest_rate: financialParams.interestRate || 4.5,
loan_term: financialParams.loanTerm || 30
});
try {
// 1. Get investment potential analysis
const investmentPotential = await fetch(
`${baseUrl}/api/properties/investment_potential/?property_address=${encodeURIComponent(address)}`,
{ headers }
).then(res => res.json());
// 2. Get detailed long-term rental analysis
const rentalAnalysis = await fetch(
`${baseUrl}/api/properties/rental/long_term/?${queryParams}`,
{ headers }
).then(res => res.json());
return {
investmentRating: investmentPotential.investment_potential,
rental: {
monthlyGross: rentalAnalysis['Monthly Gross'],
monthlyNet: rentalAnalysis['Monthly Net'],
annualNet: rentalAnalysis['Annual Net'],
cashOnCash: rentalAnalysis['Cash-on-Cash'],
capRate: rentalAnalysis['Long-Term Cap Rate'],
cashFlow: rentalAnalysis['Long-Term Cash Flow']
}
};
} catch (error) {
console.error('Error calculating investment returns:', error);
throw error;
}
}
// Usage
const params = {
purchaseMethod: 'financed',
downPaymentPercent: 25,
interestRate: 6.5,
loanTerm: 30
};
const investment = await calculateInvestmentReturns('123 Main St, Austin, TX 78701', params, 'YOUR_JWT_TOKEN');
console.log(investment);
House Flip Analyzer
InvestmentCreate a tool to quickly assess the viability of a house flip by combining purchase price, renovation cost estimates, and after-repair value (ARV).
async function analyzeFlipOpportunity(address, token) {
const baseUrl = 'https://developers.homesage.ai';
const headers = { 'Authorization': `Bearer ${token}` };
try {
// 1. Get flip return analysis
const flipAnalysis = await fetch(
`${baseUrl}/api/properties/flip_return/?property_address=${encodeURIComponent(address)}`,
{ headers }
).then(res => res.json());
// 2. Get renovation cost estimates
const renovationCosts = await fetch(
`${baseUrl}/api/properties/renovation/cost/?property_address=${encodeURIComponent(address)}`,
{ headers }
).then(res => res.json());
// 3. Get comparable sales for ARV estimation
const comps = await fetch(
`${baseUrl}/api/properties/comps/?property_address=${encodeURIComponent(address)}&limit=5`,
{ headers }
).then(res => res.json());
// Calculate average sold price from comparables
const soldComps = comps.comparables.filter(comp => comp.status === 'sold');
const avgSoldPrice = soldComps.reduce((sum, comp) => sum + comp.sold_price, 0) / soldComps.length;
return {
flip: {
totalProjectCost: flipAnalysis.total_project_cost,
profit: flipAnalysis.profit,
roi: flipAnalysis.resale_roi,
maxRenovationBudget: flipAnalysis.max_recommended_renovation_budget
},
renovation: {
estimatedCost: renovationCosts.renovation_cost,
afterRepairValue: renovationCosts.full_potential,
valueIncrease: renovationCosts.estimated_value_increase
},
market: {
comparablesSoldAvg: avgSoldPrice,
comparablesCount: soldComps.length
}
};
} catch (error) {
console.error('Error analyzing flip opportunity:', error);
throw error;
}
}
// Usage
const flipAnalysis = await analyzeFlipOpportunity('123 Main St, Austin, TX 78701', 'YOUR_JWT_TOKEN');
console.log(`Estimated Profit: $${flipAnalysis.flip.profit}`);
console.log(`ROI: ${flipAnalysis.flip.roi}%`);
console.log(`Max Renovation Budget: $${flipAnalysis.flip.maxRenovationBudget}`);
Rental Income Optimizer
RentalCompare the potential income from long-term vs. short-term (vacation) rental strategies for a given property to determine the most profitable use case.
async function compareRentalStrategies(address, token) {
const baseUrl = 'https://developers.homesage.ai';
const headers = { 'Authorization': `Bearer ${token}` };
try {
// 1. Get long-term rental analysis
const longTermRental = await fetch(
`${baseUrl}/api/properties/rental/long_term/?property_address=${encodeURIComponent(address)}`,
{ headers }
).then(res => res.json());
// 2. Get short-term rental analysis
const shortTermRental = await fetch(
`${baseUrl}/api/properties/rental/short_term/?property_address=${encodeURIComponent(address)}`,
{ headers }
).then(res => res.json());
// Compare the two strategies
const comparison = {
longTerm: {
monthlyGross: longTermRental['Monthly Gross'],
monthlyNet: longTermRental['Monthly Net'],
annualNet: longTermRental['Annual Net'],
capRate: longTermRental['Long-Term Cap Rate'],
cashOnCash: longTermRental['Cash-on-Cash']
},
shortTerm: {
monthlyGross: shortTermRental.short_term_monthly_gross,
monthlyNet: shortTermRental.short_term_monthly_net,
annualNet: shortTermRental.short_term_annual_net,
capRate: shortTermRental.cap_rate,
cashOnCash: shortTermRental.short_term_cash_on_cash
},
recommendation: null
};
// Determine the better strategy
const longTermAnnual = longTermRental['Annual Net'];
const shortTermAnnual = shortTermRental.short_term_annual_net;
if (shortTermAnnual > longTermAnnual * 1.2) {
comparison.recommendation = {
strategy: 'Short-Term Rental',
reason: `Short-term rental generates ${((shortTermAnnual - longTermAnnual) / longTermAnnual * 100).toFixed(1)}% more annual income`,
additionalIncome: shortTermAnnual - longTermAnnual
};
} else if (longTermAnnual > shortTermAnnual) {
comparison.recommendation = {
strategy: 'Long-Term Rental',
reason: 'Long-term rental provides more stable income with less management overhead',
additionalIncome: longTermAnnual - shortTermAnnual
};
} else {
comparison.recommendation = {
strategy: 'Either',
reason: 'Both strategies provide similar returns; consider management preference',
additionalIncome: 0
};
}
return comparison;
} catch (error) {
console.error('Error comparing rental strategies:', error);
throw error;
}
}
// Usage
const rentalComparison = await compareRentalStrategies('123 Main St, Austin, TX 78701', 'YOUR_JWT_TOKEN');
console.log(`Recommended Strategy: ${rentalComparison.recommendation.strategy}`);
console.log(`Reason: ${rentalComparison.recommendation.reason}`);
console.log(`Long-Term Annual Net: $${rentalComparison.longTerm.annualNet}`);
console.log(`Short-Term Annual Net: $${rentalComparison.shortTerm.annualNet}`);
Error Codes
Homesage.ai uses standard HTTP status codes and provides detailed error messages to help you troubleshoot issues.
Status Code | Error Type | Description |
---|---|---|
200 | Success | Request completed successfully |
400 | Bad Request | Invalid request parameters or missing required fields |
401 | Unauthorized | Invalid or expired JWT token |
402 | Payment Required | Insufficient credits or no subscription plan |
404 | Not Found | Property or resource not found |
429 | Too Many Requests | Rate limit exceeded |
500 | Internal Server Error | Unexpected server error |
Error Response Format
{
"error": "Property not found"
}
Rate Limits
API rate limits vary by plan tier to ensure fair usage and system stability.
Rate Limit Tiers
Plan | Requests/Hour | Requests/Day | Concurrent Requests |
---|---|---|---|
Free | 100 | 1,000 | 5 |
Starter | 1,000 | 10,000 | 10 |
Professional | 5,000 | 50,000 | 25 |
Enterprise | Custom | Custom | Custom |