Market answers

A key with market:read asks what listings on the market in Costa Rica ask: the same Market Answer your team sees on the console's Market page. Use it to price a listing, back a pricing conversation or watch a neighbourhood.

Asking prices only

Costa Rica has no MLS and no public sold prices, so every answer is about asking prices: what listings on agency sites and portals ask, crawled once a month. Prices are in USD; colones are converted at BCCR's rate for the month each price was seen. A rent is per month.

Asking a question

GET /v1/market/answer takes the Market Query as query parameters, the same ones the console keeps in the Market page's URL:

  • place — a Place code at any Level, e.g. CR-30301 (Tres Ríos) or the barrio CR-1090311 (Valle del Sol). A Place counts the listings in it and beneath it. Leave it out for the whole country.
  • development — a Development's id (a condominium, as the MCP tool's place_candidates give it): only the listings in it. Its Place is the query's place.
  • operation — sale (the default) or rent.
  • type — a Property Type, e.g. house or land.
  • beds with beds_mode — exact (the default) or at_least.
  • baths with baths_mode — at_least (the default) or exact.
  • in_development — in a condominium: yes, no or any (the default); include_unknown=true also counts listings whose condominium status is unknown.
  • since and until — dates: the listings on the market at some point in that window, at the last price they asked in it. Without them, the listings on the market now.
  • near — your own asking price in USD. The answer ranks it (price_rank) and, by default, lists the comparables closest to it first.
  • sort — the comparables' order: close (the default: closest to near, else to the median), price or per_m2, lowest first.
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"

A Place or Development that doesn't exist, or a window that ends before it starts, is a 422. While market answers aren't open yet, the answer is a 403 with the detail market_unavailable; GET /v1/tenant says whether they are (market_check_enabled).

Reading the answer

statistics counts Market Properties, not listings: one house shown on three sites counts once, at the median of its asking prices. matched is how many match and priced how many of those have a price that isn't flagged; the statistics are over the priced ones. How much you get depends on band:

  • none — under 5 priced: no statistic, only the comparables.
  • low — 5 to 9: the median, with low_n: true.
  • full — 10 or more: the median, p25 and p75 (the middle half), p10 and p90 (where 8 in 10 ask), min and max, and the histogram.

median_per_m2 (built m², lot m² for land) needs 5 properties with that area. An area under 20 m², or implausible for the type, is left out of every price per m² (the comparable's usd_per_m2 is null) while its price still counts; per_m2_count is how many areas were read. time_on_market_days and trend_pct stay null until a second monthly crawl.

histogram puts the priced properties' asking prices in 20 equal-width buckets from low (the 5th percentile) to high (the 95th), each with its low, high and count; below and above count the ones outside, so below, the buckets and above add up to priced. It is null under a full band.

scopes says how many priced properties there are where you asked and, under 5 in a Development or a Place below the province, at each wider Level up to the canton, until one has 5: the Development, its Place, that Place's parent. Each scope has its level (the Level's key, or development), level_label by language, name, count and statistics, the one asked first, so you can say "3 in Valle del Sol; 41 counting all of Pozos". The answer's own statistics stay the narrow ones. development_name names the Development asked about.

by_type comes when you ask no type: for each Property Type with a priced property, most priced first, its priced, band, median, p25, p75 and median_per_m2, by the same bands. With a type it is empty.

With near, price_rank is the share of the priced comparables (the properties you may see) asking less than it, in whole percent: 62 means your price is above 62% of them. It is null without near or under 5 priced. crc_per_usd is BCCR's latest monthly rate, to turn a colones price into the USD near takes.

method says how the answer was made, for a line under your numbers: run_dates (when the listings were collected), publishers, Place precision counts, the fx_rates used, multi_publisher and merged listings counted once, and how many listings were left out for an unknown condominium status (unknown_development_left_out), a price that looks wrong (flagged_left_out) or an area a price per m² can't be read from (area_left_out).

Comparables

comparables are the matching properties in the sort order (closest to near or the median by default, cheapest first when there is no median; those without a price, or without a price per m² for per_m2, last), limit at a time (up to 200; 50 by default). Pass next_cursor back as cursor, with the same sort and near, for the next page until it is null; comparable_count is how many there are. Each has its publishers (name and link to the listing), its listings with the original price and currency and the price_usd, its Place and place_precision, in_development, and a price_flag when its price looks wrong. Flagged prices are left out of the statistics.

The listings on your own site are collected monthly too: they count and come back as comparables with is_yours: true. Other agencies' listings on LetsRealty are counted in the statistics but never shown.

Rate limit

Answers have their own budget of 30 a minute per agency, shared by every key and the MCP tool, the same on every plan. Your other calls are not affected. See Rate limits.

MCP

The market_answer tool of the MCP server asks the same question with the same parameters. Its place also takes a canton, district, barrio or condominium name, or a Development's id; a name that could be several returns place_candidates to pick from instead of an answer.