Skip to main content

​
Matching Algorithm

Kin Conecta’s matching algorithm is the core system that connects tourists with compatible local guides based on a comprehensive compatibility analysis. The system calculates match scores from 0 to 100, analyzing multiple dimensions of travel preferences and guide expertise.
The matching algorithm is based on a proprietary study conducted by the Bugbusters team analyzing compatibility factors including experience expectations, pace, interests, and logistics.

​
How It Works

The matching system evaluates candidate profiles and generates recommendations sorted by compatibility score.
1

Profile Analysis

The system analyzes the tourist’s or guide’s profile, extracting key preferences including languages, interests, travel style, group preferences, transport options, and accessibility needs.
2

Candidate Evaluation

For each potential match, the algorithm calculates a compatibility score by comparing profile attributes across multiple weighted categories.
3

Score Calculation

Points are awarded based on matches in different categories, with each category contributing to a maximum score of 100 points.
4

Results Ranking

Candidates are sorted by score (descending), then by number of matched fields, ensuring the best matches appear first.

​
Scoring Categories

The algorithm evaluates compatibility across these weighted categories:

Languages

25 points maximumMatching spoken languages between tourist and guide. Essential for effective communication during tours.

Interests & Expertise

20 points maximumAlignment between tourist interests and guide expertise areas (culture, gastronomy, nature, adventure, etc.).

Pace & Intensity

15 points maximumMatching tour intensity and activity levels (relaxed, moderate, high-energy).

Group Preference

10 points maximumCompatibility in preferred group sizes (solo, couple, small groups, large groups).

Transport

8 points maximumMatching transport preferences and offerings (walking, metro, car, etc.).

Travel Style

8 points maximumAlignment of guide style with tourist travel preferences (cultural, gastronomic, adventure, etc.).

Photo Preferences

6 points maximumMatching photography styles and preferences during tours.

Accessibility

6 points maximumCompatibility of accessibility needs with guide adaptations and accommodations.

Planning Level

2 points maximumMatching planning and logistics preferences.

Additional Notes Bonus

0-2 pointsBonus points for keyword matches in additional notes (safe keywords only).

​
API Endpoints

The matching service exposes two primary endpoints: 
GET /api/matching/tourist/{touristUserId}/guides?limit=10&offset=0
Returns a paginated list of compatible guides for a specific tourist. 
GET /api/matching/guide/{guideUserId}/tourists?limit=10&offset=0
Returns a paginated list of compatible tourists for a specific guide.

​
Response Structure

The matching API returns detailed compatibility information: 
{
  "results": [
    {
      "candidateUserId": 21,
      "score": 67.5,
      "matchedFields": [
        {
          "field": "Idiomas",
          "evidence": "español, english",
          "points": 16.67
        },
        {
          "field": "Intereses/Experiencia",
          "evidence": "cultura, gastronomía",
          "points": 10.0
        }
      ],
      "profilePreview": {
        "fullName": "Ana Torres",
        "avatarUrl": "https://...",
        "coverUrl": "https://...",
        "locationLabel": "CDMX Centro",
        "rating": 4.8,
        "reviewsCount": 24
      }
    }
  ],
  "totalCandidates": 54,
  "limit": 10,
  "offset": 0
}

​
Response Fields

The unique user ID of the recommended guide or tourist.
Compatibility score from 0-100, calculated based on profile matching across all categories.
Array of compatibility factors that contributed points, including:
  • field: Category name (e.g., “Idiomas”, “Intereses”)
  • evidence: Specific matched values
  • points: Points contributed by this category
Quick profile information for display in UI:
  • fullName: User’s full name
  • avatarUrl: Profile picture URL
  • coverUrl: Cover image URL
  • locationLabel: Location description
  • rating: Average rating (guides only)
  • reviewsCount: Number of reviews (guides only)
Total number of matching candidates available (for pagination).

​
Implementation Details

The matching system is implemented in the MatchingService class located at: 
socialNetwork/src/main/java/org/generation/socialNetwork/matching/service/MatchingService.java

​
Key Features

Pagination Support

Results are paginated with configurable limit (default: 20, max: 100) and offset parameters.

Bi-directional Matching

System supports both tourist-to-guide and guide-to-tourist recommendations.

Self-Exclusion

Automatically filters out the requesting user from their own recommendations.

Active Profiles Only

Only matches active, complete profiles for quality recommendations.
The scoring engine uses a MatchingScoringEngine component that can be customized or extended to adjust compatibility weights based on real-world usage data.

​
User Experience

From a user perspective, the matching algorithm enables:
  1. Personalized Recommendations: Users see potential matches ranked by compatibility
  2. Transparency: Each recommendation shows which factors contributed to the match
  3. Discovery: Users can explore diverse profiles while prioritizing best matches
  4. Efficiency: Reduces time spent searching by surfacing most compatible profiles first
The matching algorithm requires complete profiles to work effectively. Users with incomplete profiles may receive fewer or lower-quality recommendations.

​
Future Enhancements

Planned improvements to the matching system include:
  • Machine learning integration to improve score accuracy based on successful matches
  • Location-based distance scoring
  • Availability and scheduling compatibility
  • Price range matching
  • Historical interaction patterns
  • User feedback integration to refine recommendations

Related Documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us