binaaz-python-sdk

Typed Python client for bina.az, the Azerbaijani real estate site. Sign in with email and password or with an SMS code, post, edit, prolong and delete listings, upload and rotate photos, read the catalog of cities, districts and metro stations. Sync and async, with retry rules built so a listing or a payment is never sent twice.

pip install binaaz-python-sdk

This is not an official bina.az product. It talks to the same endpoints the bina.az website uses, with its own User-Agent. It does not solve captchas or Cloudflare challenges: if bina.az answers with a challenge page you get BlockedError.

Sign in

from binaaz_sdk import BinaAz

with BinaAz() as bina:
    bina.auth.login("agency@example.az", "password")
    saved = bina.cookie

Phone accounts sign in with a code that bina.az sends by SMS:

sent = bina.auth.send_code("050 123 45 67")
profile = bina.auth.verify_code("050 123 45 67", "1234")

bina.cookie is the signed in session. Keep it somewhere safe and pass it back later, so you do not sign in on every run:

bina = BinaAz(cookie=saved)
bina.profile()

A cookie copied from a browser works too, as a header value, a {"name": "value"} mapping or a cookie export list. Cloudflare cookies are dropped, they are never stored or sent. Cookies that bina.az renews are picked up from every answer.

Post a listing

from binaaz_sdk import BinaAz, Category, ContactType, Listing

photos = bina.photos.upload_many(["1.jpg", "2.jpg", "3.jpg", "4.jpg"])

result = bina.items.create(Listing(
    category_id=Category.APARTMENT_OLD_BUILDING,
    is_leased=False,
    price=120000,
    rooms=3,
    area={"value": 85},
    floor={"value": 4, "total": 9},
    location={"address": "Nizami street 10", "city_id": "1", "latitude": 40.379, "longitude": 49.846},
    contact={"type": ContactType.AGENT, "name": "Agency"},
    photo_ids=[p.id for p in photos],
    description="Renovated three room flat near the metro.",
))
result.id, result.url, result.state

bina.az takes 4 to 30 photos on a listing. A new listing starts as pending and moves to published, rejected or awaiting_payment. When bina.az refuses it, ItemError.status tells why: RESTRICTED (confirm the phone number first), UNVERIFIED, INVALID or FAILURE. Field problems are in ItemError.errors.

Manage listings

page = bina.items.list("published", first=50)
everything = bina.items.all()
item = bina.items.get("4123456")

bina.items.update("4123456", listing)
bina.items.prolong("4123456")
bina.items.delete("4123456")

list follows bina.az cursors (page.next_cursor), all reads every page. Tabs are pending, published, rejected, expired and awaiting_payment. An update of a listing under moderation raises ItemError with status="LOCKED" and locked_until. Listing management needs a company profile (agencies and residences); other profiles get NotSupportedError.

Paid services

for service in bina.items.paid_services("4123456"):
    service.title, service.options, service.payment_methods

payment = bina.items.buy_service("4123456", service.id, "wallet", option_id=service.options[0].id, confirm=True)
payment.redirect_url
bina.items.pay("4123456", confirm=True)

Anything that costs money needs confirm=True, otherwise InvalidRequestError is raised before a request is made. A card payment comes back with redirect_url, the page where the payment is finished.

Photos and catalog

photo = bina.photos.upload(open("cover.jpg", "rb"))
photo = bina.photos.rotate(photo.id, 90)

bina.catalog.categories()
bina.catalog.cities()
bina.catalog.regions("1")
bina.catalog.townships("4")
bina.catalog.landmarks("1", 40.379, 49.846)

Uploads take bytes, a path or a file object. Rotating returns a new photo id; use that one in the listing. Catalog calls need no session.

Safety

Endpoints

AsyncBinaAz has the same methods, awaited. graphql(query, variables) sends any other query with the session.

Errors

BinaAzError is the base. Answers raise APIError subclasses: BadRequestError, AuthenticationError (the session is not signed in), NotFoundError, RateLimitError, ServerError and BlockedError. GraphQL errors raise GraphQLError with errors, refused listings raise ItemError with status, errors and locked_until, a wrong SMS code raises CodeRejectedError. Each carries status_code, message and the raw body.

Config

Pass values in code, or set BINAAZ_COOKIE, BINAAZ_TIMEOUT, BINAAZ_MAX_RETRIES, BINAAZ_CODE_ATTEMPTS, BINAAZ_USER_AGENT and the rest, or put them in binaaz.toml (example). Every path is a setting (BINAAZ_ENDPOINTS__GRAPHQL=...). Messages live in messages.yaml and can be replaced with messages.use(...).

Develop

pip install -e ".[dev]" && pytest && ruff check . && mypy src

Links

• Source code: github.com/qiyascc/binaaz-python-sdk
• PyPI: pypi.org/project/binaaz-python-sdk
• Project page: theqiyas.cc/projects/binaaz-sdk
• Author: Qiyas Sadıqov, more projects at theqiyas.cc

License

MIT