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

package/README.md

@@ -0,0 +1,386 @@
+![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**

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@sharpapi/sharpapi-node-tours-activities-categories",
+  "version": "1.0.0",
+  "description": "SharpAPI.com Node.js SDK for generating tours and activities product categories",
+  "main": "src/index.js",
+  "scripts": {
+    "test": "jest"
+  },
+  "keywords": [
+    "sharpapi",
+    "ai-powered",
+    "ai capabilities",
+    "api",
+    "ai api",
+    "api integration",
+    "artificial intelligence",
+    "natural language processing",
+    "restful api",
+    "nodejs",
+    "software development",
+    "travel",
+    "tourism",
+    "tours",
+    "activities",
+    "product categories"
+  ],
+  "author": "Dawid Makowski <contact@sharpapi.com>",
+  "license": "MIT",
+  "dependencies": {
+    "@sharpapi/sharpapi-node-core": "file:../sharpapi-node-core"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sharpapi/sharpapi-node-tours-activities-categories.git"
+  }
+}

package/src/SharpApiToursActivitiesCategoriesService.js

@@ -0,0 +1,36 @@
+const { SharpApiCoreService, SharpApiJobTypeEnum } = require('@sharpapi/sharpapi-node-core');
+
+/**
+ * Service for generating tours and activities product categories using SharpAPI.com
+ */
+class SharpApiToursActivitiesCategoriesService extends SharpApiCoreService {
+  /**
+   * Generates a list of suitable categories for the Tours & Activities product
+   * with relevance weights as float value (1.0-10.0) where 10 equals 100%, the highest relevance score.
+   * Provide the product name and its parameters to get the best category matches possible.
+   * Comes in handy with populating product catalogue data and bulk product processing.
+   *
+   * @param {string} productName
+   * @param {string|null} city
+   * @param {string|null} country
+   * @param {string|null} language
+   * @param {number|null} maxQuantity
+   * @param {string|null} voiceTone
+   * @param {string|null} context
+   * @returns {Promise<string>} - The status URL.
+   */
+  async toursAndActivitiesProductCategories(productName, city = null, country = null, language = null, maxQuantity = null, voiceTone = null, context = null) {
+    const data = { content: productName };
+    if (city) data.city = city;
+    if (country) data.country = country;
+    if (language) data.language = language;
+    if (maxQuantity) data.max_quantity = maxQuantity;
+    if (voiceTone) data.voice_tone = voiceTone;
+    if (context) data.context = context;
+
+    const response = await this.makeRequest('POST', SharpApiJobTypeEnum.TTH_TA_PRODUCT_CATEGORIES.url, data);
+    return this.parseStatusUrl(response);
+  }
+}
+
+module.exports = { SharpApiToursActivitiesCategoriesService };

package/src/index.js

@@ -0,0 +1,6 @@
+// sharpapi-node-tours-activities-categories/src/index.js
+const { SharpApiToursActivitiesCategoriesService } = require('./SharpApiToursActivitiesCategoriesService');
+
+module.exports = {
+  SharpApiToursActivitiesCategoriesService,
+};