bina.az Python SDK

bina.az is where most of Azerbaijan looks for a flat. Agencies post dozens of listings there every week, by hand, one form at a time. This SDK lets a program do it: sign in, upload the photos, post the listing, keep it alive and take it down when the flat is sold.

bina.az has no public API. The client talks to the same endpoints the bina.az website uses, with its own User-Agent, as one signed in account. It is not an official bina.az product, and it does not solve captchas or Cloudflare challenges. If bina.az answers with a challenge page, you get BlockedError and nothing else happens.

What it does

• Sign in with email and password, or with a code bina.az sends by SMS. The session is a cookie you can save and pass back next time, so a script does not sign in on every run. A cookie copied from a browser works too.
• Listings. Post, edit, prolong and delete, and list them by tab: pending, published, rejected, expired, awaiting payment. A refused listing says why: the phone is not confirmed, the account is not verified, or a field is wrong.
• Photos. Upload from bytes, a path or a file, and rotate. bina.az wants 4 to 30 per listing, and the client checks that before sending.
• Catalog. Categories, cities, districts, townships and metro stations near a point on the map.
• Paid services. Boosting a listing or paying for it needs confirm=True. Without it, nothing is sent.

Never twice

A listing or a payment must not go out twice. So when a create, update, delete, payment or sign in times out, the client does not retry. It raises OutcomeUnknownError and you check the account first. Reads, on the other hand, retry with backoff, and a 429 waits for Retry-After.

The SMS login service on bina.az sometimes drops answers, so asking for a code is retried a few times. If that means more than one SMS may arrive, the result says so, and a rejected code warns that the earlier attempt may have used it.

Built with Python, httpx and Pydantic, sync and async, typed with mypy and covered by 60 tests. MIT licensed.