# imoti.net Property Search API Documentation

Scrappa's `GET /api/imoti-net/search` returns imoti.net property listings in Bulgaria as structured JSON, for sale (`ad_type=sale`) or for rent (`rent`).

## What you get

One request returns one page of up to 30 listings. Each listing has `id`, `url`, `title`, `property_type`, `location` with `city` and `district`, `price` in euro and lev, `area_sqm`, `floor`, `price_per_sqm`, the `publisher` (agency or private seller), a `thumbnail`, `photo_count`, a `promoted` flag and a short `summary`. Call the listing endpoint for the full record.

## Filters are honoured

`location` is required and takes an id from `/api/imoti-net/locations`. An id that does not exist returns `422` (`unknown_location`). Price, property type and sort are applied by imoti.net itself. A listing whose own price cannot confirm a price filter is left out and counted in `meta.omitted_unverifiable`. If imoti.net cannot apply the filters the request fails, and it never returns an unfiltered list. `applied_filters` echoes what was applied.

## Property types

`property_type` takes one or more keys separated by commas: one_room, two_room, three_room, four_room, multi_room, maisonette, studio, office, room, garage, basement, building, house, house_floor, villa, plot, care_home, hall, shop, commercial, venue, industrial, gas_station, hotel, warehouse, factory, farmland, farm, forest, reservoir, prefab_house, project, beach. Rooms are only available as property types (`one_room`, `two_room`, ...).

## Price and currency

`price_min` and `price_max` are whole numbers in `currency` (`eur`, the default, or `bgn`).

## Sort

`sort` is one of `price`, `property_type`, `location`, `area`, `price_per_sqm` or `newest`. A filtered or sorted search is ordered by price when no sort is given. Promoted listings stay on top of every page.

## Pagination

`page` is 1-based with 30 listings per page. `pagination.pages_count` is the last page. A page past the last page returns an empty list, never another page's listings, and `pages_count` can be `null` when imoti.net gives no page count for that page. imoti.net gives no total count and shows at most 34 pages for one search (1,020 listings), so narrow big cities with price or property type filters.

## Not available

imoti.net has no area filter, no bedrooms or bathrooms filter and no standalone agent profile. The first call of a new filter set makes two lookups, later pages one.

- **Documentation:** [https://scrappa.co/docs/imoti-net-api/imoti_net_search](https://scrappa.co/docs/imoti-net-api/imoti_net_search)
- **API group:** imoti.net API
- **Endpoint:** `GET https://scrappa.co/api/imoti-net/search`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `ad_type` | string | Yes | sale or rent. |
| `location` | integer | Yes | Location id from /api/imoti-net/locations, for example 1 for Sofia. |
| `property_type` | string | No | Comma separated property type keys, for example two_room,three_room. |
| `price_min` | integer | No | Minimum price in `currency`. |
| `price_max` | integer | No | Maximum price in `currency`. |
| `currency` | string | No | eur (default) or bgn. Applies to price_min and price_max. |
| `sort` | string | No | price, property_type, location, area, price_per_sqm or newest. |
| `page` | integer | No | Result page, 1-based. 30 listings per page. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/imoti-net/search?ad_type=sale&location=1&property_type=two_room&price_min=100000&price_max=200000&sort=price"
```

## Example response

```json
{
    "success": true,
    "returned": 1,
    "pagination": {
        "page": 1,
        "limit": 30,
        "pages_count": 34,
        "has_next_page": true,
        "has_previous_page": false
    },
    "applied_filters": {
        "ad_type": "sale",
        "location": {
            "id": 1,
            "name": "\u0421\u043e\u0444\u0438\u044f"
        },
        "property_type": [
            "two_room"
        ],
        "price_min": 100000,
        "price_max": 200000,
        "currency": "eur",
        "sort": "price"
    },
    "listings": [
        {
            "id": "6175289",
            "url": "https://www.imoti.net/bg/obiava/prodava/sofia/gorna-banja/dvustaen/6175289",
            "title": "\u043f\u0440\u043e\u0434\u0430\u0432\u0430 \u0414\u0432\u0443\u0441\u0442\u0430\u0435\u043d \u0430\u043f\u0430\u0440\u0442\u0430\u043c\u0435\u043d\u0442, 89 \u043c2",
            "ad_type": "sale",
            "is_new_build": false,
            "property_type": "\u0414\u0432\u0443\u0441\u0442\u0430\u0435\u043d \u0430\u043f\u0430\u0440\u0442\u0430\u043c\u0435\u043d\u0442",
            "location": "\u0421\u043e\u0444\u0438\u044f, \u0413\u043e\u0440\u043d\u0430 \u0411\u0430\u043d\u044f",
            "city": "\u0421\u043e\u0444\u0438\u044f",
            "district": "\u0413\u043e\u0440\u043d\u0430 \u0411\u0430\u043d\u044f",
            "price": {
                "eur": 267120,
                "bgn": 522441,
                "on_request": false
            },
            "area_sqm": 89,
            "floor": {
                "number": 1,
                "total": 5,
                "label": "1 \u043e\u0442 5"
            },
            "building_floors": null,
            "price_per_sqm": {
                "eur": 3001,
                "bgn": 5870.13
            },
            "publisher": {
                "name": "Barnes Bulgaria",
                "type": "agency",
                "is_recommended": true
            },
            "thumbnail": "https://www.imoti.net/web/files/obiavi/6175289/main_image/thumb_280x210_1.jpg?ver=1792994645",
            "photo_count": 14,
            "promoted": true,
            "promotion": "\u0418\u0437\u0431\u0440\u0430\u043d\u0430",
            "summary": "\u041f\u0440\u0435\u0434\u0441\u0442\u0430\u0432\u044f\u043c\u0435 \u0441\u043b\u044a\u043d\u0447\u0435\u0432 \u0434\u0432\u0443\u0441\u0442\u0430\u0435\u043d \u0430\u043f\u0430\u0440\u0442\u0430\u043c\u0435\u043d\u0442 \u043d\u0430 \u043f\u044a\u0440\u0432\u0438 \u0435\u0442\u0430\u0436 \u043e\u0442 \u043e\u0431\u0449\u043e \u043f\u0435\u0442 \u0432 \u043f\u0440\u0435\u0441\u0442\u0438\u0436\u0435\u043d \u043a\u043e\u043c\u043f\u043b\u0435\u043a\u0441 ..."
        }
    ],
    "meta": {
        "endpoint_family": "search",
        "billable": true,
        "attempts": 2,
        "omitted_unverifiable": 0
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Unknown Location | The `location` id is not in the imoti.net location list (`unknown_location`). Non-billable. |
| 422 | Validation Error | A query parameter is missing, unknown or unusable. Unknown parameters are rejected, never ignored. Non-billable. |
| 503 | Upstream Unavailable | imoti.net could not be reached after retries, answered with an error, or returned an unexpected answer (`upstream_unavailable`, `upstream_blocked`, `parser_drift`). Retryable and never billed. Clients are never rate limited. |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)