Flujo Básico de Avalúo

Este tutorial te lleva desde cero hasta obtener tu primera tasación inmobiliaria. Es el

"Hola Mundo" de Place Analyzer API.

Tiempo estimado: 5-10 minutos

Este tutorial está diseñado para llevarte desde cero hasta tu primera tasación exitosa en menos de 10 minutos.

Los 3 Endpoints Principales

Este flujo utiliza los endpoints del

#	Método	Endpoint	Descripción
1	`POST`	`/valuation-request`	Crear solicitud → obtienes `requestCode`
2	`GET`	`/valuation-request/[code]`	Consultar estado → verificas si está `READY`
3	`GET`	`/valuation-request/[code]/result`	Obtener resultado → recibes `priceLand` y `priceBuild`

Ver API Reference completo

Cada paso incluye un enlace directo al API Reference donde encontrarás todos los parámetros, ejemplos de respuesta, códigos de error y más detalles técnicos.

El Ciclo de Vida de un Avalúo

Los avalúos en Place Analyzer son asíncronos. Esto significa que:

Envías una solicitud de tasación (toma segundos) → Recibes un requestCode
Consultas el estado periódicamente (cada 5-10 segundos) → Verificas si está READY
Obtienes el resultado completo cuando está listo → Recibes priceLand y priceBuild

Paso 1: Crear la Solicitud de Avalúo

API Reference

📚 Documentación completa del endpoint: POST /valuation-request

Consulta el API Reference para ver todos los parámetros disponibles, ejemplos de respuesta y códigos de error.

Estructura del Request

El cuerpo de la solicitud tiene la siguiente estructura:

{
  "latitude": number,        // Requerido: Latitud GPS
  "longitude": number,       // Requerido: Longitud GPS
  "property": {              // Requerido: Datos de la propiedad
    "propertyType": string,      // Requerido: Casa, Departamento, Terreno, etc.
    "propertyAge": string,       // Requerido según tipo de propiedad: Nuevo, Semi nuevo, Antiguo, etc.
    "propertyCondition": string, // Requerido según tipo de propiedad: Excelente, Bueno, Regular, Malo
    "m2Land": number,            // Requerido según tipo de propiedad: Metros² de terreno
    "m2Built": number,           // Requerido según tipo de propiedad: Metros² construidos
    "m2Covered": number,         // Requerido para Departamento: Metros² cubiertos
    "m2SemiCovered": number,     // Requerido para Departamento: Metros² semicubiertos
    "numberOfBedrooms": integer, // Opcional: Número de dormitorios
    "numberOfBathrooms": integer,// Opcional: Número de baños
    "garageSpaces": integer,     // Opcional: Espacios de garage
    "hasServiceArea": boolean,   // Opcional: Tiene área de servicio
    "hasBalcony": boolean,       // Opcional: Tiene balcón
    "hasGym": boolean,           // Opcional: Tiene gimnasio
    "hasPool": boolean,          // Opcional: Tiene piscina
    "isLuxury": boolean          // Opcional: Es propiedad de lujo
  }
}

Campos Requeridos

Campo	Tipo	Descripción	Ejemplo	Obs
`latitude`	`number`	Latitud GPS de la propiedad	`-34.603722`
`longitude`	`number`	Longitud GPS de la propiedad	`-58.381592`
`property.propertyType`	`string`	Tipo de propiedad	`Casa`, `Departamento`, `Terreno`	Siempre requerido
`property.m2Land`	`number`	Metros² de terreno	`360`	Requerido para Terreno y demás tipos (no Departamento)
`property.m2Built`	`number`	Metros² construidos	`120`	Requerido para demás tipos (no Terreno ni Departamento)
`property.m2Covered`	`number`	Metros² cubiertos	`80`	Requerido para Departamento
`property.m2SemiCovered`	`number`	Metros² semicubiertos	`10`	Requerido para Departamento
`property.propertyAge`	`string`	Antigüedad del inmueble	`Nuevo`, `Semi nuevo`, `Antiguo`	Requerido para Departamento y demás tipos
`property.propertyCondition`	`string`	Estado de conservación	`Excelente`, `Bueno`, `Regular`, `Malo`	Requerido para demás tipos (no Terreno ni Departamento)

Matriz completa

La obligatoriedad exacta por propertyType está detallada en Avalúos individuales.

Encontrar las coordenadas

Puedes obtener las coordenadas de varias formas:

📍 Opción 1: Google Maps

Busca la dirección en Google Maps
Haz clic derecho en el punto
Selecciona "Qué hay aquí"
Copia las coordenadas del formato "lat, lng"

📍 Opción 2: Herramientas online

📍 Opción 3: API de geocodificación

// Ejemplo con Google Geocoding API
const geocodeResponse = await fetch(
  `https://maps.googleapis.com/maps/api/geocode/json?address=${encodeURIComponent(address)}`
);

Hacer la petición

Envía una petición POST al endpoint /valuation-request con los datos de la propiedad:

Ejemplo con curl:

curl -X POST "https://api.placeanalyzer.com/valuation/valuation-request" \
-H "X-API-KEY: tu_api_key_aqui" \
-H "Content-Type: application/json" \
-d '{
  "latitude": -25.2821,
  "longitude": -57.6353,
  "property": {
    "propertyType": "Casa",
    "propertyAge": "Semi nuevo",
    "propertyCondition": "Bueno",
    "m2Land": 300,
    "m2Built": 200,
    "numberOfBedrooms": 3,
    "numberOfBathrooms": 2,
    "garageSpaces": 1
  }
}'

Respuesta exitosa (200):

{
  "id": 12345,
  "requestCode": "abc-123-xyz-456",
  "requestDate": "2025-01-15T10:30:00Z",
  "status": "CREATED"
}

¡Guarda el requestCode!

El requestCode es el identificador único de tu avalúo. Lo necesitarás en los siguientes pasos. No lo pierdas.

Paso 2: Consultar el Estado

API Reference

📚 Documentación completa del endpoint: GET /valuation-request/{requestCode}

Este endpoint devuelve el estado actual y todos los detalles de la solicitud.

Los avalúos toman tiempo para procesar (2-5 minutos). Debes consultar el estado periódicamente hasta que cambie a READY.

Recomendación de Polling

Consulta el estado cada 5-10 segundos. No consultes más frecuentemente para evitar límites de rate limiting.

Ejemplo con curl:

curl -X GET "https://api.placeanalyzer.com/valuation/valuation-request/abc-123-xyz-456" \
-H "X-API-KEY: tu_api_key_aqui"

Respuesta completa:

{
  "requestCode": "abc-123-xyz-456",
  "requestDate": "2025-01-15T10:30:00Z",
  "status": "READY",
  "currency": "USD",
  "mlModelCode": "V1",
  "latitude": -25.2821,
  "longitude": -57.6353,
  "region": "PY",
  "property": {
    "propertyId": 67890,
    "propertyType": "Casa",
    "m2Land": 300,
    "m2Built": 200,
    "numberOfBedrooms": 3,
    "numberOfBathrooms": 2,
    "garageSpaces": 1,
    "propertyAge": "Semi nuevo",
    "propertyCondition": "Bueno",
    "hasServiceArea": false,
    "hasBalcony": false,
    "hasGym": false,
    "hasPool": false,
    "isLuxury": false
  },
  "reportSettings": {
    "nearbySales": true,
    "nearbyRentals": true,
    "graphicActivity": true
  },
  "user": {
    "name": "Juan",
    "lastname": "Pérez",
    "username": "juan.perez@empresa.com",
    "company": "Mi Empresa S.A."
  }
}

¡Listo para el Paso 3!

Cuando status sea READY, puedes proceder al Paso 3 para obtener el resultado de la tasación.

Estados posibles

Estado	Descripción	¿Resultado disponible?
`CREATED`	En cola para procesar	❌ No
`READY`	Procesamiento terminado	✅ Sí
`ERROR_VALUATION`	Error durante el procesamiento	❌ No (ver `failedMessage`)

Estrategia de Polling

JavaScript:

// requestCode obtenido del Paso 1: "abc-123-xyz-456"
const requestCode = "abc-123-xyz-456";
const apiKey = "tu_api_key_aqui";

async function waitForCompletion(requestCode, apiKey) {
  while (true) {
    const response = await fetch(
      `{API_BASE_URL}/valuation-request/${requestCode}`,
      {
        headers: { 'X-API-KEY': apiKey }
      }
    );

    const data = await response.json();

    if (data.status === 'READY') {
      return data;
    } else if (data.status === 'ERROR_VALUATION') {
      throw new Error(`El avalúo falló: ${data.failedMessage}`);
    }

    // Esperar 5 segundos antes de consultar de nuevo
    await new Promise(resolve => setTimeout(resolve, 5000));
  }
}

// Usar la función
waitForCompletion(requestCode, apiKey).then(data => {
  console.log('Avalúo completado:', data);
});

Python:

import time
import requests

# requestCode obtenido del Paso 1
request_code = "abc-123-xyz-456"
api_key = "tu_api_key_aqui"

def wait_for_completion(request_code, api_key):
    while True:
        response = requests.get(
            f'{API_BASE_URL}/valuation-request/{request_code}',
            headers={'X-API-KEY': api_key}
        )

        data = response.json()

        if data['status'] == 'READY':
            return data
        elif data['status'] == 'ERROR_VALUATION':
            raise Exception(f"El avalúo falló: {data.get('failedMessage', 'Error desconocido')}")

        # Esperar 5 segundos
        time.sleep(5)

# Usar la función
result = wait_for_completion(request_code, api_key)
print('Avalúo completado:', result)

Paso 3: Obtener el Resultado Completo

API Reference

📚 Documentación completa del endpoint: GET /valuation-request/{requestCode}/result

⚠️ Importante: Este es un endpoint diferente al del Paso 2. Aquí obtienes los valores de tasación calculados.

Una vez que el estado es READY, solicita el resultado de la tasación:

Ejemplo con curl:

curl -X GET "{API_BASE_URL}/valuation-request/abc-123-xyz-456/result" \
-H "X-API-KEY: tu_api_key_aqui"

Respuesta exitosa (200):

{
  "requestCode": "abc-123-xyz-456",
  "requestDate": "2025-01-15T10:30:00Z",
  "status": "READY",
  "currency": "USD",
  "mlModelCode": "V1",
  "priceLand": 150000.00,
  "priceBuild": 200000.00
}

¿Qué significa cada campo?

Campo	Descripción	Ejemplo
`requestCode`	Código único de la solicitud	`abc-123-xyz-456`
`requestDate`	Fecha y hora de la solicitud	`2025-01-15T10:30:00Z`
`status`	Estado final del avalúo	`READY`
`currency`	Moneda de los valores	`USD`
`mlModelCode`	Código del modelo ML utilizado	`V1`
`priceLand`	Valor estimado del terreno	`150000.00`
`priceBuild`	Valor estimado de la construcción	`200000.00`

Calcular valor total

El valor total de la propiedad se obtiene sumando priceLand + priceBuild:

const totalValue = result.priceLand + result.priceBuild;
// 150000 + 200000 = 350000 USD

📋 Resumen: Diferencia entre los 3 endpoints

Paso	Endpoint	Método	Qué devuelve	Cuándo llamarlo
1	`/valuation-request`	`POST`	`id`, `requestCode`, `requestDate`, `status`	Una vez al inicio
2	`/valuation-request/{code}`	`GET`	Estado completo + detalles	Múltiples veces hasta `READY`
3	`/valuation-request/{code}/result`	`GET`	`priceLand`, `priceBuild`	Una vez cuando `status = READY`

💡 Tip: El Paso 2 es para monitoreo, el Paso 3 es para obtener los valores de tasación.

Ejemplo Completo en JavaScript

Aquí tienes un ejemplo completo que integra los tres pasos:

const API_BASE = '{API_BASE_URL}';
const API_KEY = 'tu_api_key_aqui';

async function createValuation() {
  // Función auxiliar para esperar a que el avalúo se complete
  async function waitForCompletion(requestCode) {
    while (true) {
      const response = await fetch(
        `${API_BASE}/valuation-request/${requestCode}`,
        {
          headers: { 'X-API-KEY': API_KEY }
        }
      );

      const data = await response.json();

      if (data.status === 'READY') {
        return data;
      } else if (data.status === 'ERROR_VALUATION') {
        throw new Error(`El avalúo falló: ${data.failedMessage || 'Error desconocido'}`);
      }

      console.log(`⏳ Estado: ${data.status} - Esperando 5 segundos...`);
      await new Promise(resolve => setTimeout(resolve, 5000));
    }
  }

  try {
    // ============================================================
    // PASO 1: Crear solicitud (POST /valuation-request)
    // ============================================================
    console.log('🚀 Paso 1: Creando solicitud de avalúo...');
    
    const createResponse = await fetch(`${API_BASE}/valuation-request`, {
      method: 'POST',
      headers: {
        'X-API-KEY': API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        "latitude": -25.2821,
        "longitude": -57.6353,
        property: {
          propertyType: 'Casa',
          propertyAge: 'Semi nuevo',
          propertyCondition: 'Bueno',
          m2Land: 300,
          m2Built: 200,
          numberOfBedrooms: 3,
          numberOfBathrooms: 2,
          garageSpaces: 1
        }
      })
    });

    const createResult = await createResponse.json();
    const requestCode = createResult.requestCode;

    console.log(`✅ Solicitud creada: ${requestCode}`);
    console.log(`   ID: ${createResult.id}`);
    console.log(`   Estado: ${createResult.status}`);

    // ============================================================
    // PASO 2: Consultar estado (GET /valuation-request/[code])
    // ============================================================
    console.log('⏳ Paso 2: Esperando a que el estado sea READY...');
    
    const valuationDetails = await waitForCompletion(requestCode);
    
    console.log('✅ Estado: READY');
    console.log(`   Región: ${valuationDetails.region}`);
    console.log(`   Modelo ML: ${valuationDetails.mlModelCode}`);

    // ============================================================
    // PASO 3: Obtener resultado (GET /valuation-request/[code]/result)
    // ============================================================
    console.log('📊 Paso 3: Obteniendo resultado completo...');
    
    const resultResponse = await fetch(
      `${API_BASE}/valuation-request/${requestCode}/result`,
      {
        headers: { 'X-API-KEY': API_KEY }
      }
    );

    const result = await resultResponse.json();
    const totalValue = result.priceLand + result.priceBuild;

    console.log('🎉 ¡Avalúo completado!');
    console.log(`💰 Valor del terreno: $${result.priceLand.toLocaleString()} ${result.currency}`);
    console.log(`🏠 Valor construcción: $${result.priceBuild.toLocaleString()} ${result.currency}`);
    console.log(`📊 Valor total: $${totalValue.toLocaleString()} ${result.currency}`);

    return result;

  } catch (error) {
    console.error('❌ Error:', error.message);
  }
}

// Ejecutar el ejemplo
createValuation();

Ejemplo Completo en Python

import time
import requests

API_BASE = '{API_BASE_URL}'
API_KEY = 'tu_api_key_aqui'

def create_valuation():
    try:
        # ============================================================
        # PASO 1: Crear solicitud (POST /valuation-request)
        # ============================================================
        print('🚀 Paso 1: Creando solicitud de avalúo...')
        
        create_response = requests.post(
            f'{API_BASE}/valuation-request',
            headers={
                'X-API-KEY': API_KEY,
                'Content-Type': 'application/json'
            },
            json={
                "latitude": -25.2821,
                "longitude": -57.6353,
                'property': {
                    'propertyType': 'Casa',
                    'propertyAge': 'Semi nuevo',
                    'propertyCondition': 'Bueno',
                    'm2Land': 300,
                    'm2Built': 200,
                    'numberOfBedrooms': 3,
                    'numberOfBathrooms': 2,
                    'garageSpaces': 1
                }
            }
        )
        
        create_result = create_response.json()
        request_code = create_result['requestCode']
        
        print(f"✅ Solicitud creada: {request_code}")
        print(f"   ID: {create_result['id']}")
        print(f"   Estado: {create_result['status']}")

        # ============================================================
        # PASO 2: Consultar estado (GET /valuation-request/[code])
        # ============================================================
        print('⏳ Paso 2: Esperando a que el estado sea READY...')
        
        valuation_details = wait_for_completion(request_code)
        
        print('✅ Estado: READY')
        print(f"   Región: {valuation_details.get('region', 'N/A')}")
        print(f"   Modelo ML: {valuation_details.get('mlModelCode', 'N/A')}")

        # ============================================================
        # PASO 3: Obtener resultado (GET /valuation-request/[code]/result)
        # ============================================================
        print('📊 Paso 3: Obteniendo resultado completo...')
        
        result_response = requests.get(
            f'{API_BASE}/valuation-request/{request_code}/result',
            headers={'X-API-KEY': API_KEY}
        )
        
        result = result_response.json()
        total_value = result['priceLand'] + result['priceBuild']
        
        print('🎉 ¡Avalúo completado!')
        print(f"💰 Valor del terreno: ${result['priceLand']:,.2f} {result['currency']}")
        print(f"🏠 Valor construcción: ${result['priceBuild']:,.2f} {result['currency']}")
        print(f"📊 Valor total: ${total_value:,.2f} {result['currency']}")
        
        return result
        
    except Exception as e:
        print(f'❌ Error: {str(e)}')
        raise

def wait_for_completion(request_code):
    while True:
        response = requests.get(
            f'{API_BASE}/valuation-request/{request_code}',
            headers={'X-API-KEY': API_KEY}
        )
        
        data = response.json()
        
        if data['status'] == 'READY':
            return data
        elif data['status'] == 'ERROR_VALUATION':
            raise Exception(f"El avalúo falló: {data.get('failedMessage', 'Error desconocido')}")
        
        print(f"⏳ Estado: {data['status']} - Esperando 5 segundos...")
        time.sleep(5)

# Ejecutar el ejemplo
if __name__ == '__main__':
    create_valuation()

Conclusión

¡Felicidades! 🎉 Has completado tu primer avalúo con Place Analyzer API.

Resumen de lo que aprendiste:

✅ Paso 1: POST /valuation-request - Crear solicitud con latitude, longitude y property
✅ Paso 2: GET /valuation-request/[code] - Monitorear estado hasta READY
✅ Paso 3: GET /valuation-request/[code]/result - Obtener priceLand y priceBuild

🚀 Próximos pasos recomendados:

Ahora que dominas el flujo básico, explora más funcionalidades:

📚 API Reference completo - Explora todos los parámetros y opciones disponibles
📊 Generar reportes - Añade datos demográficos y análisis comercial
📊 Datos estadísticos - Obtén datos demográficos y comerciales
🔍 Consultar propiedades cercanas - Obtén comparables para análisis

💬 ¿Necesitas ayuda?

❌ Errores: Consulta la guía de manejo de errores
🔑 Autenticación: Revisa la guía de autenticación
📖 Glosario: Entiende todos los términos en el glosario y estados