Skip to main content
POST
/
api
/
b2a
/
recommend
Recommend
curl --request POST \
  --url https://api.privetag.com/api/b2a/recommend \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "user_profile": {
    "travel_type": "<string>",
    "nationality": "<string>",
    "interests": [
      "<string>"
    ],
    "budget": "<string>",
    "age_group": "<string>"
  },
  "location": {
    "city": "<string>",
    "lat": 123,
    "lon": 123,
    "hotel_id": "<string>"
  },
  "filters": {
    "is_indoor": true,
    "difficulty": "<string>",
    "max_price": 123,
    "categories": [
      "<string>"
    ]
  },
  "limit": 123,
  "include_flash_deals": true
}
'
{
  "success": true,
  "data": {
    "recommendations": [
      {
        "id": "<string>",
        "title": "<string>",
        "description": "<string>",
        "category": "<string>",
        "price": 123,
        "currency": "<string>",
        "relevance_score": 123,
        "recommendation_reason": "<string>",
        "is_flash_deal": true,
        "original_price": 123,
        "images": [
          "<string>"
        ]
      }
    ],
    "context": {
      "log_id": "<string>",
      "user_profile_summary": "<string>",
      "environment_summary": "<string>"
    }
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.privetag.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Get Recommendations

This endpoint returns activities ranked by Ground Truth data - real user behavior, not assumptions.

​
Use This Endpoint When

User asks about activities

  • “What should we do today?”
  • “Any family activities nearby?”
  • “Things to do in Bangkok”

Context-aware needs

  • “It’s raining, what’s good?”
  • “Romantic dinner for tonight”
  • “Kid-friendly activities”

​
Request

​
user_profile
object
required
User preferences and characteristics
​
location
object
required
User’s current or target location
​
filters
object
Additional filtering options
​
limit
number
default:"10"
Maximum number of recommendations (1-20)
​
include_flash_deals
boolean
default:"true"
Include same-day flash deals (30-50% off)

​
Response

​
success
boolean
Whether the request was successful
​
data
object

​
Examples

​
Family Trip in Bangkok

curl -X POST https://api.privetag.com/api/b2a/recommend \
  -H "x-api-key: pk_a1b2c3..." \
  -H "Content-Type: application/json" \
  -d '{
    "user_profile": {
      "travel_type": "family",
      "interests": ["theme-park", "zoo", "aquarium"]
    },
    "location": {
      "city": "Bangkok",
      "lat": 13.7563,
      "lon": 100.5018
    },
    "filters": {
      "difficulty": "easy"
    },
    "limit": 5
  }'

​
Rainy Day Recommendations

When lat/lon is provided, the API automatically fetches weather data: 
{
  "user_profile": {
    "travel_type": "couple"
  },
  "location": {
    "lat": 7.8804,
    "lon": 98.3923
  },
  "filters": {
    "is_indoor": true
  }
}

​
Response Example

{
  "success": true,
  "data": {
    "recommendations": [
      {
        "id": "act_abc123",
        "title": "Safari World Bangkok",
        "description": "World-class zoo with safari and marine park",
        "category": "zoo",
        "price": 1500,
        "currency": "THB",
        "relevance_score": 95,
        "recommendation_reason": "Perfect for families - interactive animal experiences",
        "is_flash_deal": false,
        "images": ["https://cdn.privetag.com/activities/safari-world-1.jpg"]
      },
      {
        "id": "act_def456",
        "title": "Dream World Theme Park",
        "description": "Exciting rides and attractions for all ages",
        "category": "theme-park",
        "price": 1200,
        "currency": "THB",
        "relevance_score": 92,
        "recommendation_reason": "Family-friendly theme park with easy rides",
        "is_flash_deal": true,
        "original_price": 1800
      }
    ],
    "context": {
      "log_id": "ctx_xyz789",
      "user_profile_summary": "family, interested in theme-park, zoo, aquarium",
      "environment_summary": "Bangkok, sunny, 32°C, afternoon"
    }
  }
}

​
Relevance Score Factors

The relevance_score (0-100) is calculated from:
FactorWeightDescription
User Profile Match30%How well activity matches travel_type and interests
Ground Truth Data25%Real visit data from similar user profiles
Weather Appropriateness20%Indoor/outdoor suitability for current weather
Time Appropriateness15%Activity timing (morning activity, dinner spot, etc.)
Price Match10%Budget alignment
Ground Truth Advantage: Our recommendations improve over time as we collect more NFC-verified visit data. The more your users book and visit, the better the recommendations become.

​
Error Responses

CodeDescription
INVALID_LOCATIONCity not found or coordinates out of service area
INVALID_PROFILEMissing required user_profile fields
NO_ACTIVITIESNo activities found matching criteria

​
Next Steps

Execute Booking

Once user selects an activity, execute the booking