API para puntajes de calidad de ubicación

Necesitas clasificar vecindarios rápidamente: autocompletar direcciones, obtener listados activos dentro de un cuadro delimitador y obtener los detalles completos de una propiedad, para que puedas calcular puntajes de calidad de ubicación para tu aplicación. Al final de esta guía, podrás llamar a tres puntos finales reales en Zyla API Hub para obtener los datos en bruto que puntuarás: sugerencias de ubicación basadas en palabras clave, inventario residencial dentro de un límite geográfico y detalles profundos de propiedades.

Lo que esta API te ofrece para puntuar ubicaciones

La API de Bienes Raíces de Canadá agrega datos de listados residenciales que puedes usar para derivar tus propias métricas de "calidad de ubicación". Con ella, puedes:

• Resolver la intención del usuario rápidamente utilizando sugerencias de ubicación basadas en palabras clave.
• Obtener listados dentro de un cuadro delimitador de latitud/longitud para calcular densidad, variedad y distribución de precios.
• Obtener detalles completos de la propiedad (descripciones, IDs, etc.) para enriquecer tu lógica de puntuación o construir vistas detalladas.

Estos bloques de construcción se utilizan comúnmente en guías para compradores, herramientas de descubrimiento de vecindarios, enrutamiento de leads y paneles de análisis de inversiones. Si necesitas un feed confiable que puedas implementar esta semana, esta es una opción sencilla en Zyla API Hub.

Comenzando en Zyla API Hub

Abre la página del mercado de la API y comienza una prueba para obtener una clave de API. La autenticación es un encabezado simple en cada solicitud: Authorization: Bearer YOUR_API_KEY. Zyla utiliza un modelo de suscripción y cuota: no es por llamada. Para el primer uso, espera una prueba de 7 días o 50 solicitudes para probar en tu entorno. Consulta la página de la API para las opciones de acceso y precios actuales.

Comienza aquí: Comienza prueba de 7 días en la API de Bienes Raíces de Canadá

Puntos finales que usarás para construir un puntaje de calidad de ubicación

1) Autocompletar (GET)

Utiliza esto para convertir la entrada del usuario en sugerencias precisas y accionables: calles, ciudades y referencias que puedes mapear a búsquedas.

• URL: https://zylalabs.com/api/5902/canada-real-estate-api/7768/auto-complete
• Propósito: Devolver sugerencias de ubicación basadas en palabras clave.
• Parámetros requeridos:
  • Query (string): Ejemplo: Quebec
• Parámetros opcionales:
  • CultureId (string): Ejemplo: 1
  • IncludeLocations (string): Ejemplo: true

Copia y pega cURL:

curl -s -X GET "https://zylalabs.com/api/5902/canada-real-estate-api/7768/auto-complete?Query=Quebec&CultureId=1&IncludeLocations=true" \
-H "Authorization: Bearer YOUR_API_KEY"

Ejemplo de respuesta oficial:

{"ErrorCode":{"Id":200,"Description":"Success - OK","ProductName":"Realtor API 7 | 20241202.1 | 1018e702fe06dda8279318e12b199910ca21c3ff | Monday, December 2, 2024 12:21:41 PM","Version":"1.0.9102.31292"},"Results":[{"Type":1,"ListingId":"27656697","ReferenceNumber":"X10440405","Address_EN":"191 QUEBEC STREET","Address_FR":"191 QUEBEC STREET","City":"Bracebridge (Macaulay)","PostalCode":"p1l1e3","Province":"ON","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27656697\/191-quebec-street-bracebridge-macaulay-macaulay","RelativeURLFr":"\/immobilier\/27656697\/191-quebec-street-bracebridge-macaulay","isReferenceMatch":false,"isPostalCodeMatch":false},{"Type":1,"ListingId":"27661192","ReferenceNumber":"X10428998","Address_EN":"549 QUEBEC STREET","Address_FR":"549 QUEBEC STREET","City":"London","PostalCode":"n5w3y9","Province":"ON","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27661192\/549-quebec-street-london-east-g","RelativeURLFr":"\/immobilier\/27661192\/549-quebec-street-london","isReferenceMatch":false,"isPostalCodeMatch":false},{"Type":1,"ListingId":"27720876","ReferenceNumber":"R2949266","Address_EN":"212 4928 QUEBEC STREET","Address_FR":"212 4928 QUEBEC STREET","City":"Vancouver","PostalCode":"v5w2n2","Province":"BC","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27720876\/212-4928-quebec-street-vancouver","RelativeURLFr":"\/immobilier\/27720876\/212-4928-quebec-street-vancouver","isReferenceMatch":false,"isPostalCodeMatch":false},{"Type":1,"ListingId":"27741486","ReferenceNumber":"X11894528","Address_EN":"558 QUEBEC STREET","Address_FR":"558 QUEBEC STREET","City":"Hamilton (Parkview)","PostalCode":"l8h6v4","Province":"ON","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27741486\/558-quebec-street-hamilton-parkview-parkview","RelativeURLFr":"\/immobilier\/27741486\/558-quebec-street-hamilton-parkview","isReferenceMatch":false,"isPostalCodeMatch":false},{"Type":1,"ListingId":"27754883","ReferenceNumber":"S11901084","Address_EN":"267 QUEBEC STREET","Address_FR":"267 QUEBEC STREET","City":"Clearview (Stayner)","PostalCode":"l0m1s0","Province":"ON","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27754883\/267-quebec-street-clearview-stayner-stayner","RelativeURLFr":"\/immobilier\/27754883\/267-quebec-street-clearview-stayner","isReferenceMatch":false,"isPostalCodeMatch":false}],"ResultsMapBox":[{…

Qué leer de esto:

• ErrorCode: Usa Id y Description para interrumpir flujos no 200.
• Results: Cada sugerencia te da ListingId, ReferenceNumber, Address_EN/FR, City, PostalCode, Province y URLs relativas. Estos pueden mostrarse directamente en tu UI y usarse para iniciar una búsqueda de seguimiento para listados dentro de esa área.

2) Listar Residencial (GET)

Obtén una página de propiedades residenciales dentro de un cuadro delimitador de lat/long. Perfecto para métricas de densidad, agregación de precios y mapeo de clusters.

• URL: https://zylalabs.com/api/5902/canada-real-estate-api/7769/list-residential
• Propósito: Devolver propiedades residenciales disponibles para venta o alquiler basadas en límites geográficos.
• Parámetros requeridos:
  • LatitudeMax (número): 81.14747595814636
  • LatitudeMin (número): -22.26872153207164
  • LongitudeMax (número): -10.267941690981388
  • LongitudeMin (número): -136.83037765324116

Ejemplo de cURL (copia tal cual y cambia la clave del encabezado):

Notas que ahorran tiempo:

• Las respuestas incluyen un objeto Paging con RecordsPerPage, CurrentPage y TotalRecords. Usa eso para paginar y calcular una métrica de densidad de listados por área.
• ErrorCode.Status puede incluir pistas de caché como “Pins-Via-Cache:false;Sidebar-Items-Via-Cache:0;”. No confíes en esto para la lógica, pero pueden explicar el tiempo de respuesta en los registros.
• RecordsShowing y Pins pueden ayudarte a depurar cuántos pines de mapa o elementos el servidor pretende mostrar por página.

3) Detalle de Propiedad (GET)

Obtén la información completa de una sola propiedad utilizando una combinación de ReferenceNumber y PropertyID. Usa esto para enriquecer tu UI de puntuación con descripciones completas y para confirmar detalles de candidatos seleccionados.

• URL: https://zylalabs.com/api/5902/canada-real-estate-api/7770/property-detail
• Propósito: Obtener información detallada del listado, como imágenes, descripción y características de la propiedad.
• Parámetros requeridos:
  • ReferenceNumber (string): 67b74ee58bc56b22659786b3
  • PropertyID (string): 27935110

Ejemplo de cURL:

Orientación práctica:

• Revisa el bloque ErrorCode antes de leer los campos.
• Usa comentarios públicos e identificadores clave para anclar una página de perfil de propiedad en tu aplicación.

Ejemplo en Python: resolver una consulta y calcular un puntaje de densidad de listados simple

Este ejemplo llama a Autocompletar para confirmar un área objetivo a partir de la entrada de un usuario, luego llama a Listar Residencial para un amplio cuadro delimitador. Adaptarás el cuadro delimitador a las sugerencias seleccionadas por el usuario (por ejemplo, restringiéndolo a una ciudad específica o geometría de vecindario que derives de tus propios datos).

import requests

API_KEY = "YOUR_API_KEY"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# 1) Resolver la intención del usuario con Autocompletar
auto_complete_url = "https://zylalabs.com/api/5902/canada-real-estate-api/7768/auto-complete"
params = {
"Query": "Quebec",
"CultureId": "1",
"IncludeLocations": "true"
}
ac_resp = requests.get(auto_complete_url, headers=HEADERS, params=params, timeout=30)
ac_data = ac_resp.json()

if ac_data.get("ErrorCode", {}).get("Id") != 200:
raise SystemExit(f"Autocompletar falló: {ac_data.get('ErrorCode')}")

suggestions = ac_data.get("Results", [])
# En una aplicación real, selecciona una sugerencia basada en la acción del usuario.
first = suggestions[0] if suggestions else None
if first:
print("Sugerencia principal:", first.get("Address_EN"), first.get("City"), first.get("Province"))

# 2) Obtener listados dentro de un cuadro delimitador (valores de demostración de la documentación)
list_url = "https://zylalabs.com/api/5902/canada-real-estate-api/7769/list-residential"
list_params = {
"LatitudeMax": 81.14747595814636,
"LatitudeMin": -22.26872153207164,
"LongitudeMax": -10.267941690981388,
"LongitudeMin": -136.83037765324116
}
list_resp = requests.get(list_url, headers=HEADERS, params=list_params, timeout=30)
list_data = list_resp.json()

if list_data.get("ErrorCode", {}).get("Id") != 200:
raise SystemExit(f"Listar Residencial falló: {list_data.get('ErrorCode')}")

paging = list_data.get("Paging", {})
total_records = paging.get("TotalRecords")
records_per_page = paging.get("RecordsPerPage")
current_page = paging.get("CurrentPage")
print("Página de listados:", current_page, "tamaño de página:", records_per_page, "total:", total_records)

# 3) Un proxy mínimo de "calidad de ubicación": puntaje de densidad (registros por N km cuadrados) basado en tus límites.
# Debes calcular el área para tus límites elegidos; aquí solo mostramos la idea sin matemáticas geodésicas.
results = list_data.get("Results", [])
count = len(results) if isinstance(results, list) else 0
print("Proxy de densidad (conteo en bbox):", count)

Consejos:

• Mantén tus tiempos de espera de solicitudes razonables (20–30s) para la variación de red.
• Usa el objeto ErrorCode para bifurcar en flujos de éxito vs. reintentos o flujos de respaldo.
• Persiste los totales de Paging para análisis y para evitar volver a contar en cada cambio de página del usuario.

Cómo convertir estas respuestas en un puntaje de "calidad de ubicación"

Debido a que los criterios de puntuación varían según el producto, la API devuelve datos de listados y sugerencias en bruto. Puedes calcular un puntaje compuesto así:

• Densidad de inventario: número de listados por unidad de área en tu cuadro delimitador (de Listar Residencial + tu propio cálculo de área).
• Diversidad: cuenta por atributos de propiedad presentes en Results (por ejemplo, StoriesTotal si está disponible en objetos Building) para estimar variedad.
• Proxies de actualidad/disponibilidad: usa los totales de paginación para saber si un área está "activa".
• Señales de texto: extrae PublicRemarks (cuando esté disponible) de Detalle de Propiedad para resaltar palabras clave (renovado, cerca del transporte) para tu modelo.

Comienza con densidad y diversidad. Proporcionan una línea base accionable y son rápidas de calcular.

Agentes de IA: llama a la API a través de MCP

Si prefieres orquestar llamadas desde un agente de IA o asistente de IDE, puedes usar el punto final MCP de Zyla. Cualquier cliente compatible con MCP (por ejemplo, Claude Code, Cursor, Windsurf) puede acceder a las APIs de Zyla con tu misma clave a través de la puerta de enlace MCP. Consulta: MCP.

Esquema de flujo de trabajo:

• Proporciona el punto final MCP y tu clave de API a tu cliente MCP: https://mcp.zylalabs.com/mcp?apikey=YOUR_API_KEY
• Instruye a tu agente para que llame primero al punto final de Autocompletar para la entrada del usuario, luego a Listar Residencial para el área seleccionada.
• Opcionalmente, obtén Detalle de Propiedad para enriquecer los resúmenes antes de responder en el chat.

Detalles operativos que ayudan en producción

• Autenticación: Envía Authorization: Bearer YOUR_API_KEY en cada solicitud.
• Paginación: Lee el objeto Paging en Listar Residencial para paginar y almacenar recuentos en caché.
• Caché: La cadena ErrorCode.Status puede incluir pistas (por ejemplo, Pins-Via-Cache). Trátalo como informativo.
• Localización: Autocompletar admite CultureId y Address_EN/FR. Respeta el idioma del usuario en tu UI.
• Cuotas: Zyla utiliza suscripción + cuota. La primera API generalmente ofrece una prueba de 7 días o 50 solicitudes para evaluar. Para límites actuales, consulta la página del mercado.

Flujo de extremo a extremo para implementar esta semana

1. Adquiere una clave en la página del mercado y guárdala en tu administrador de secretos.
2. Implementa Autocompletar en tu cuadro de búsqueda para resolver rápidamente el área pretendida por el usuario.
3. Traduce la sugerencia elegida en un cuadro delimitador. Si tu aplicación almacena polígonos, mapea las sugerencias a tu geometría. De lo contrario, comienza con un cuadro a nivel de ciudad que mantengas.
4. Llama a Listar Residencial y calcula:
   • Conteo de listados (proxy de densidad).
   • Distribución de diversidad de atributos del array Results.
5. Al seleccionar, llama a Detalle de Propiedad para una vista detallada y extraer características de texto para tu puntaje.
6. Expón el puntaje compuesto de "calidad de ubicación" con un enlace para ver los datos subyacentes (número de listados, propiedades de muestra).

Lista de verificación de solución de problemas

• 401/403: Verifica Authorization: Bearer YOUR_API_KEY y el estado de la suscripción.
• Sugerencias vacías: Intenta una cadena de consulta más amplia en Autocompletar o confirma que IncludeLocations esté configurado en true cuando sea necesario.
• Paginación inesperada: Registra todo el objeto Paging para confirmar RecordsPerPage y TotalPages.
• Consultas lentas: Pre-cacha cuadros delimitadores frecuentes y reutiliza puntajes calculados.

FAQ

¿Cómo me autentico?
Envía el encabezado Authorization: Bearer YOUR_API_KEY con cada solicitud.

¿Puedo filtrar por precio, camas u otros atributos?
El punto final Listar Residencial se describe para límites geográficos en esta guía. Si necesitas filtros adicionales, consulta la página de la API para los parámetros y ejemplos disponibles.

¿Cómo pagino los resultados?
Usa el objeto Paging en la respuesta de Listar Residencial. Campos como RecordsPerPage, CurrentPage y TotalPages indican cuántas páginas solicitar. Maneja esto en tu capa de API y transmite a la UI.

¿Qué debo usar para calcular un puntaje de calidad de ubicación?
Comienza con la densidad de listados dentro de tu cuadro delimitador, luego agrega diversidad por atributos de propiedad y señales de palabras clave de texto de Detalle de Propiedad. Mantén el modelo transparente para que los usuarios puedan ver por qué un área obtuvo una puntuación alta o baja.

¿Hay un plan gratuito?
Zyla utiliza suscripción + cuota. Para evaluaciones de primera vez, espera una prueba de 7 días o 50 solicitudes. Consulta la página de la API para las opciones de acceso y precios actuales.

Implementa tu función de puntuación de ubicación

Obtén tu clave, conecta los tres puntos finales anteriores y comienza a calcular un puntaje de ubicación opinado que se ajuste a tu producto. Comienza aquí: Comienza prueba de 7 días en la API de Bienes Raíces de Canadá. Siempre puedes expandir más tarde con APIs adicionales de Zyla: hay más de 10,000 APIs públicas disponibles en Zyla API Hub.

Respuesta oficial de la API

{"ErrorCode":{"Id":200,"Description":"Success - OK","ProductName":"Realtor API 7 | 20241202.1 | 1018e702fe06dda8279318e12b199910ca21c3ff | Monday, December 2, 2024 12:21:41 PM","Version":"1.0.9102.31292"},"Results":[{"Type":1,"ListingId":"27656697","ReferenceNumber":"X10440405","Address_EN":"191 QUEBEC STREET","Address_FR":"191 QUEBEC STREET","City":"Bracebridge (Macaulay)","PostalCode":"p1l1e3","Province":"ON","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27656697\/191-quebec-street-bracebridge-macaulay-macaulay","RelativeURLFr":"\/immobilier\/27656697\/191-quebec-street-bracebridge-macaulay","isReferenceMatch":false,"isPostalCodeMatch":false},{"Type":1,"ListingId":"27661192","ReferenceNumber":"X10428998","Address_EN":"549 QUEBEC STREET","Address_FR":"549 QUEBEC STREET","City":"London","PostalCode":"n5w3y9","Province":"ON","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27661192\/549-quebec-street-london-east-g","RelativeURLFr":"\/immobilier\/27661192\/549-quebec-street-london","isReferenceMatch":false,"isPostalCodeMatch":false},{"Type":1,"ListingId":"27720876","ReferenceNumber":"R2949266","Address_EN":"212 4928 QUEBEC STREET","Address_FR":"212 4928 QUEBEC STREET","City":"Vancouver","PostalCode":"v5w2n2","Province":"BC","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27720876\/212-4928-quebec-street-vancouver","RelativeURLFr":"\/immobilier\/27720876\/212-4928-quebec-street-vancouver","isReferenceMatch":false,"isPostalCodeMatch":false},{"Type":1,"ListingId":"27741486","ReferenceNumber":"X11894528","Address_EN":"558 QUEBEC STREET","Address_FR":"558 QUEBEC STREET","City":"Hamilton (Parkview)","PostalCode":"l8h6v4","Province":"ON","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27741486\/558-quebec-street-hamilton-parkview-parkview","RelativeURLFr":"\/immobilier\/27741486\/558-quebec-street-hamilton-parkview","isReferenceMatch":false,"isPostalCodeMatch":false},{"Type":1,"ListingId":"27754883","ReferenceNumber":"S11901084","Address_EN":"267 QUEBEC STREET","Address_FR":"267 QUEBEC STREET","City":"Clearview (Stayner)","PostalCode":"l0m1s0","Province":"ON","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27754883\/267-quebec-street-clearview-stayner-stayner","RelativeURLFr":"\/immobilier\/27754883\/267-quebec-street-clearview-stayner","isReferenceMatch":false,"isPostalCodeMatch":false}],"ResultsMapBox":[{…

Respuesta oficial de la API

{"ErrorCode":{"Id":200,"Description":"Success - OK","ProductName":"Realtor API 7 | 20241202.1 | 1018e702fe06dda8279318e12b199910ca21c3ff | Monday, December 2, 2024 12:21:41 PM","Version":"1.0.9102.31292"},"Results":[{"Type":1,"ListingId":"27656697","ReferenceNumber":"X10440405","Address_EN":"191 QUEBEC STREET","Address_FR":"191 QUEBEC STREET","City":"Bracebridge (Macaulay)","PostalCode":"p1l1e3","Province":"ON","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27656697\/191-quebec-street-bracebridge-macaulay-macaulay","RelativeURLFr":"\/immobilier\/27656697\/191-quebec-street-bracebridge-macaulay","isReferenceMatch":false,"isPostalCodeMatch":false},{"Type":1,"ListingId":"27661192","ReferenceNumber":"X10428998","Address_EN":"549 QUEBEC STREET","Address_FR":"549 QUEBEC STREET","City":"London","PostalCode":"n5w3y9","Province":"ON","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27661192\/549-quebec-street-london-east-g","RelativeURLFr":"\/immobilier\/27661192\/549-quebec-street-london","isReferenceMatch":false,"isPostalCodeMatch":false},{"Type":1,"ListingId":"27720876","ReferenceNumber":"R2949266","Address_EN":"212 4928 QUEBEC STREET","Address_FR":"212 4928 QUEBEC STREET","City":"Vancouver","PostalCode":"v5w2n2","Province":"BC","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27720876\/212-4928-quebec-street-vancouver","RelativeURLFr":"\/immobilier\/27720876\/212-4928-quebec-street-vancouver","isReferenceMatch":false,"isPostalCodeMatch":false},{"Type":1,"ListingId":"27741486","ReferenceNumber":"X11894528","Address_EN":"558 QUEBEC STREET","Address_FR":"558 QUEBEC STREET","City":"Hamilton (Parkview)","PostalCode":"l8h6v4","Province":"ON","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27741486\/558-quebec-street-hamilton-parkview-parkview","RelativeURLFr":"\/immobilier\/27741486\/558-quebec-street-hamilton-parkview","isReferenceMatch":false,"isPostalCodeMatch":false},{"Type":1,"ListingId":"27754883","ReferenceNumber":"S11901084","Address_EN":"267 QUEBEC STREET","Address_FR":"267 QUEBEC STREET","City":"Clearview (Stayner)","PostalCode":"l0m1s0","Province":"ON","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27754883\/267-quebec-street-clearview-stayner-stayner","RelativeURLFr":"\/immobilier\/27754883\/267-quebec-street-clearview-stayner","isReferenceMatch":false,"isPostalCodeMatch":false}],"ResultsMapBox":[{…