Basic Appraisal Flow
This tutorial takes you from zero to getting your first real estate appraisal. It's the
"Hello World" of the Place Analyzer API.The 3 Main Endpoints
This flow uses 3 different endpoints that work together. Each step has its complete documentation in the
API Reference:| # | Method | Endpoint | Description |
|---|---|---|---|
| 1 | POST | /valuation-request | Create request → you get requestCode |
| 2 | GET | /valuation-request/\{requestCode\} | Check status → verify if it's COMPLETED |
| 3 | GET | /valuation-request/\{requestCode\}/result | Get result → receive the complete appraisal |
The Lifecycle of an Appraisal
Appraisals in Place Analyzer are asynchronous. This means that:
- You send a request for appraisal (takes seconds) → You receive a
requestCode - You check the status periodically (every 5-10 seconds) → You verify if it's
COMPLETED - You get the complete result when it's ready → You receive the final appraisal
Step 1: Create the Appraisal Request
What do you need?
To create an appraisal, the fields always required are latitude, longitude, and property.propertyType. Additional fields inside property depend on propertyType:
| Field | Type | Description | When required |
|---|---|---|---|
latitude / longitude | number | GPS coordinates | Always |
property.propertyType | string | Property type (Casa, Departamento, Terreno, …) | Always |
property.m2Land | number | Land square meters | Terreno and other types (not Departamento) |
property.m2Built | number | Built square meters | Other types (not Terreno nor Departamento) |
property.m2Covered | number | Covered square meters | Departamento |
property.m2SemiCovered | number | Semi-covered square meters | Departamento |
property.propertyAge | string | Property age | Departamento and other types |
property.propertyCondition | string | Condition | Other types (not Terreno nor Departamento) |
Finding coordinates
You can get coordinates in several ways:
📍 Option 1: Google Maps
- Search for the address in Google Maps
- Right-click on the point
- Select "What's here"
- Copy the coordinates in "lat, lng" format
📍 Option 2: Online tools
📍 Option 3: Geocoding API
// Example with Google Geocoding API const geocodeResponse = await fetch( `https://maps.googleapis.com/maps/api/geocode/json?address=${encodeURIComponent(address)}` );
Make the request
Send a POST request to the /valuation-request endpoint with the property data:
Example with curl:
curl -X POST "https://api.place-api.com/valuation/v1/valuation-request" \
-H "X-API-KEY: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"lat": -34.603722,
"lng": -58.381592,
"m2Land": 300,
"m2Built": 200,
"propertyType": "Casa",
"reportSettings": {
"sector": "COMERCIAL",
"category": "Supermercado",
"includePopulationData": true,
"includeCommerceAnalysis": true
}
}'Successful response (201):
{ "requestCode": "PA-2025-001234", "status": "PENDING_PROCESSING", "createdAt": "2025-01-15T10:30:00Z", "estimatedCompletion": "2025-01-15T10:35:00Z", "message": "Appraisal request created successfully" }
Step 2: Check the Status
Appraisals take time to process (2-5 minutes). You must check the status periodically until it changes to COMPLETED.
Example with curl:
curl -X GET "https://api.place-api.com/valuation/v1/valuation-request/PA-2025-001234" \
-H "X-API-KEY: your_api_key_here"Response while processing:
{ "requestCode": "PA-2025-001234", "status": "PENDING_PROCESSING", "createdAt": "2025-01-15T10:30:00Z", "estimatedCompletion": "2025-01-15T10:35:00Z" }
Response when ready:
{ "requestCode": "PA-2025-001234", "status": "COMPLETED", "createdAt": "2025-01-15T10:30:00Z", "completedAt": "2025-01-15T10:32:45Z", "resultAvailable": true }
Possible states
| State | Description | Result available? |
|---|---|---|
PENDING_PROCESSING | Queued for processing | ❌ No |
PROCESSING | Being processed | ❌ No |
COMPLETED | Processing finished | ✅ Yes |
FAILED | Error during processing | ❌ No |
CANCELLED | Cancelled by user | ❌ No |
Polling Strategy
JavaScript:
// requestCode obtained from Step 1: "abc-123-xyz-456" const requestCode = "abc-123-xyz-456"; const apiKey = "your_api_key_here"; async function waitForCompletion(requestCode, apiKey) { while (true) { const response = await fetch( `{VALUATION_API_URL}/valuation-request/${requestCode}`, { headers: { 'X-API-KEY': apiKey } } ); const status = await response.json(); if (status.status === 'COMPLETED') { return status; } else if (status.status === 'FAILED') { throw new Error('Appraisal failed'); } // Wait 5 seconds before querying again await new Promise(resolve => setTimeout(resolve, 5000)); } } // Use the function waitForCompletion(requestCode, apiKey).then(data => { console.log('Appraisal completed:', data); });
Python:
import time import requests # requestCode obtained from Step 1 request_code = "abc-123-xyz-456" api_key = "your_api_key_here" def wait_for_completion(request_code, api_key): while True: response = requests.get( f'{VALUATION_API_URL}/valuation-request/{request_code}', headers={'X-API-KEY': api_key} ) status = response.json() if status['status'] == 'COMPLETED': return status elif status['status'] == 'FAILED': raise Exception('Appraisal failed') # Wait 5 seconds time.sleep(5) # Use the function result = wait_for_completion(request_code, api_key) print('Appraisal completed:', result)
Step 3: Get the Complete Result
Once the status is COMPLETED, request the complete appraisal result:
Example with curl:
curl -X GET "https://api.place-api.com/valuation/v1/valuation-request/PA-2025-001234/result" \
-H "X-API-KEY: your_api_key_here"Successful response (200):
{ "requestCode": "PA-2025-001234", "propertyId": "PROP-456789", "status": "COMPLETED", "createdAt": "2025-01-15T10:30:00Z", "completedAt": "2025-01-15T10:32:45Z", "result": { "estimatedBuildValue": 45000000, "estimatedLandValue": 30000000, "totalEstimatedValue": 75000000, "currency": "ARS", "confidence": 0.87, "valuationDate": "2025-01-15", "propertyDetails": { "lat": -34.603722, "lng": -58.381592, "m2Land": 300, "m2Built": 200, "propertyType": "Casa", "yearBuilt": 2010, "bedrooms": 3, "bathrooms": 2, "parkingSpaces": 1, "amenities": ["GARDEN", "GARAGE"] }, "marketAnalysis": { "zoneName": "Palermo", "averagePricePerM2": 250000, "priceTrend": "STABLE", "comparableProperties": 15, "marketLiquidity": "HIGH" } } }
What does each field mean?
| Field | Description | Example |
|---|---|---|
estimatedBuildValue | Construction value | $45,000,000 |
estimatedLandValue | Land value | $30,000,000 |
totalEstimatedValue | Total property value | $75,000,000 |
confidence | Confidence level (0-1) | 0.87 (87%) |
currency | Appraisal currency | ARS, USD |
zoneName | Zone name | Palermo, Recoleta |
averagePricePerM2 | Average price per m² in the area | $250,000 |
📋 Summary: Difference between the 3 endpoints
It's important to understand that each endpoint has a specific purpose:
| Step | Endpoint | Method | What it returns | When to call it |
|---|---|---|---|---|
| 1 | /valuation-request | POST | requestCode + initial status | Once at the beginning |
| 2 | /valuation-request/\{code\} | GET | Only the current status | Multiple times in loop until COMPLETED |
| 3 | /valuation-request/\{code\}/result | GET | Complete appraisal with all values | Once when status = COMPLETED |
💡 Tip: Step 2 is for monitoring (lightweight), Step 3 is for getting the actual data (heavyweight).
Complete Example in JavaScript
Here's a complete example that integrates all three steps:
const API_BASE = 'https://api.place-api.com/valuation/v1';
const API_KEY = 'your_api_key_here';
async function createValuation() {
try {
// ============================================================
// STEP 1: Create request (POST /valuation-request)
// ============================================================
console.log('🚀 Step 1: Creating appraisal request...');
const createResponse = await fetch(`${API_BASE}/valuation-request`, {
method: 'POST',
headers: {
'X-API-KEY': API_KEY,
'Content-Type': 'application/json'
},
body: JSON.stringify({
lat: -34.603722,
lng: -58.381592,
m2Land: 300,
m2Built: 200,
propertyType: 'Casa',
reportSettings: {
sector: 'COMERCIAL',
category: 'Supermercado'
}
})
});
const createResult = await createResponse.json();
const requestCode = createResult.requestCode;
console.log(`✅ Request created: ${requestCode}`);
// ============================================================
// STEP 2: Check status (GET /valuation-request/{requestCode})
// ============================================================
console.log('⏳ Step 2: Waiting for status to be COMPLETED...');
await waitForCompletion(requestCode);
console.log('✅ Status: COMPLETED');
// ============================================================
// STEP 3: Get result (GET /valuation-request/{requestCode}/result)
// ============================================================
console.log('📊 Step 3: Getting complete result...');
const resultResponse = await fetch(`${API_BASE}/valuation-request/${requestCode}/result`, {
headers: { 'X-API-KEY': API_KEY }
});
const finalResult = await resultResponse.json();
console.log('🎉 Appraisal completed!');
console.log(`💰 Estimated value: $${finalResult.result.totalEstimatedValue.toLocaleString()}`);
console.log(`📍 Zone: ${finalResult.result.marketAnalysis.zoneName}`);
console.log(`🎯 Confidence: ${(finalResult.result.confidence * 100).toFixed(1)}%`);
return finalResult;
} catch (error) {
console.error('❌ Error:', error.message);
}
}
async function waitForCompletion(requestCode) {
while (true) {
const response = await fetch(`${API_BASE}/valuation-request/${requestCode}`, {
headers: { 'X-API-KEY': API_KEY }
});
const status = await response.json();
if (status.status === 'COMPLETED') {
return;
} else if (status.status === 'FAILED') {
throw new Error('Appraisal failed');
}
console.log(`⏳ Status: ${status.status} - Waiting 5 seconds...`);
await new Promise(resolve => setTimeout(resolve, 5000));
}
}
// Run the example
createValuation();Conclusion
Congratulations! 🎉 You've completed your first appraisal with the Place Analyzer API.
Summary of what you learned:
- ✅ Step 1:
POST /valuation-request- Create request and getrequestCode - ✅ Step 2:
GET /valuation-request/\{requestCode\}- Monitor status untilCOMPLETED - ✅ Step 3:
GET /valuation-request/\{requestCode\}/result- Get complete result - ✅ Interpret estimated values, market analysis, and confidence level
🚀 Recommended next steps:
Now that you master the basic flow, explore more functionalities:
- 📚 Complete API Reference - Explore all available parameters and options
- 📊 Generate reports - Add demographic data and commercial analysis
- 📊 Statistical data - Get demographic and commercial data
- 🔍 Query nearby properties - Get comparables for analysis
💬 Need help?
- ❌ Errors: Check the error handling guide
- 🔑 Authentication: Review the authentication guide
- 📖 Glossary: Understand all terms in the glossary and states