Skip to main content
placeanalyzerAPI ReferenceGuías

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:

#MethodEndpointDescription
1POST/valuation-requestCreate request → you get requestCode
2GET/valuation-request/\{requestCode\}Check status → verify if it's COMPLETED
3GET/valuation-request/\{requestCode\}/resultGet result → receive the complete appraisal

The Lifecycle of an Appraisal

Appraisals in Place Analyzer are asynchronous. This means that:

  1. You send a request for appraisal (takes seconds) → You receive a requestCode
  2. You check the status periodically (every 5-10 seconds) → You verify if it's COMPLETED
  3. 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:

FieldTypeDescriptionWhen required
latitude / longitudenumberGPS coordinatesAlways
property.propertyTypestringProperty type (Casa, Departamento, Terreno, …)Always
property.m2LandnumberLand square metersTerreno and other types (not Departamento)
property.m2BuiltnumberBuilt square metersOther types (not Terreno nor Departamento)
property.m2CoverednumberCovered square metersDepartamento
property.m2SemiCoverednumberSemi-covered square metersDepartamento
property.propertyAgestringProperty ageDepartamento and other types
property.propertyConditionstringConditionOther types (not Terreno nor Departamento)

Finding coordinates

You can get coordinates in several ways:

📍 Option 1: Google Maps

  1. Search for the address in Google Maps
  2. Right-click on the point
  3. Select "What's here"
  4. 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

StateDescriptionResult available?
PENDING_PROCESSINGQueued for processing❌ No
PROCESSINGBeing processed❌ No
COMPLETEDProcessing finished✅ Yes
FAILEDError during processing❌ No
CANCELLEDCancelled 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?

FieldDescriptionExample
estimatedBuildValueConstruction value$45,000,000
estimatedLandValueLand value$30,000,000
totalEstimatedValueTotal property value$75,000,000
confidenceConfidence level (0-1)0.87 (87%)
currencyAppraisal currencyARS, USD
zoneNameZone namePalermo, Recoleta
averagePricePerM2Average 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:

StepEndpointMethodWhat it returnsWhen to call it
1/valuation-requestPOSTrequestCode + initial statusOnce at the beginning
2/valuation-request/\{code\}GETOnly the current statusMultiple times in loop until COMPLETED
3/valuation-request/\{code\}/resultGETComplete appraisal with all valuesOnce 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:

  1. ✅ Step 1: POST /valuation-request - Create request and get requestCode
  2. ✅ Step 2: GET /valuation-request/\{requestCode\} - Monitor status until COMPLETED
  3. ✅ Step 3: GET /valuation-request/\{requestCode\}/result - Get complete result
  4. ✅ Interpret estimated values, market analysis, and confidence level

Now that you master the basic flow, explore more functionalities:

💬 Need help?