Houses Endpoints
List Houses
File: api/houses.php
Method: POST
Auth: Optional JWT (enhances results with group filters)
The main property listing endpoint. Returns all active houses for a city, sorted by relevance.
| Param | Type | Description |
|---|---|---|
jwt | string | Optional user JWT |
city | string | City name |
commute | int | Commute preference score (UK) |
inTheMix | int | In The Mix preference score (UK) |
housrHub | int | Housr Hub preference score (UK) |
seshOrStudy | int | Sesh Or Study preference score (UK) |
priceRange | string | "min,max" price range |
houseCapacity | string | "min,max" bedroom range |
bathrooms | int | Minimum bathrooms |
housr_plus | string | "only", "include", or null (exclude) |
uobApprovedOnly | bool | UoB approved agents only (UK, Birmingham) |
distanceFromCampus | int | Max distance from campus in miles (US) |
Filtering Logic:
- Active houses only (
status=1,deleted_at IS NULL,lat/lng not null) - Available units (
number_available IS NULL OR number_available > 0) - City-scoped
- Price range: UK uses
price_pw(adjusts for bills), US usesprice_pm - Bedroom range
- Housr Plus filtering (only/include/exclude)
- UoB approved filtering (UK, Birmingham only)
- Property operator restriction (US, non-student users)
Sort Order:
- Boost credits (descending, if enabled via feature flag)
- Housr Plus order (if applicable)
- UK: Preference points (commute/inTheMix/housrHub/seshOrStudy scoring), then tier, then priority, then random
- US: Distance from campus (if filter set), then priority, then random
UK Equalisation: The first 30 results are equalised across landlords using a round-robin tier system to prevent any single agent from dominating the listing.
Response: { "property_data": [...] } with house objects including images, pricing, trending status, Housr Plus flag.
Search Houses
File: api/searchHouses.php
Method: POST
Auth: Required JWT
| Param | Type | Description |
|---|---|---|
jwt | string | User JWT |
input | string | Search text |
offset | int | Pagination offset |
Searches houses by title, description, address (and building_name in US) using LIKE queries. Returns 5 results at a time. Uses prepared statements. Results ordered by title/address match first, then by like count.
Get House Details
File: api/getHouse.php
Method: POST
Auth: Optional JWT
| Param | Type | Description |
|---|---|---|
jwt | string | Optional user JWT |
house_id | string | House ID |
academic_year | string | Academic year for lease terms (US) |
Returns full property details including:
- Property data (title, description, address, images, pricing)
- Agent information (name, email, image, verification status)
- Like count and friend likes (if authenticated)
- Viewing request status (if authenticated)
- Video tour link
- Map highlights (nearby universities and points of interest with proximity)
- US-specific: Building details, property operator phone, amenities, lease terms by academic year, agent rating, promotions, image room labels
- UK-specific: Housr rating, garden, large communal space, recently renovated, bookable viewing slots
Like House
File: api/like.php
Method: POST
Auth: Required JWT
Adds a house to the user’s liked list.
Remove Liked House
File: api/removeLikedHouse.php
Method: POST
Auth: Required JWT
Removes a house from the user’s liked list.
Get User Liked Houses
File: api/getUserLikedHouses.php
Method: POST
Auth: Required JWT
Returns all houses liked by the authenticated user.
Liked Houses
File: api/liked.php
Method: POST
Auth: Required JWT
Returns liked house data (alternative endpoint).
House Likes
File: api/houseLikes.php
Method: POST
Returns like data for a specific house.
Dislike
File: api/dislike.php
Method: POST
Auth: Required JWT
Records a dislike (user dismissed the house).
Clear Dislikes
File: api/clearDislikes.php
Method: POST
Auth: Required JWT
Clears all dislike records for a user.
Disliked
File: api/disliked.php
Method: POST
Auth: Required JWT
Returns disliked house IDs.
House Viewed
File: api/houseViewed.php
Method: POST
Tracks that a user viewed a house (used for trending calculation).
Featured House
File: api/featuredHouse.php
Method: POST
Returns the featured house for a city.
Get Top Picks
File: api/getTopPicks.php
Method: POST
Returns top pick houses.
Cumulative House Prices
File: api/cumulativeHousePrices.php
Method: POST
Returns cumulative pricing data.
Save User House Filters
File: api/saveUserHouseFilters.php
Method: POST
Auth: Required JWT
Saves the user’s house search filter preferences.
Cities
File: api/cities.php
Method: GET/POST
Auth: None
Returns the list of available cities.
Universities
File: api/universities.php
Method: GET/POST
Returns the list of universities.
Buildings (US)
File: api/buildings.php
Method: POST
Returns building details for US properties.