Respuestas de mercado

Una clave con market:read pregunta qué piden las propiedades en el mercado de Costa Rica: la misma respuesta de mercado que ve tu equipo en la página Mercado de la consola. Úsala para ponerle precio a una propiedad, respaldar una conversación sobre el precio o seguir una zona.

Solo precios de lista

Costa Rica no tiene MLS ni precios de venta públicos, así que cada respuesta habla de precios de lista: lo que piden los anuncios de agencias y portales, recolectados una vez al mes. Los precios están en USD; los colones se convierten al tipo del BCCR del mes en que se vio cada precio. Un alquiler es mensual.

Hacer una pregunta

GET /v1/market/answer recibe la consulta de mercado como parámetros, los mismos que la consola guarda en la dirección de la página Mercado:

  • place — un código de Lugar de cualquier nivel, p. ej. CR-30301 (Tres Ríos) o el barrio CR-1090311 (Valle del Sol). Un Lugar cuenta los anuncios en él y debajo de él. Omítelo para todo el país.
  • development — el id de un condominio (como lo dan los place_candidates de la herramienta MCP): solo sus anuncios. Su Lugar es el place de la consulta.
  • operation — sale (por defecto) o rent.
  • type — un tipo de propiedad, p. ej. house o land.
  • beds con beds_mode — exact (por defecto) o at_least.
  • baths con baths_mode — at_least (por defecto) o exact.
  • in_development — en condominio: yes, no o any (por defecto); include_unknown=true cuenta también los anuncios con condominio desconocido.
  • since y until — fechas: los anuncios en el mercado en algún momento de ese periodo, al último precio que pidieron en él. Sin ellas, los anuncios en el mercado hoy.
  • near — tu propio precio de lista en USD. La respuesta lo ubica (price_rank) y, por defecto, lista primero los comparables más cercanos a él.
  • sort — el orden de los comparables: close (por defecto: los más cercanos a near, o a la mediana), price o per_m2, de menor a mayor.
curl "https://api.letsrealty.io/v1/market/answer?place=CR-30301&type=house&beds=3&in_development=yes&near=385000" \
  -H "Authorization: Bearer $LETSREALTY_API_KEY"

Un Lugar o condominio que no existe, o un periodo que termina antes de empezar, es un 422. Mientras las respuestas de mercado aún no estén abiertas, la respuesta es un 403 con el detalle market_unavailable; GET /v1/tenant dice si lo están (market_check_enabled).

Leer la respuesta

statistics cuenta propiedades, no anuncios: una casa publicada en tres sitios cuenta una vez, a la mediana de sus precios de lista. matched es cuántas coinciden y priced cuántas de ellas tienen un precio no marcado; las estadísticas son sobre estas. Lo que recibes depende de band:

  • none — menos de 5 con precio: ninguna estadística, solo los comparables.
  • low — de 5 a 9: la mediana (median), con low_n: true.
  • full — 10 o más: la mediana, p25 y p75 (la mitad central), p10 y p90 (donde piden 8 de cada 10), min y max, y el histogram.

median_per_m2 (m² construidos, m² de lote en terrenos) necesita 5 propiedades con esa área. Un área menor a 20 m², o imposible para el tipo, queda fuera de todo precio por m² (el usd_per_m2 del comparable es null), pero su precio sigue contando; per_m2_count es cuántas áreas se leyeron. time_on_market_days y trend_pct quedan en null hasta una segunda recolección mensual.

histogram reparte los precios de lista de las propiedades con precio en 20 tramos (buckets) del mismo ancho, de low (el percentil 5) a high (el 95), cada uno con su low, high y count; below y above cuentan los que quedan fuera, así que below, los tramos y above suman priced. Es null si la banda no es full.

scopes dice cuántas propiedades con precio hay donde preguntaste y, con menos de 5 en un condominio o en un Lugar bajo la provincia, en cada nivel más amplio hasta el cantón, hasta que uno tenga 5: el condominio, su Lugar, el Lugar que lo contiene. Cada uno trae su level (la clave del nivel, o development), level_label por idioma, name, count y statistics, primero el que preguntaste, para decir "En Valle del Sol hay 3; incluyendo todo Pozos hay 41". Las statistics de la respuesta siguen siendo las del lugar preguntado. development_name nombra el condominio preguntado.

by_type viene cuando no pides type: por cada tipo de propiedad con alguna con precio, de la que más tiene a la que menos, su priced, band, median, p25, p75 y median_per_m2, con las mismas bandas. Con un type viene vacío.

Con near, price_rank es el porcentaje de los comparables con precio (las propiedades que puedes ver) que piden menos, en enteros: 62 significa que tu precio está sobre el 62% de ellas. Es null sin near o con menos de 5 con precio. crc_per_usd es el último tipo mensual del BCCR, para convertir a USD un precio en colones antes de pasarlo en near.

method dice cómo se hizo la respuesta, para una línea bajo tus cifras: run_dates (cuándo se recolectaron los anuncios), publishers, los conteos de precisión del Lugar (precision), los fx_rates usados, los anuncios multi_publisher y merged contados una vez, y cuántos quedaron fuera por condominio desconocido (unknown_development_left_out) por un precio que parece incorrecto (flagged_left_out) o por un área de la que no se puede leer un precio por m² (area_left_out).

Comparables

comparables son las propiedades que coinciden en el orden de sort (por defecto, las más cercanas a near o a la mediana, de la más barata a la más cara si no hay mediana; las que no tienen precio, o precio por m² con per_m2, al final), de limit en limit (hasta 200; 50 por defecto). Pasa next_cursor como cursor, con el mismo sort y near, para la siguiente página hasta que sea null; comparable_count es cuántas hay. Cada una trae sus publishers (nombre y enlace al anuncio), sus listings con el price y la currency originales y el price_usd, su Lugar y place_precision, in_development, y un price_flag cuando su precio parece incorrecto. Los precios marcados quedan fuera de las estadísticas.

Las propiedades de tu propio sitio también se recolectan cada mes: cuentan y vuelven como comparables con is_yours: true. Las de otras agencias en LetsRealty cuentan en las estadísticas, pero nunca se muestran.

Límite de uso

Las respuestas tienen su propio límite de 30 por minuto por agencia, compartido por todas las claves y la herramienta MCP, igual en todos los planes. Tus otras llamadas no se ven afectadas. Consulta Límites de uso.

MCP

La herramienta market_answer del servidor MCP hace la misma pregunta con los mismos parámetros. Su place acepta también el nombre de un cantón, distrito, barrio o condominio, o el id de un condominio; un nombre que puede ser varios devuelve place_candidates para elegir, en vez de una respuesta.