imotesa.bg

Compare asking prices in two to five neighbourhoods of the same Bulgarian city for one market segment (property type, sale or rent, optional room count). For each area: median and average price per m², the middle 50% range, median total price, sample size, a rank and how much pricier it is than the cheapest compared area. Use this when the user compares neighbourhoods by price or asks which of several areas is cheaper. Do not use it for: a single area (use get_market_stats), areas in different cities, individual listings (use search_properties), or lifestyle questions (schools, safety, transport), which Imotesa has no data on. All figures are ASKING prices in EUR (rent is monthly), not transaction prices. rank 1 is the MOST expensive area; pct_above_cheapest is relative to the cheapest compared area. An area with available=false has too few listings for statistics and is not ranked. Areas accept slugs or names; if location_matches is present, tell the user which neighbourhood was used.

compare_areas

Get the current details of one Bulgarian property by its Imotesa slug: attributes, Bulgarian description, current asking prices (sale and/or rent), the live listings offering it (portal, agency, price, when first and last seen), photos and the imotesa.bg page. Use this when the user asks about a specific property from an earlier search_properties result; pass that result's "slug". The slug is also the last path segment of an imotesa.bg property URL. Do not use it for: finding properties (use search_properties), how the price changed over time (use get_property_history), or area-wide prices. Prices are asking prices in EUR (monthly for rent), not sale prices, and come only from live listings: an inactive property has none. If merged_from is present, the property asked for was found to be a duplicate and merged into this one, whose slug differs; use the new slug from then on. NOT_FOUND means no property has this slug; search again.

get_property

Get the observed asking-price history of one Bulgarian property by its Imotesa slug: for each portal listing that has offered it (active or not), when it was first and last seen, every asking price observed, and each meaningful price change. Use this when the user asks whether a specific property was reduced or raised, relisted, or how long it has been on the market; pass the "slug" of a search_properties result. Do not use it for: area-wide price trends, or the current details of a property (use get_property). These are asking prices in EUR as advertised (monthly for rent), not sale prices: nothing here says what a buyer paid. Each listing has its own series; do not join them into one timeline, because different sellers and agencies price the same property independently. Moves under 1% are not counted as changes. change_summary counts changes across all listings. If merged_from is present, the property asked for was merged into this one as a duplicate, and the history covers the listings of both.

get_property_history

Get asking-price statistics for one Bulgarian property market segment: a city or one of its neighbourhoods, a property type, sale or rent, and optionally a room count. Returns the price per m² and total price distribution (average, median, percentiles), the sample size, and optionally the monthly history. Use this when the user asks what property costs in a place, the typical price per square metre, how prices are spread, or how they moved over recent months. Do not use it for: individual listings (use search_properties), one property (use get_property), comparing several neighbourhoods (use compare_areas), forecasts, or what buyers actually paid. All figures are ASKING prices in EUR (rent is monthly), not transaction prices; say so when quoting them. Prefer the median. city and area accept a slug or a Bulgarian/English name; if location_matches is present, the place was matched approximately — tell the user which place the figures are for. available=false means Imotesa publishes no statistics for that segment (too few listings); try a wider segment (no rooms, or the whole city). Link the user to attribution_url.

get_market_stats

List or look up the canonical Bulgarian city and neighbourhood slugs that the other Imotesa tools accept. Call with type="cities" for every city, or type="areas" plus a city for that city's neighbourhoods. Add query to find places by name (Bulgarian or English, prefix and small typos tolerated; for areas also by landmark), best match first. Use this when you need a slug, need to check that a place exists, or want to show the user which neighbourhoods a city has. You do not need it before get_market_stats or compare_areas, which accept names directly. Slugs are Latin transliterations ("sofiya", "sofiya-lozenec"); name_en is a transliteration too ("Lozenec"), not always the usual English spelling. infrastructure and nature are Imotesa scores from 0 to 10, present only for some areas: nature is measured from land-cover maps on one scale for all cities; infrastructure ranks transit, drive time and everyday amenities within the area's city. similar lists areas editorially judged comparable.

list_locations

Resolve a structured property filter to the canonical imotesa.bg category-page URL for that filter set. The returned URL is stable and citeable; fetching it returns HTML that embeds Schema.org RealEstateListing JSON-LD an agent can parse. All fields are optional; an empty call resolves to all active sale listings. Slugs (city, areas, property_type) must come from list_locations or the documented enums.

resolve_search_url

Search the current, active property listings in Bulgaria (sale or rent) with a natural-language query in Bulgarian or English, e.g. "Двустаен в Лозенец до 250 000 евро" or "3-room flat in Plovdiv under 200k". Each result is one deduplicated property, even when several portals or agencies list it. Use this when the user wants to find properties that match their preferences. For more about one result, pass its "slug" to get_property (details, all current offers) or get_property_history (price changes). Do not use it for: a property you already have a slug or imotesa.bg link for, the price history of a property, average or median prices of an area, comparing neighbourhoods, sold (transaction) prices, mortgages, legal questions, or anywhere outside Bulgaria. Prices are asking prices in EUR (monthly for rent), not sale prices. Always check normalized_filter: it shows how the query was understood. unresolved_locations lists places that matched nothing and were left out of the search, so the results cover a wider area than the user asked for. total is the number of all matches; results holds at most "limit" of them, newest first.

search_properties