Search & Filters

The search and filtering system enables users to discover guides, tours, and experiences that match their specific interests and requirements. Combined with the intelligent matching algorithm, these tools help tourists find their ideal local guide quickly and efficiently.

The search system works alongside the matching algorithm: while matching recommends compatible profiles, search allows users to actively explore based on their criteria.

System Overview

Kin Conecta provides multiple discovery methods to help users find what they’re looking for:

Location-Based Search

Find guides and tours in specific cities, states, or regions across Mexico.

Category Filtering

Filter by interest categories like culture, gastronomy, nature, adventure, and more.

Tour Search

Browse available tour packages by destination, price, duration, and group size.

Guide Discovery

Search for guides by expertise, language, rating, experience level, and availability.

Search Types

The platform supports different search approaches depending on what users need:

1. Guide Search

Find local guides based on multiple criteria:

Location

Primary filter: Select city or state where you need a guide (CDMX, Guadalajara, Oaxaca, etc.).

Expertise & Interests

Filter by guide expertise areas that match your interests:

Culture: Museums, historical sites, architecture
Gastronomy: Food tours, cooking classes, market visits
Nature: Parks, beaches, eco-tourism
Adventure: Hiking, diving, extreme sports
Art: Galleries, street art, artisan workshops

Languages

Filter guides by spoken languages (Spanish, English, French, German, etc.).

Additional Filters

Refine results by:

Rating: Minimum star rating (4+, 4.5+, etc.)
Experience Level: Beginner-friendly, intermediate, expert
Group Size: Solo, couples, small groups, large groups
Price Range: Budget, moderate, premium
Certifications: Official tourism certifications

2. Tour Search

Browse pre-packaged tour offerings:

{
  "tourId": 789,
  "title": "Tour Gastronómico CDMX: Mercados y Taquerías",
  "description": "Explora la auténtica gastronomía mexicana...",
  "guideId": 12,
  "categoryId": 2,
  "location": "CDMX Centro",
  "price": 850.00,
  "currency": "MXN",
  "durationHours": 4.0,
  "maxGroupSize": 8,
  "ratingAvg": 4.8,
  "bookingsCount": 156,
  "coverImage": "https://..."
}

Search Criteria:

Destination

Filter tours by city, neighborhood, or specific landmarks.

Price Range

Set minimum and maximum price to fit your budget.

Duration

Filter by tour length: half-day, full-day, multi-day experiences.

Group Size

Find tours that accommodate your party size (max group size).

Rating

Show only highly-rated tours (4+ stars, 4.5+ stars).

Availability

Filter by available dates and times.

Special Features

Tours with food included, transportation, photography, etc.

3. Combined Search

The most powerful approach combines both guide and tour filtering:

Start with Matching: Get personalized recommendations
Apply Location Filter: Narrow to specific destinations
Add Interest Filters: Focus on preferred activities
Refine Results: Use additional filters for perfect match

Filter Implementation

Filters are implemented based on profile and tour attributes:

Guide Profile Filters

Based on GuideProfileEntity fields:

// Location
locationLabel: "CDMX Centro"
locations: Set<GuideLocationEntity>

// Languages
languages: Set<LanguageEntity> // español, english, français

// Expertise Areas
expertiseAreas: Set<GuideExpertiseAreaEntity> // cultura, gastronomía, etc.

// Experience & Style
experienceLevel: "Expert" // Beginner, Intermediate, Expert
style: "Cultural" // Cultural, Adventure, Relaxed

// Group & Logistics
groupSize: "Small groups (2-6)" // Solo-friendly, Couples, Small, Large
tourIntensity: "Moderate" // Low, Moderate, High
transportOffered: "Walking + Metro"

// Trust Signals
ratingAvg: 4.8
reviewsCount: 24
certifications: Set<GuideCertificationEntity>

// Accessibility
adaptations: Set<GuideAdaptationEntity>

Tourist Profile Filters

When guides search for compatible tourists:

// Location
location: "CDMX"

// Languages
languages: Set<LanguageEntity>

// Interests
interests: Set<InterestEntity>

// Travel Preferences
travelStyle: "Cultural" // Cultural, Adventure, Gastronomic
tripType: "City break" // Weekend, Week-long, Extended
paceAndCompany: "Moderate pace"
activityLevel: "Moderate"

// Group Dynamics
groupPreference: "Small groups"

// Special Needs
accessibility: "Wheelchair accessible"
dietaryPreferences: "Vegetarian"

Tour Filters

Based on Tour entity:

// Basic Info
title: String
description: Text
categoryId: Integer

// Location (through TourDestinations)
tourDestinations: List<TourDestinations>

// Pricing & Logistics
price: BigDecimal
currency: "MXN"
durationHours: BigDecimal
maxGroupSize: Short

// Trust & Popularity
ratingAvg: BigDecimal
bookingsCount: Integer

// Status
status: ENUM('active', 'inactive', 'pending')

Search UI/UX

The search interface provides an intuitive discovery experience:

Search Bar

Prominent search input for keywords, location, or guide names.

Filter Panel

Collapsible sidebar or modal with all filter options organized by category.

Results Grid

Card-based layout showing guide profiles or tour packages with key information.

Sort Options

Dropdown to sort results by:

Relevance (default)
Rating (high to low)
Price (low to high / high to low)
Popularity (most bookings)
Newest (recently added)

Active Filters Display

Show currently applied filters as removable tags above results.

Implementation Architecture

Backend Query Building

Search queries are built dynamically based on applied filters:

public List<GuideProfile> searchGuides(
    String location,
    Set<String> languages,
    Set<String> expertiseAreas,
    BigDecimal minRating,
    String experienceLevel,
    String groupSize,
    BigDecimal minPrice,
    BigDecimal maxPrice
) {
    // Build dynamic query with JPA Criteria API or QueryDSL
    // Apply filters only if provided
    // Return filtered and sorted results
}

Service Layer

The TourService handles tour searches:

socialNetwork/src/main/java/org/generation/socialNetwork/tours/service/TourService.java

Key methods:

getAllTours(): Retrieve all active tours
getTourById(Long id): Get specific tour details
Additional filtering methods (to be implemented)

For optimal performance, implement database indexes on frequently filtered fields like location, categoryId, ratingAvg, and price.

Search Optimization

Indexing Strategy

-- Guide search optimization
CREATE INDEX idx_guide_location ON guide_profiles(location_label);
CREATE INDEX idx_guide_rating ON guide_profiles(rating_avg DESC);
CREATE INDEX idx_guide_active ON guide_profiles(user_id) WHERE account_status = 'active';

-- Tour search optimization
CREATE INDEX idx_tour_category ON tours(category_id);
CREATE INDEX idx_tour_price ON tours(price);
CREATE INDEX idx_tour_rating ON tours(rating_avg DESC);
CREATE INDEX idx_tour_active ON tours(status) WHERE status = 'active';

-- Full-text search
CREATE FULLTEXT INDEX idx_tour_search ON tours(title, description);

Caching

Cache frequently accessed filter options:

List of locations (cities/states)
Available categories
Language options
Popular search queries

User Experience Flow

Start Search

User enters a keyword or selects a location to begin their search.

View Initial Results

System displays relevant results sorted by relevance or matching score.

Apply Filters

User refines results using filter panel (interests, price, rating, etc.).

Browse Results

User scrolls through filtered results, viewing guide/tour cards with key information.

View Details

Clicking a card opens detailed profile/tour page with full information.

Compare Options

User can bookmark favorites or open multiple tabs to compare options.

Take Action

User messages guide, requests booking, or adds tour to favorites.

Search + Matching Integration

The search system complements the matching algorithm:

Matching First

Start with personalized recommendations from the matching algorithm, then refine with search filters.

Search First

Browse guides/tours using search, then see compatibility scores from matching algorithm in results.

Hybrid Approach

Mix matched and searched results, showing high-compatibility matches first followed by broader search results.

Learning System

Search behavior informs matching algorithm to improve future recommendations.

Best Practices

For Tourists

Start Broad

Begin with general criteria (location, category) then narrow down with additional filters.

Use Matching

Check recommended matches before searching broadly - you might find perfect matches.

Read Reviews

Don’t rely solely on filters - read reviews to understand guide quality and style.

Save Favorites

Bookmark interesting profiles to compare later before making a decision.

For Implementation

Always filter out inactive or deleted profiles/tours
Implement pagination for large result sets (don’t load thousands at once)
Provide feedback when no results match criteria (suggest relaxing filters)
Log popular search terms to improve categories and matching

API Examples

Search Guides

GET /api/guides/search?
  location=CDMX&
  languages=español,english&
  expertiseAreas=cultura,gastronomía&
  minRating=4.0&
  limit=20&
  offset=0

Search Tours

GET /api/tours/search?
  categoryId=2&
  minPrice=500&
  maxPrice=1500&
  minRating=4.5&
  maxGroupSize=8&
  sortBy=rating&
  limit=20&
  offset=0

Combined Search

GET /api/search?
  q=gastronomía+CDMX&
  type=all&
  filters=rating:4+,price:500-1500&
  limit=20

Future Enhancements

Planned improvements to search and filtering:

Smart Search: Natural language queries (“Find a food tour guide in Mexico City under $50”)
Autocomplete: Suggest locations, categories, and guides as user types
Search History: Save recent searches for quick access
Saved Filters: Create and save custom filter combinations
Map View: Display results on an interactive map
Advanced Filters: Date ranges, specific amenities, accessibility features
Faceted Search: Show count of results for each filter option
Similar Results: “More like this” recommendations based on viewed profiles
AI-Powered: Machine learning to understand intent and improve relevance
Voice Search: Speak search queries instead of typing

Overview

For Tourists

For Guides

Features

​Search & Filters

​System Overview

Location-Based Search

Category Filtering

Tour Search

Guide Discovery

​Search Types

​1. Guide Search

​2. Tour Search

Destination

Category

Price Range

Duration

Group Size

Rating

Availability

Special Features

​3. Combined Search

​Filter Implementation

​Guide Profile Filters

​Tourist Profile Filters

​Tour Filters

​Search UI/UX

​Implementation Architecture

​Backend Query Building

​Service Layer

​Search Optimization

​Indexing Strategy

​Caching

​User Experience Flow

​Search + Matching Integration

Matching First

Search First

Hybrid Approach

Learning System

​Best Practices

​For Tourists

Start Broad

Use Matching

Read Reviews

Save Favorites

​For Implementation

​API Examples

​Search Guides

​Search Tours

​Combined Search

​Future Enhancements

Related Documentation

Build docs developers (and LLMs) love

Search & Filters

System Overview

Search Types

1. Guide Search

2. Tour Search

3. Combined Search

Filter Implementation

Guide Profile Filters

Tourist Profile Filters

Tour Filters

Search UI/UX

Implementation Architecture

Backend Query Building

Service Layer

Search Optimization

Indexing Strategy

Caching

User Experience Flow

Search + Matching Integration

Best Practices

For Tourists

For Implementation

API Examples

Search Guides

Search Tours

Combined Search

Future Enhancements