Skip to main content

​
Overview

The Advanced Search API provides powerful filtering capabilities for searching housing listings based on tags (amenities) and star ratings. This endpoint enables users to find accommodations that match their specific requirements.
This endpoint does not require authentication and is publicly accessible for searching available housing.

​
Search Houses

Search for housing listings with optional filters for tags and minimum star rating. 
curl -X GET "https://localhost:8443/v1/api/query?tags=beach,pool&stars=4"

​
Query Parameters

​
tags
string
Comma-separated list of tags to filter by (e.g., ‘beach,pool,wifi’). Tag names are case-insensitive and will be trimmed of whitespace.Example values:
  • beach
  • pool,wifi
  • beach,pool,gym,spa
​
stars
integer
Minimum star rating to filter by (1-5). Only houses with this rating or higher will be returned.Valid values: 1, 2, 3, 4, 5
Both parameters are optional. If neither is provided, all houses will be returned.

​
Response

​
houses
array
Array of HousingDTO objects matching the search criteria
[
  {
    "code": 1,
    "location": "Barcelona, Spain",
    "name": "Hotel Mediterranean",
    "price": 150,
    "description": "Beautiful beachfront hotel with modern amenities",
    "stars": 4,
    "acepted": true,
    "tags": [
      { "id": "pool" },
      { "id": "wifi" },
      { "id": "beach" }
    ]
  },
  {
    "code": 5,
    "location": "Marbella, Spain",
    "name": "Coastal Paradise Resort",
    "price": 220,
    "description": "Luxury beachfront resort with infinity pool",
    "stars": 5,
    "acepted": true,
    "tags": [
      { "id": "pool" },
      { "id": "beach" },
      { "id": "spa" },
      { "id": "restaurant" }
    ]
  }
]

[
  {
    "code": 5,
    "location": "Marbella, Spain",
    "name": "Coastal Paradise Resort",
    "price": 220,
    "description": "Luxury beachfront resort with infinity pool",
    "stars": 5,
    "acepted": true,
    "tags": [
      { "id": "pool" },
      { "id": "beach" },
      { "id": "spa" }
    ]
  },
  {
    "code": 7,
    "location": "Madrid, Spain",
    "name": "Grand Hotel Madrid",
    "price": 180,
    "description": "5-star luxury in the heart of Madrid",
    "stars": 5,
    "acepted": true,
    "tags": [
      { "id": "gym" },
      { "id": "wifi" },
      { "id": "restaurant" }
    ]
  }
]

​
Status Codes

CodeDescription
200Successfully retrieved filtered houses
500Internal server error

​
Search Examples

​
Find Beachfront Hotels

Search for all hotels with beach access: 
curl -X GET "https://localhost:8443/v1/api/query?tags=beach"

​
Find Luxury Hotels (4+ Stars)

Search for high-end accommodations: 
curl -X GET "https://localhost:8443/v1/api/query?stars=4"

​
Find Luxury Beachfront Hotels with Pool

Combine multiple filters for specific requirements: 
curl -X GET "https://localhost:8443/v1/api/query?tags=beach,pool&stars=4"

​
Find Budget Hotels with WiFi

Search for affordable options with internet access: 
curl -X GET "https://localhost:8443/v1/api/query?tags=wifi&stars=2"

​
Available Tags

Common tags used in the Trippins platform for filtering:

beach

Beach access or beachfront location

pool

Swimming pool facility

wifi

WiFi internet access

parking

Parking facilities

gym

Fitness center or gym

spa

Spa and wellness facilities

restaurant

On-site restaurant

bar

Bar or lounge

pets

Pet-friendly accommodation

breakfast

Breakfast included

airport

Airport shuttle service

balcony

Private balcony or terrace

​
Search Logic

​
Tag Filtering

The tag filter uses an OR logic by default:
  • Houses matching any of the specified tags will be returned
  • Tags are processed as lowercase and trimmed
  • Empty or null tag parameter returns all houses
Example: 
?tags=beach,pool
Returns houses with either a beach tag OR a pool tag (or both).

​
Star Rating Filtering

The star filter uses a minimum threshold:
  • Only houses with stars >= specified value are returned
  • Valid values are 1-5
Example: 
?stars=4
Returns houses with 4 or 5 stars.

​
Combined Filters

When both filters are applied, houses must satisfy both conditions:
  • Must have at least one of the specified tags AND
  • Must meet the minimum star rating
Example: 
?tags=beach,pool&stars=4
Returns 4+ star houses that have beach OR pool (or both).

​
Implementation Details

The search endpoint is implemented in the AdvancedSearchRestController class: Endpoint: GET /v1/api/query Processing Steps:
  1. Parse the comma-separated tags string
  2. Convert tags to lowercase and trim whitespace
  3. Query the database using HousingService.findHousesByTagsAndStars()
  4. Return matching houses as JSON
Source code reference:
  • Controller: /controller/AdvancedSearchRestController.java:74-100
  • Service method: HousingService.findHousesByTagsAndStars(Set<String> tags, Integer stars)

​
Pagination Support

For paginated housing results, use the AJAX endpoints:

​
Get Paginated Houses

This endpoint returns paginated accepted houses and is useful for infinite scroll implementations.
​
page
integer
Page number (0-based, default: 0)
​
size
integer
Number of items per page (default: 6)
curl -X GET "https://localhost:8443/v1/api/rooms/extra?page=0&size=6"
Response: 
{
  "content": [ /* array of Housing objects */ ],
  "pageable": {
    "pageNumber": 0,
    "pageSize": 6,
    "offset": 0
  },
  "totalPages": 5,
  "totalElements": 28,
  "last": false,
  "first": true
}

​
Error Handling

​
Error Response Format

​
error
string
Error type (e.g., “Search failed”)
​
message
string
Detailed error message describing what went wrong
{
  "error": "Search failed",
  "message": "Invalid star rating. Must be between 1 and 5."
}

​
Common Errors

ScenarioStatus CodeError Message
Database connection failure500”Search failed - Database error”
Invalid star value (< 1 or > 5)500”Invalid star rating. Must be between 1 and 5.”
Malformed request400”Bad Request - Invalid parameters”

​
Performance Tips

For Optimal Performance:
  • Be specific with tag filters to reduce result set size
  • Use pagination for large result sets
  • Cache frequently used search queries on the client side
  • Consider implementing debouncing for real-time search inputs
  • Use the acepted: true filter to show only approved listings

​
Use Cases

Filter by Amenities

Allow users to find hotels with specific features like pools, gyms, or beach access

Quality Filtering

Enable users to filter by minimum star rating for quality assurance

Vacation Planner

Help users find perfect vacation spots with desired amenities

Business Travel

Find accommodations with business-friendly amenities like WiFi and parking

Build docs developers (and LLMs) love

Get started for freeTalk to us