Suelo Casa tutorial

What Suelo Casa is

Suelo Casa is a housing price prediction service: a map of real listings plus a geo-aware model that estimates the price of a home at any point you click, with a confidence score, a price range and the nearest comparable sales.

• Datasets: venezuela (live listings from the Suelo Casa Supabase project, when its tables are readable: homes, commercial space and land for sale plus monthly rentals in one list, each priced by its market's model; the single markets supabase, supabase_land and supabase_rent can be served on their own), king_county (house sales in King County, WA) and boston (the corrected Boston Housing census tracts). The first available one is the default; GET /datasets lists what this server loaded.
• One model per dataset: inputs differ per dataset (for venezuela: operation, type, square metres, bedrooms, age, parking, 44 yes/no features and optional quality scores; sqft for King County; rooms per dwelling for Boston). GET /config?dataset=... describes them; POST /predict takes a lat/lon plus any of those inputs, and fills the rest from nearby listings.
• Accounts: register with a username and password, sign in on the map or with POST /api/auth/login. Data and prediction endpoints need a signed-in user.
• API tokens: long-lived opaque tokens for scripts, created and revoked on the Tokens page or with /api/auth/tokens. Only a SHA-256 digest of each token is stored.
• Organizations: create one, create accounts for collaborators, group them in teams (Orgs). Your profile and password are on the Cuenta page.

Everything runs as one uvicorn process on port 8039: the map at /, this tutorial at /tutorial, a share page at /share and the OpenAPI docs at /docs.

Quick start

Check the server is up (no account needed):

curl https://pricepredai.interdataresearch.ai/health

1. Create an account and sign in

Usernames are 3-64 characters (letters, digits, _ . @ + -), passwords at least 8. Name and email are optional; with an email you can also sign in with it instead of the username. The commands below ask for the password instead of keeping it in your shell history.

read -rsp 'Password: ' SC_PASS; echo
curl -sS -X POST https://pricepredai.interdataresearch.ai/api/auth/register \
  -H 'Content-Type: application/json' \
  -d "{\"username\":\"ada\",\"name\":\"Ada\",\"email\":\"ada@example.com\",\"password\":\"$SC_PASS\"}"

SESSION=$(curl -sS -X POST https://pricepredai.interdataresearch.ai/api/auth/login \
  -H 'Content-Type: application/json' \
  -d "{\"username\":\"ada\",\"password\":\"$SC_PASS\"}" \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["token"])')

Login answers {ok, username, must_change_password, token, token_type} and also sets the session cookie the map uses. The session token lasts 7 days.

2. Create an API token

TOKEN=$(curl -sS -X POST https://pricepredai.interdataresearch.ai/api/auth/tokens \
  -H "Authorization: Bearer $SESSION" \
  -H 'Content-Type: application/json' \
  -d '{"name":"my script","expires_in_days":30}' \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["token"])')

3. Explore a dataset and predict

curl -sS https://pricepredai.interdataresearch.ai/datasets -H "Authorization: Bearer $TOKEN"
curl -sS "https://pricepredai.interdataresearch.ai/config?dataset=boston" -H "Authorization: Bearer $TOKEN"
curl -sS "https://pricepredai.interdataresearch.ai/properties?dataset=boston" -H "Authorization: Bearer $TOKEN" | head -c 400; echo

curl -sS -X POST https://pricepredai.interdataresearch.ai/predict \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"dataset":"boston","lat":42.35,"lon":-71.08,"RM":6.5}'

For Venezuela, operation is 0 (for sale) or 1 (for rent, monthly) and property_kind is 0 apartment, 1 house, 2 townhouse, 3 local/oficina, 4 galpón/depósito, 5 edificio or 6 terreno (sale only):

curl -sS -X POST https://pricepredai.interdataresearch.ai/predict \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"dataset":"venezuela","lat":10.496,"lon":-66.853,"operation":0,"property_kind":0,"area_m2":120,"beds":3,"baths":2,"age":15}'

Every Venezuela input the map shows is accepted here, all optional (GET /config?dataset=venezuela lists each one with its label, range, options and group):

• Main: operation, property_kind, area_m2 (15-2,000,000; land area for a terreno), beds, baths (0-30), age (0-120, blank = unknown), parking (0-10).
• Details: lot_m2 (0-50,000), floor (0-60), levels (1-6), half_baths (0-5); blank lot, floor or levels = unknown.
• Features: 44 yes/no flags, 1 or 0: new_build, remodeled, needs_work, penthouse, duplex, studio, quinta, ground_floor, pool, elevator, generator, water_tank, security, gated, gym, party_room, playground, sports, covered_parking, maletero, storage, solar, gas, service_room, furnished, terrace, balcony, garden, bbq, fireplace, ac, kitchen_fitted, laundry, closets, premium_finish, office, pet, view, mountain, beach, informal, urgent, documents_ok, investment.
• Quality (text scores): llm_condition, llm_finish_quality, llm_luxury, llm_location_quality (1-5); llm_view_quality, llm_renovation_cost_hint, llm_noise_or_risk, llm_seller_motivation (0-3); llm_extra_units (0-20).

Each market's model reads only its own inputs: rent skips the Quality scores; land uses area_m2, the flags water_tank, security, gated, view, mountain, beach, informal, urgent, documents_ok, investment and the Quality scores. Inputs a market doesn't use are dropped without an error.

The answer carries predicted_price, an interval (low, high, level), a confidence score and label, the comps it compared against and features_used (which inputs came from you and which from nearby listings). For Venezuela it also names the market (sale, rent or land) whose model priced it. Unknown input names are listed in ignored_inputs; out-of-range values answer 422.

Endpoints

Every path is relative to https://pricepredai.interdataresearch.ai. Auth: open = no token; user = a signed-in user (session cookie, or Authorization: Bearer with a session or API token) whose password does not need changing. The full schemas are in /docs; the share page lists every endpoint straight from the OpenAPI schema.

Errors use FastAPI's shape, {"detail": ...}: 401 not_authenticated or password_change_required, 403 for a rule you don't meet, 404, 409 for duplicates, 422 for invalid input and 429 after 10 failed logins in 15 minutes.

API tokens

There are two kinds of bearer token, and every protected endpoint accepts both:

• Session tokens come from POST /api/auth/login (7 days) and the map's Share API panel (30 days). They are signed, not stored; they stop working when you change your password.
• API tokens are opaque random strings you create for scripts and services. Only their SHA-256 digest is stored, so the token itself is shown once, at creation. A request is authenticated by looking that digest up. Each one has a name, an expiry (1-365 days, default 30) and a last-used time.

Create, list and revoke them on the Tokens page, or:

# create (needs any valid token or the session cookie)
curl -sS -X POST https://pricepredai.interdataresearch.ai/api/auth/tokens -H "Authorization: Bearer $SESSION" \
  -H 'Content-Type: application/json' -d '{"name":"nightly job","expires_in_days":90}'

# list: id, name, created_at, expires_at, last_used_at (never the token)
curl -sS https://pricepredai.interdataresearch.ai/api/auth/tokens -H "Authorization: Bearer $SESSION"

# revoke by id (204)
curl -sS -X DELETE https://pricepredai.interdataresearch.ai/api/auth/tokens/1 -H "Authorization: Bearer $SESSION"

POST /api/auth/logout with an API token as the bearer revokes that token. Changing your password revokes all of your API tokens, together with every older session.

Orgs, accounts & teams

Organizations let several accounts work together. The rules:

• Anyone signed in can create an org and becomes its owner and first admin. A user can belong to many orgs.
• Members can read the org, its member list and its teams.
• Admins (an org can have several) rename the org, create accounts for collaborators and create and fill teams.

Create an org, then an account for a colleague. username and password are optional: without a username it comes from the email, without a password a temporary 12-character one is generated, which must be changed at first sign-in. role is member (default) or admin:

curl -sS -X POST https://pricepredai.interdataresearch.ai/api/orgs -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"name":"Caracas brokers"}'

curl -sS -X POST https://pricepredai.interdataresearch.ai/api/orgs/1/accounts -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"email":"bob@example.com","role":"member"}'

The answer carries the username, the password (shown only this once), the login_url and a ready-to-send message; it is also emailed when Resend is configured (email_status). An email that already has an account answers 409. The new account is a member right away: its owner signs in with the username or the email and, with a temporary password, changes it on the Cuenta page (or with POST /api/auth/change-password) before anything else works.

Then an admin groups members in teams. Only members of the org can join its teams, and team names are unique per org:

curl -sS -X POST https://pricepredai.interdataresearch.ai/api/orgs/1/teams -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"name":"Valuations"}'

curl -sS -X POST https://pricepredai.interdataresearch.ai/api/orgs/1/teams/1/members -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"user_id":2}'

GET /api/me lists your orgs with your role in each.

Sharing the API

Two ways to hand the API to someone:

• The share page (/share): the base URL, a copy-and-paste curl session (register, log in, create a token, list datasets, predict) and the full endpoint table. It needs no login, so you can send the link as it is.
• The map's Share API panel (GET /api/share): when you're signed in, a POST /predict curl that already carries a fresh 30-day token for you. Treat that one like a password.

The base URL comes from the address the page was opened with, here https://pricepredai.interdataresearch.ai. api_client.py and api_example.sh in the project read a token from SUELO_CASA_TOKEN; an API token from the Tokens page works there too.