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.

New to our APIs? Start with the Quick Start Guide to get up and running in minutes.

Quick Start

Get started with Homesage.ai APIs in just a few steps:

1. Get Your API Key

Sign up for a developer account and generate your JWT token through our Developer Portal.

2. Make Your First Request
JavaScript
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));
3. Explore the APIs

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.

JWT Token Structure

Algorithm: HS256 (HMAC with SHA-256)

Token Format: Bearer YOUR_JWT_TOKEN

Header Example:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Obtaining a Token
  1. Register for a developer account at our Developer Portal
  2. Navigate to the API Keys section
  3. Generate a new JWT token
  4. Store the token securely
Keep your JWT token secure and never expose it in client-side code or public repositories.
Token Expiration

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

Investment Analysis APIs

Interactive API Playground

Response

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.

Each recipe includes complete, working code that you can copy and use immediately in your applications.

Complete Property Analyzer

Property Analysis

Get 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.

APIs Used
/api/properties/info/ /api/properties/comps/ /api/properties/investment_potential/
View Implementation Code
JavaScript
JavaScript
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

Financial

Build a flexible investment calculator that allows users to input their own financial assumptions to analyze a property's long-term rental performance.

APIs Used
/api/properties/investment_potential/ /api/properties/rental/long_term/
View Implementation Code
JavaScript
JavaScript
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

Investment

Create a tool to quickly assess the viability of a house flip by combining purchase price, renovation cost estimates, and after-repair value (ARV).

APIs Used
/api/properties/flip_return/ /api/properties/renovation/cost/ /api/properties/comps/
View Implementation Code
JavaScript
JavaScript
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

Rental

Compare the potential income from long-term vs. short-term (vacation) rental strategies for a given property to determine the most profitable use case.

APIs Used
/api/properties/rental/long_term/ /api/properties/rental/short_term/
View Implementation Code
JavaScript
JavaScript
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 CodeError TypeDescription
200SuccessRequest completed successfully
400Bad RequestInvalid request parameters or missing required fields
401UnauthorizedInvalid or expired JWT token
402Payment RequiredInsufficient credits or no subscription plan
404Not FoundProperty or resource not found
429Too Many RequestsRate limit exceeded
500Internal Server ErrorUnexpected 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

PlanRequests/HourRequests/DayConcurrent Requests
Free1001,0005
Starter1,00010,00010
Professional5,00050,00025
EnterpriseCustomCustomCustom
Rate limits are enforced per API key. Contact support for higher limits.