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 de solo lectura y requiere un token emitido por un administrador. Inicia sesión y solicita acceso, describiendo tu integración. Los administradores de Suelo revisan las solicitudes, emiten tokens para usuarios específicos y los entregan directamente. Los usuarios no pueden emitir ni revocar tokens. La vigencia predeterminada es de 90 días; un administrador puede elegir entre 1 y 365 días y revocar el acceso en cualquier momento.

Envía el token con cada consulta de datos:

curl -H "Authorization: Bearer <token>" https://suelo.casa/api/v1/listings

Un token ausente, inválido, vencido o revocado devuelve 401. No se aceptan sesiones del navegador ni tokens en la URL. CORS permite Authorization. La descripción OpenAPI, el catálogo y el estado del servicio siguen públicos. Más detalles en auth.md.

Por favor identifica tu cliente en el encabezado User-Agent. Las respuestas de datos son privadas y no se cachean: la revocación se aplica en la siguiente consulta.

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.