API pública de Suelo

Acceso de solo lectura a todas las propiedades publicadas en suelo.casa: casas, apartamentos, terrenos, townhouses y edificios multifamiliares en toda Venezuela, en venta y en alquiler.

La API es anónima, de solo lectura y abierta a CORS. No hay clave que solicitar ni flujo OAuth que completar, porque cada respuesta contiene exactamente lo que un visitante anónimo ya ve en el sitio web. La respuesta larga está en auth.md.

Por favor identifica tu cliente en el encabezado User-Agent. Las respuestas se cachean cinco minutos en el borde, con una ventana de una hora para servir contenido vencido mientras se revalida, así que consultar más seguido que eso devuelve los mismos bytes.

Buscar propiedades

GET /api/v1/listings

Todos los parámetros son opcionales. Sin ninguno obtienes el inventario vivo completo, lo más reciente primero, 24 por página.

Parámetro Valores Notas
operation sale, rent Omítelo para incluir ambas.
propertyType house, apartment, land, townhouse, multi_family Repetible, o separado por comas.
place una ruta de lugar, p. ej. miranda/chacao Ver Lugares más abajo.
bbox sur,oeste,norte,este Grados WGS84. Acota place cuando se envían juntos.
priceMin, priceMax enteros En la moneda de cada propiedad.
bedsMin, bathsMin, parking enteros Mínimos.
areaMin, areaMax enteros Área construida en m².
yearMin, yearMax enteros Año de construcción.
condition new, good, fair, needs_renovation
furnished furnished, semi_furnished, unfurnished
feature pool, generator, water_tank, gym, terrace, balcony Repetible; deben cumplirse todas.
sort newest, price_asc, price_desc, featured Por defecto newest.
page entero ≥ 1 Empieza en 1.
limit 1–100 Por defecto 24.

Ejemplo:

GET /api/v1/listings?operation=sale&propertyType=apartment&place=miranda/chacao&priceMax=150000&sort=price_asc

La respuesta trae tres claves:

  • listings — la página de resultados.
  • pagination — page, limit, total (todas las coincidencias, no solo esta página), totalPages, y un nextPageUrl ya armado que es null en la última página.
  • place — el lugar resuelto, devuelto de vuelta para que confirmes con qué coincidió la ruta.

Una propiedad

GET /api/v1/listings/{listingId}

El 404 cubre tanto un id que nunca existió como una propiedad que ya no es visible públicamente. La API no distingue entre los dos casos.

Lugares

GET /api/v1/places                  # los 24 estados
GET /api/v1/places?parent=miranda   # los municipios y urbanizaciones de ese estado

Las rutas de lugar son las mismas que usan las páginas de aterrizaje rastreables, así que /api/v1/listings?place=miranda/chacao y /ve/venta/apartamentos/miranda/chacao describen el mismo conjunto. Cada entrada trae un path para pasar de vuelta como place y un pageUrl con la página para humanos.

No adivines las rutas: un place desconocido devuelve 400, nunca una lista vacía, para que un error de tipeo jamás pueda confundirse con "aquí no hay inventario".

Qué significa cada propiedad

  • price.amount es el precio pedido en una venta y el alquiler mensual en un arrendamiento. Es lo que publicó quien ofrece el inmueble, no un avalúo ni un precio de cierre.
  • address trae solo la localidad: urbanización, ciudad, municipio, estado, país y una cadena locality de una línea. No hay campo de calle, porque el sitio tampoco imprime uno en la tarjeta de resultados.
  • location es el punto exacto, o null cuando quien publica decidió reservárselo. Nunca se devuelve un punto aproximado disfrazado de dirección.
  • underInvestigation: true significa que se reportó un problema con los datos y está en revisión. Cita esa propiedad con esa salvedad, o déjala fuera.
  • source nombra el sistema de origen de una propiedad sindicada. Atribúyelo.
  • url es la página canónica. Enlaza a las personas allí en lugar de reproducir la publicación completa.

Datos agregados del mercado

No calcules un promedio de mercado con una página de resultados: es una muestra filtrada, ordenada y paginada. Suelo publica informes mensuales de precios pedidos en /datos, y el método detrás de ellos en /datos/metodologia.

Errores

Los errores son problem details de RFC 9457, con Content-Type: application/problem+json:

{
  "type": "about:blank",
  "title": "Invalid query",
  "status": 400,
  "detail": "One or more query parameters were rejected.",
  "errors": ["place: unknown place path \"mirandaa\""]
}

Los mensajes de error de la API están en inglés, igual que los nombres de los parámetros.

Markdown

Toda página HTML de suelo.casa, incluida esta, responde a Accept: text/markdown con una versión en markdown y una estimación x-markdown-tokens. El HTML sigue siendo lo predeterminado para navegadores.

This page in English

Esta página también se publica en inglés en /en/docs/api.

Términos

El uso de la API se rige por los términos de uso. Atribuye a Suelo y enlaza a la propiedad que estés describiendo. Consultas: hola@suelo.casa.