@sharpapi/sharpapi-node-tours-activities-categories

v1.0.1

Published

4 months ago

SharpAPI.com Node.js SDK for generating tours and activities product categories

SharpAPI GitHub cover

Tours & Activities Categorization API for Node.js

🎭 Automatically categorize tours and activities with AI — powered by SharpAPI.

SharpAPI Tours & Activities Categorization uses AI to automatically categorize tours, excursions, activities, and experiences based on their descriptions. Perfect for travel platforms, tour operators, and activity booking systems.

📋 Table of Contents

Requirements

Node.js >= 16.x
npm or yarn

Installation

Step 1. Install the package via npm:

npm install @sharpapi/sharpapi-node-tours-activities-categories

Step 2. Get your API key

Visit SharpAPI.com to get your API key.

Usage

const { SharpApiToursActivitiesCategoriesService } = require('@sharpapi/sharpapi-node-tours-activities-categories');

const apiKey = process.env.SHARP_API_KEY;
const service = new SharpApiToursActivitiesCategoriesService(apiKey);

const activityDescription = `
Full-day wine tasting tour through Napa Valley. Visit 4 premium wineries,
enjoy gourmet lunch, and learn about wine-making process from expert sommeliers.
Small group experience with hotel pickup included.
`;

async function categorizeActivity() {
  try {
    const statusUrl = await service.categorizeProduct(activityDescription);
    console.log('Job submitted. Status URL:', statusUrl);

    const result = await service.fetchResults(statusUrl);
    console.log('Categories:', result.getResultJson());
  } catch (error) {
    console.error('Error:', error.message);
  }
}

categorizeActivity();

API Documentation

Methods

`categorizeProduct(activityDescription: string, maxCategories?: number): Promise<string>`

Categorizes a tour or activity based on its description.

Parameters:

activityDescription (string, required): The tour/activity description to categorize
maxCategories (number, optional): Maximum number of categories to return (default: 5)

Returns:

Promise: Status URL for polling the job result

Response Format

The API returns categories with relevance scores (weight: 0-10):

{
  "categories": [
    {
      "name": "Food & Wine Tours",
      "weight": 10,
      "subcategories": ["Wine Tasting", "Culinary Experience", "Gourmet Tours"]
    },
    {
      "name": "Cultural Tours",
      "weight": 8,
      "subcategories": ["Educational", "Small Group"]
    },
    {
      "name": "Day Tours",
      "weight": 9,
      "subcategories": ["Full-Day Experience", "Guided Tour"]
    }
  ]
}

Weight Scale:

10: Perfect match
8-9: Highly relevant
6-7: Moderately relevant
4-5: Somewhat relevant
1-3: Slightly relevant

Examples

Basic Activity Categorization

const { SharpApiToursActivitiesCategoriesService } = require('@sharpapi/sharpapi-node-tours-activities-categories');

const service = new SharpApiToursActivitiesCategoriesService(process.env.SHARP_API_KEY);

const activity = 'Guided snorkeling adventure with sea turtles. Equipment and lunch included.';

service.categorizeProduct(activity)
  .then(statusUrl => service.fetchResults(statusUrl))
  .then(result => {
    const categories = result.getResultJson();
    console.log('🎯 Activity Categories:');
    categories.forEach((cat, index) => {
      console.log(`${index + 1}. ${cat.name} (relevance: ${cat.weight}/10)`);
      if (cat.subcategories) {
        console.log(`   Types: ${cat.subcategories.join(', ')}`);
      }
    });
  })
  .catch(error => console.error('Categorization failed:', error));

Batch Tour Categorization

const service = new SharpApiToursActivitiesCategoriesService(process.env.SHARP_API_KEY);

const tours = [
  'City walking tour of historical landmarks with professional guide',
  'Sunset sailing cruise with champagne and appetizers',
  'Mountain hiking adventure with experienced trail guide',
  'Cooking class: Learn to make authentic Italian pasta'
];

async function categorizeAllTours(tours) {
  const categorized = await Promise.all(
    tours.map(async (tour) => {
      const statusUrl = await service.categorizeProduct(tour, 3);
      const result = await service.fetchResults(statusUrl);
      const categories = result.getResultJson();

      return {
        tour,
        primary: categories[0]?.name,
        categories: categories.map(c => c.name),
        tags: categories.flatMap(c => c.subcategories || [])
      };
    })
  );

  return categorized;
}

const results = await categorizeAllTours(tours);
results.forEach(r => {
  console.log(`\n${r.tour}`);
  console.log(`Primary: ${r.primary}`);
  console.log(`Tags: ${r.tags.join(', ')}`);
});

Booking Platform Integration

const service = new SharpApiToursActivitiesCategoriesService(process.env.SHARP_API_KEY);

async function enrichActivityListing(activity) {
  const fullDescription = `
    ${activity.title}
    ${activity.description}
    Duration: ${activity.duration}
    Included: ${activity.included.join(', ')}
  `;

  const statusUrl = await service.categorizeProduct(fullDescription);
  const result = await service.fetchResults(statusUrl);
  const categories = result.getResultJson();

  // Extract primary categories
  const primaryCategories = categories
    .filter(cat => cat.weight >= 7)
    .map(cat => cat.name);

  // Build search tags
  const searchTags = [
    ...primaryCategories,
    ...categories.flatMap(c => c.subcategories || [])
  ].filter((tag, index, self) => self.indexOf(tag) === index);

  return {
    ...activity,
    categories: primaryCategories,
    tags: searchTags,
    searchable: searchTags.join(' ').toLowerCase(),
    featured_badge: categories[0]?.weight === 10 ? categories[0].name : null
  };
}

const activity = {
  id: 'ACT-789',
  title: 'Zip Line Canopy Tour',
  description: 'Thrilling adventure through rainforest canopy',
  duration: '3 hours',
  included: ['Safety equipment', 'Guide', 'Photos']
};

const enriched = await enrichActivityListing(activity);
console.log('Enriched activity:', enriched);

Smart Activity Recommendations

const service = new SharpApiToursActivitiesCategoriesService(process.env.SHARP_API_KEY);

async function findSimilarActivities(referenceActivity, allActivities) {
  // Categorize reference activity
  const refStatusUrl = await service.categorizeProduct(referenceActivity);
  const refResult = await service.fetchResults(refStatusUrl);
  const refCategories = refResult.getResultJson();

  const refCategoryNames = refCategories.map(c => c.name);

  // Categorize all other activities and find matches
  const scored = [];
  for (const activity of allActivities) {
    const statusUrl = await service.categorizeProduct(activity.description);
    const result = await service.fetchResults(statusUrl);
    const categories = result.getResultJson();

    const activityCategories = categories.map(c => c.name);
    const overlap = activityCategories.filter(c => refCategoryNames.includes(c));
    const similarityScore = overlap.length / refCategoryNames.length;

    if (similarityScore > 0) {
      scored.push({
        ...activity,
        similarityScore,
        sharedCategories: overlap
      });
    }
  }

  return scored.sort((a, b) => b.similarityScore - a.similarityScore);
}

const reference = 'Scuba diving with certified instructors';
const otherActivities = [
  { id: 1, description: 'Snorkeling tour in coral reef' },
  { id: 2, description: 'Museum guided tour' },
  { id: 3, description: 'Deep sea fishing adventure' }
];

const similar = await findSimilarActivities(reference, otherActivities);
console.log('Similar activities:', similar);

Use Cases

Tour Booking Platforms: Auto-categorize activity listings
Travel Marketplaces: Organize experiences by category
Search & Filtering: Enable category-based activity search
Recommendation Systems: Suggest similar activities
Content Organization: Tag and classify tour content
Dynamic Pricing: Group activities for pricing strategies
Marketing Campaigns: Target specific activity categories

Activity Categories

The system recognizes various activity types:

Adventure & Outdoor:

Water Sports
Mountain Activities
Extreme Sports
Wildlife Encounters
Nature Tours

Cultural & Educational:

Historical Tours
Museum Visits
Cooking Classes
Language Learning
Art Workshops

Food & Drink:

Wine Tasting
Food Tours
Culinary Classes
Brewery Tours
Coffee Experiences

Entertainment:

Shows & Performances
Nightlife Tours
Music Events
Festival Access
Theme Parks

Wellness & Relaxation:

Spa Experiences
Yoga Retreats
Meditation Sessions
Hot Springs
Wellness Tours

Transportation & Sightseeing:

City Tours
Hop-On Hop-Off
Scenic Drives
Boat Cruises
Helicopter Tours

API Endpoint

POST /tth/ta_product_categories

For detailed API specifications, refer to:

Related Packages

@sharpapi/sharpapi-node-hospitality-categories - Hospitality categorization
@sharpapi/sharpapi-node-travel-review-sentiment - Review sentiment
@sharpapi/sharpapi-node-product-categories - General product categorization
@sharpapi/sharpapi-node-client - Full SharpAPI SDK

License

This project is licensed under the MIT License. See the LICENSE.md file for details.

Support

Documentation: SharpAPI.com Documentation
Issues: GitHub Issues
Email: [email protected]