Overview The Matching API provides intelligent recommendations by analyzing user profiles, preferences, languages, expertise areas, and locations to suggest the best matches between tourists and guides.
Get Recommended Guides for Tourist curl -X GET "https://api.kinconecta.com/api/matching/tourist/123/guides?limit=10&offset=0" \ -H "Authorization: Bearer YOUR_TOKEN"
Endpoint GET /api/matching/tourist/{touristUserId}/guides
Path Parameters The unique identifier of the tourist user requesting guide recommendations
Query Parameters Maximum number of recommended guides to return (pagination)
Number of results to skip for pagination
Response List of recommended guide matches with scoring details Show MatchResultDTO properties
The user ID of the recommended guide
Matching algorithm score (0-100) indicating compatibility
Detailed breakdown of matched criteria Show MatchedFieldDTO properties
Name of the matched field (e.g., “language”, “interest”, “location”)
Specific value that matched (e.g., “Spanish”, “Hiking”, “Madrid”)
Points contributed to the overall match score
Quick profile summary of the guide Show ProfilePreviewDTO properties
URL to the guide’s profile picture
URL to the guide’s cover photo
Primary location where the guide operates
Average rating from previous reviews
Total number of reviews received
Total number of potential guide matches available
The limit value used in this query
The offset value used in this query
Example Response { "results" : [ { "candidateUserId" : 456 , "score" : 87.5 , "matchedFields" : [ { "field" : "language" , "evidence" : "Spanish" , "points" : 25.0 }, { "field" : "interest" , "evidence" : "Cultural Tours" , "points" : 20.0 }, { "field" : "location" , "evidence" : "Barcelona" , "points" : 30.0 }, { "field" : "expertise" , "evidence" : "Art & Museums" , "points" : 12.5 } ], "profilePreview" : { "fullName" : "Carlos Rodriguez" , "avatarUrl" : "https://cdn.kinconecta.com/avatars/456.jpg" , "coverUrl" : "https://cdn.kinconecta.com/covers/456.jpg" , "locationLabel" : "Barcelona, Spain" , "rating" : 4.8 , "reviewsCount" : 127 } } ], "totalCandidates" : 45 , "limit" : 10 , "offset" : 0 }
Get Recommended Tourists for Guide curl -X GET "https://api.kinconecta.com/api/matching/guide/456/tourists?limit=10&offset=0" \ -H "Authorization: Bearer YOUR_TOKEN"
Endpoint GET /api/matching/guide/{guideUserId}/tourists
Path Parameters The unique identifier of the guide user requesting tourist recommendations
Query Parameters Maximum number of recommended tourists to return (pagination)
Number of results to skip for pagination
Response The response structure is identical to the tourist endpoint, but returns tourist matches instead of guide matches.
List of recommended tourist matches with scoring details. See the tourist endpoint above for detailed field descriptions.
Total number of potential tourist matches available
The limit value used in this query
The offset value used in this query
Example Response { "results" : [ { "candidateUserId" : 789 , "score" : 92.0 , "matchedFields" : [ { "field" : "language" , "evidence" : "English" , "points" : 25.0 }, { "field" : "interest" , "evidence" : "Adventure Sports" , "points" : 30.0 }, { "field" : "location" , "evidence" : "Madrid" , "points" : 27.0 }, { "field" : "adaptation" , "evidence" : "Wheelchair Accessible" , "points" : 10.0 } ], "profilePreview" : { "fullName" : "Sarah Johnson" , "avatarUrl" : "https://cdn.kinconecta.com/avatars/789.jpg" , "coverUrl" : "https://cdn.kinconecta.com/covers/789.jpg" , "locationLabel" : "New York, USA" , "rating" : null , "reviewsCount" : 0 } } ], "totalCandidates" : 23 , "limit" : 10 , "offset" : 0 }
Matching Algorithm The matching algorithm analyzes multiple factors to calculate compatibility scores:
Scoring Factors
Languages (up to 25 points): Matches between tourist language preferences and guide spoken languagesInterests & Expertise (up to 30 points): Alignment between tourist interests and guide expertise areasLocation (up to 30 points): Geographic proximity and location preferencesAdaptations (up to 15 points): Special accessibility needs and guide capabilities
Score Interpretation
90-100 : Excellent match - Highly recommended75-89 : Very good match - Strong compatibility60-74 : Good match - Solid potentialBelow 60 : Moderate match - Consider other options