npm package: @sharpapi/sharpapi-node-tours-activities-categories
Description: SharpAPI.com Node.js SDK for generating tours and activities product categories
Author: Dawid Makowski
Latest version: 1.0.1

![SharpAPI GitHub cover](https://sharpapi.com/sharpapi-github-php-bg.jpg "SharpAPI Node.js Client")

# Tours & Activities Categorization API for Node.js

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

[![npm version](https://img.shields.io/npm/v/@sharpapi/sharpapi-node-tours-activities-categories.svg)](https://www.npmjs.com/package/@sharpapi/sharpapi-node-tours-activities-categories)
[![License](https://img.shields.io/npm/l/@sharpapi/sharpapi-node-tours-activities-categories.svg)](https://github.com/sharpapi/sharpapi-node-client/blob/master/LICENSE.md)

**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

1. [Requirements](#requirements)
2. [Installation](#installation)
3. [Usage](#usage)
4. [API Documentation](#api-documentation)
5. [Response Format](#response-format)
6. [Examples](#examples)
7. [License](#license)

---

## Requirements

- Node.js >= 16.x
- npm or yarn

---

## Installation

### Step 1. Install the package via npm:

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

### Step 2. Get your API key

Visit [SharpAPI.com](https://sharpapi.com/) to get your API key.

---

## Usage

```javascript
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<string>: Status URL for polling the job result

---

## Response Format

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

```json
{
  "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

```javascript
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

```javascript
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

```javascript
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

```javascript
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:
- [Postman Documentation](https://documenter.getpostman.com/view/31106842/2sBXVeGsVh)
- [Product Page](https://sharpapi.com/en/catalog/ai/travel-tourism-hospitality/tours-activities-product-categorization)

---

## Related Packages

- [@sharpapi/sharpapi-node-hospitality-categories](https://www.npmjs.com/package/@sharpapi/sharpapi-node-hospitality-categories) - Hospitality categorization
- [@sharpapi/sharpapi-node-travel-review-sentiment](https://www.npmjs.com/package/@sharpapi/sharpapi-node-travel-review-sentiment) - Review sentiment
- [@sharpapi/sharpapi-node-product-categories](https://www.npmjs.com/package/@sharpapi/sharpapi-node-product-categories) - General product categorization
- [@sharpapi/sharpapi-node-client](https://www.npmjs.com/package/@sharpapi/sharpapi-node-client) - Full SharpAPI SDK

---

## License

This project is licensed under the MIT License. See the [LICENSE.md](LICENSE.md) file for details.

---

## Support

- **Documentation**: [SharpAPI.com Documentation](https://sharpapi.com/documentation)
- **Issues**: [GitHub Issues](https://github.com/sharpapi/sharpapi-node-client/issues)
- **Email**: contact@sharpapi.com

---

**Powered by [SharpAPI](https://sharpapi.com/) - AI-Powered API Workflow Automation**