> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oyester.metaphy.live/llms.txt
> Use this file to discover all available pages before exploring further.

# Destinations Tool

> Discover spiritual destinations from the curated database

# Destinations Tool (`search-destinations`)

Searches for spiritual destinations from a curated database of temples, monasteries, shrines, and sacred sites worldwide.

## Overview

The destinations tool provides access to a comprehensive database of spiritual locations, allowing users to discover places for pilgrimage, meditation, prayer, and spiritual exploration based on various criteria.

## Input Schema

<ParamField body="search" type="string">
  Search term for destination name, description, or location.
</ParamField>

<ParamField body="category" type="string">
  Filter by category: `"temple"`, `"monastery"`, `"shrine"`, `"sacred-site"`.
</ParamField>

<ParamField body="faith" type="string">
  Filter by faith/religion: `"buddhist"`, `"hindu"`, `"christian"`, `"islamic"`, etc.
</ParamField>

<ParamField body="purpose" type="string">
  Filter by purpose: `"pilgrimage"`, `"meditation"`, `"prayer"`, `"healing"`.
</ParamField>

<ParamField body="emotion" type="string">
  Filter by emotional experience: `"peaceful"`, `"awe-inspiring"`, `"serene"`, `"mystical"`.
</ParamField>

<ParamField body="limit" type="number" default="10">
  Maximum number of destinations to return (max: 20).
</ParamField>

## Output Schema

<ResponseField name="destinations" type="Array">
  Array of destination objects matching the search criteria.
</ResponseField>

<ResponseField name="destinations[].id" type="string">
  Unique destination identifier.
</ResponseField>

<ResponseField name="destinations[].name" type="string">
  Destination name.
</ResponseField>

<ResponseField name="destinations[].slug" type="string">
  URL-friendly identifier.
</ResponseField>

<ResponseField name="destinations[].description" type="string">
  Detailed description of the destination.
</ResponseField>

<ResponseField name="destinations[].category" type="string">
  Category: `"temple"`, `"monastery"`, `"shrine"`, `"sacred-site"`.
</ResponseField>

<ResponseField name="destinations[].faith" type="string">
  Associated faith/religion.
</ResponseField>

<ResponseField name="destinations[].purpose" type="string">
  Primary purpose of the destination.
</ResponseField>

<ResponseField name="destinations[].location" type="object">
  Location information including city, region, country, and coordinates.
</ResponseField>

<ResponseField name="destinations[].emotionTags" type="string[]">
  Emotional experience tags.
</ResponseField>

<ResponseField name="destinations[].highlights" type="string[]">
  Key highlights and features.
</ResponseField>

<ResponseField name="totalFound" type="number">
  Number of destinations returned.
</ResponseField>

<ResponseField name="searchCriteria" type="object">
  Echo of search parameters used.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable result summary.
</ResponseField>

## Example Usage

### Search by Location and Faith

```json theme={null}
{
  "toolCallId": "call_destinations_123",
  "toolName": "search-destinations",
  "args": {
    "search": "temples in India",
    "faith": "buddhist",
    "limit": 5
  }
}
```

### Tool Result

```json theme={null}
{
  "destinations": [
    {
      "id": "dest-123",
      "name": "Bodh Gaya",
      "slug": "bodh-gaya",
      "description": "The site where the Buddha attained enlightenment under the Bodhi tree. A place of profound spiritual significance for Buddhists worldwide.",
      "category": "temple",
      "faith": "buddhist",
      "purpose": "pilgrimage",
      "location": {
        "city": "Bodh Gaya",
        "region": "Bihar",
        "country": "India",
        "coordinates": {
          "lat": 24.6951,
          "lng": 84.9916
        }
      },
      "emotionTags": ["peaceful", "awe-inspiring", "serene"],
      "highlights": [
        "Mahabodhi Temple",
        "Bodhi Tree",
        "Monastic university"
      ]
    }
  ],
  "totalFound": 1,
  "searchCriteria": {
    "search": "temples in India",
    "faith": "buddhist",
    "limit": 5
  },
  "message": "Found 1 spiritual destination"
}
```

## Natural Language Triggers

The tool responds to various destination-related queries:

* "Find Buddhist temples in Japan"
* "Show me peaceful meditation spots in Thailand"
* "Where can I go for a spiritual pilgrimage?"
* "Recommend sacred sites for inner peace"
* "Find Hindu temples near Kyoto"
* "Places for mindful walking"

## Integration Examples

### Destination Discovery App

```javascript theme={null}
class SpiritualDestinationFinder {
  constructor(chat) {
    this.chat = chat;
    this.destinations = [];
  }

  async findDestinations(criteria) {
    const query = this.buildSearchQuery(criteria);
    const response = await this.chat.sendMessage(query, 'wanderer');

    return this.extractDestinationsFromResponse(response);
  }

  buildSearchQuery(criteria) {
    const { location, faith, purpose, emotion, category } = criteria;

    let query = "Find spiritual destinations";

    if (location) query += ` in ${location}`;
    if (faith) query += ` for ${faith} practitioners`;
    if (purpose) query += ` for ${purpose}`;
    if (emotion) query += ` that feel ${emotion}`;
    if (category) query += ` with ${category} category`;

    return query + ".";
  }

  extractDestinationsFromResponse(response) {
    const toolResults = response.toolResults || [];
    const destinationResult = toolResults.find(r => r.toolName === 'search-destinations');

    if (destinationResult) {
      this.destinations = destinationResult.result.destinations;
      return destinationResult.result;
    }

    return { destinations: [], totalFound: 0 };
  }

  async getDestinationDetails(destinationId) {
    const destination = this.destinations.find(d => d.id === destinationId);
    if (!destination) return null;

    // Get more details or plan a visit
    const query = `Tell me more about ${destination.name} and how to visit it.`;
    const response = await this.chat.sendMessage(query, 'wanderer');

    return {
      ...destination,
      detailedInfo: response.text
    };
  }
}

// Usage
const finder = new SpiritualDestinationFinder(chat);

const results = await finder.findDestinations({
  location: 'Japan',
  faith: 'buddhist',
  purpose: 'meditation'
});

console.log('Found destinations:', results.destinations);
```

### Meditation Journey Planner

```javascript theme={null}
class MeditationJourneyPlanner {
  constructor(chat) {
    this.chat = chat;
  }

  async planMeditationJourney(origin, preferences) {
    const { duration, focus, experience } = preferences;

    // Find suitable destinations
    const destinations = await this.findMeditationDestinations(origin, preferences);

    // Plan the journey
    const journey = await this.createJourneyPlan(destinations, preferences);

    return journey;
  }

  async findMeditationDestinations(origin, preferences) {
    const query = `Find meditation destinations within ${preferences.distance || 500}km of ${origin} for ${preferences.experience || 'beginner'} practitioners focusing on ${preferences.focus || 'mindfulness'}.`;

    const response = await this.chat.sendMessage(query, 'wanderer');
    const toolResults = response.toolResults || [];
    const destinationResult = toolResults.find(r => r.toolName === 'search-destinations');

    return destinationResult ? destinationResult.result.destinations : [];
  }

  async createJourneyPlan(destinations, preferences) {
    if (destinations.length === 0) {
      return { message: 'No suitable destinations found', destinations: [] };
    }

    const plan = {
      title: `${preferences.focus || 'Meditation'} Journey`,
      duration: preferences.duration || '1 week',
      destinations: destinations.slice(0, 3), // Limit to 3 destinations
      itinerary: await this.generateItinerary(destinations, preferences)
    };

    return plan;
  }

  async generateItinerary(destinations, preferences) {
    const destinationNames = destinations.map(d => d.name).join(', ');
    const query = `Create a ${preferences.duration || 'week-long'} meditation itinerary visiting: ${destinationNames}. Focus on ${preferences.focus || 'mindfulness'} practices.`;

    const response = await this.chat.sendMessage(query, 'wanderer');
    return response.text;
  }
}

// Usage
const planner = new MeditationJourneyPlanner(chat);

const journey = await planner.planMeditationJourney('Tokyo', {
  duration: '10 days',
  focus: 'zen meditation',
  experience: 'intermediate',
  distance: 300
});

console.log('Meditation Journey Plan:', journey);
```

### Map Integration

```javascript theme={null}
class DestinationMap {
  constructor(mapElement) {
    this.map = this.initializeMap(mapElement);
    this.markers = [];
  }

  displayDestinations(destinations) {
    this.clearMarkers();

    destinations.forEach(destination => {
      const marker = this.createMarker(destination);
      this.markers.push(marker);
    });

    this.fitMapToMarkers();
  }

  createMarker(destination) {
    const { location } = destination;
    const position = {
      lat: location.coordinates.lat,
      lng: location.coordinates.lng
    };

    const marker = new google.maps.Marker({
      position,
      title: destination.name,
      map: this.map
    });

    const infoWindow = new google.maps.InfoWindow({
      content: this.createInfoWindowContent(destination)
    });

    marker.addListener('click', () => {
      infoWindow.open(this.map, marker);
    });

    return marker;
  }

  createInfoWindowContent(destination) {
    return `
      <div class="destination-info">
        <h3>${destination.name}</h3>
        <p class="location">${destination.location.city}, ${destination.location.country}</p>
        <p class="description">${destination.description}</p>
        <div class="tags">
          ${destination.emotionTags?.map(tag => `<span class="tag">${tag}</span>`).join('') || ''}
        </div>
        <button onclick="planVisit('${destination.id}')">Plan Visit</button>
      </div>
    `;
  }

  clearMarkers() {
    this.markers.forEach(marker => marker.setMap(null));
    this.markers = [];
  }

  fitMapToMarkers() {
    if (this.markers.length === 0) return;

    const bounds = new google.maps.LatLngBounds();
    this.markers.forEach(marker => {
      bounds.extend(marker.getPosition());
    });

    this.map.fitBounds(bounds);
  }
}

// Usage
const destinationMap = new DestinationMap(document.getElementById('map'));

// When destinations are found
function displayDestinationsOnMap(destinations) {
  destinationMap.displayDestinations(destinations);
}
```

## Best Practices

<Tip>
  **Specific Search Terms**: Use specific location names and faith traditions for better results.
</Tip>

<Tip>
  **Combine Filters**: Use multiple filters (faith + purpose + emotion) for refined results.
</Tip>

<Tip>
  **Pagination**: Use the limit parameter to control result size for better UX.
</Tip>

<Tip>
  **Caching**: Cache destination data for frequently searched locations.
</Tip>

## Error Handling

```javascript theme={null}
async function searchDestinationsWithFallback(searchCriteria) {
  try {
    const response = await chat.sendMessage(
      `Find spiritual destinations matching: ${JSON.stringify(searchCriteria)}`,
      'wanderer'
    );

    const destinations = extractDestinationsFromResponse(response);
    if (destinations && destinations.length > 0) {
      return destinations;
    } else {
      throw new Error('No destinations found');
    }
  } catch (error) {
    console.warn('Destination search failed, using fallback');
    // Implement fallback search or cached data
    return await searchLocalDestinations(searchCriteria);
  }
}
```

## Use Cases

* **Pilgrimage Planning**: Find sacred sites for spiritual journeys
* **Meditation Retreats**: Discover peaceful locations for meditation
* **Cultural Exploration**: Learn about different faith traditions and locations
* **Wellness Travel**: Combine spiritual travel with wellness goals
* **Educational Tours**: Plan visits to historically significant spiritual sites