imot-bg-snapshot

Fetch a complete snapshot of your imot.bg adverts via their Import API — paginated, with full details (IDs) and images (filenames).

What it does

Walks every page of your imot.bg account (/adverts/loadall), then loads the full details for each advert (/adverts/load) — including the complete picts image list. The result is saved as a single JSON file you can use for analysis, migration, or data matching.

Handles:

• Automatic pagination (imot.bg returns the last page again instead of an empty one — this library detects and stops correctly)
• Sale and Rent categories
• Full image list per advert
• Optional proxy support (needed on servers that can't reach api.imot.bg directly)
• Polite request delay to stay within API limits

Requirements

• Node.js ≥ 18
• An active imot.bg Import API account

Installation

npm install imot-bg-snapshot
# or for one-off CLI use:
npx imot-bg-snapshot --help

CLI usage

[email protected] \
IMOT_BG_PASSWORD=yourpassword \
npx imot-bg-snapshot --pretty --output snapshot.json

Or create a .env file in your working directory:

[email protected]
IMOT_BG_PASSWORD=yourpassword
# Optional proxy (if your server can't reach api.imot.bg directly):
# IMOT_BG_PROXY_URL=http://proxy-host:8000
# IMOT_BG_PROXY_AUTH=user:pass

Then just run:

npx imot-bg-snapshot --pretty

Options

| Flag | Default | Description | |---|---|---| | --output, -o | imot-bg-snapshot.json | Output file path | | --limit, -l | 0 (all) | Fetch only first N adverts (useful for testing) | | --delay, -d | 250 | Milliseconds between API requests |

Categories fetched by default: all six — Продажба (1), Наем (2), Купува (3), Търси да наеме (4), Заменя (5), Съквартиранти (6). Pass categories: [1, 2] to restrict. | --pretty | off | Pretty-print JSON output | | --help, -h | — | Show help |

Programmatic API

import { fetchImotBgSnapshot } from "imot-bg-snapshot";

const snapshot = await fetchImotBgSnapshot({
  username: process.env.IMOT_BG_USERNAME!,
  password: process.env.IMOT_BG_PASSWORD!,
  // proxyUrl: "http://proxy-host:8000",  // optional
  // limit: 10,                           // optional, 0 = all
  // delay: 250,                          // ms between requests
  // categories: [1, 2, 3, 4, 5, 6],       // default: all — see ImotBgConfig for full list
});

console.log(`Fetched ${snapshot.totalAdverts} adverts`);

for (const advert of snapshot.adverts) {
  console.log(advert.ida, advert.title, `${advert.picts.length} images`);
}

Lower-level functions

import { login, fetchAdvertsPage, fetchAdvertDetail } from "imot-bg-snapshot";

const token = await login(username, password);
const page1 = await fetchAdvertsPage(token, 1 /* pn */, 1 /* page */);
const detail = await fetchAdvertDetail(token, "{IDS}");

Output shape

{
  "fetchedAt": "2026-03-14T10:00:00.000Z",
  "totalAdverts": 451,
  "adverts": [
    {
      "ida": "{IDS}",
      "code": "CODE",
      "pubtime": "1754341860",
      "rub": "1",
      "type_home": "1",
      "price": "83573",
      "town": "4",
      "craion": "577",
      "praion": "",
      "area": "51",
      "extinfo": "Описание на имота...",
      "extri": ["53"],
      "picts": [
        { "file": "{IDS}_ow.jpg" },
        { "file": "{IDS}_qM.jpg" }
      ],
      "title": "TITLE_HERE",
      "pict": "//cdn3.focus.bg/imot/photosimotbg/1/465/big/{IDS}_ow.jpg"
    }
  ]
}

Note on picts: Only images uploaded via the API (pubpictslinks) appear with .pic extensions. Images uploaded through the imot.bg web UI appear as .jpg files. Both are normalised to bare filenames in the output.

TypeScript types

All types are exported from the package:

import type {
  ImotBgConfig,
  ImotBgSnapshot,
  ImotBgAdvert,
  ImotBgPicture,
  FetchProgress,
} from "imot-bg-snapshot";

License

MIT