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 barrioCR-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'splace_candidatesgive it): only the listings in it. Its Place is the query'splace.operation—sale(the default) orrent.type— a Property Type, e.g.houseorland.bedswithbeds_mode—exact(the default) orat_least.bathswithbaths_mode—at_least(the default) orexact.in_development— in a condominium:yes,noorany(the default);include_unknown=truealso counts listings whose condominium status is unknown.sinceanduntil— 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 tonear, else to the median),priceorper_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: themedian, withlow_n: true.full— 10 or more: the median,p25andp75(the middle half),p10andp90(where 8 in 10 ask),minandmax, and thehistogram.
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.