Culture Trip APIculturetrip.com ↗

"""
Culture Trip API Client
Get your API key from: https://parse.bot/settings

Practical example: Discover travel destinations, read articles, and find bookable trips.
"""

import os
import requests
from typing import Optional
from urllib.parse import urlparse


class ParseClient:
    """Client for Culture Trip API via Parse Bot."""

    def __init__(self, api_key: Optional[str] = None):
        """Initialize the Parse API client.
        
        Args:
            api_key: API key for authentication. If not provided, reads from PARSE_API_KEY env var.
        """
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "baadb9bd-2400-44f7-905e-69a16378a62a"
        self.api_key = api_key or os.getenv("PARSE_API_KEY")
        if not self.api_key:
            raise ValueError("API key must be provided or set in PARSE_API_KEY environment variable")

    def _call(self, endpoint: str, method: str = "POST", **params) -> dict:
        """Make an API call to the Parse Bot scraper.
        
        Args:
            endpoint: The endpoint name (e.g., 'get_articles_by_destination')
            method: HTTP method - 'GET' or 'POST'
            **params: Parameters to send with the request
            
        Returns:
            Response JSON as dictionary
        """
        url = f"{self.base_url}/scraper/{self.scraper_id}/{endpoint}"
        headers = {
            "X-API-Key": self.api_key,
            "Content-Type": "application/json"
        }

        try:
            if method.upper() == "GET":
                response = requests.get(url, headers=headers, params=params)
            else:  # POST
                response = requests.post(url, headers=headers, json=params)
            
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            print(f"API Error: {e}")
            raise

    def search_trips(self, query: str) -> dict:
        """Search for travel locations and get suggestions.
        
        Args:
            query: Search keyword (e.g., London, Kyoto)
            
        Returns:
            Dictionary with suggestions list
        """
        return self._call("search_trips", method="GET", query=query)

    def list_destinations_by_region(self, region: str) -> dict:
        """List countries and cities within a specific region.
        
        Args:
            region: Region slug (e.g., asia, europe, south-america)
            
        Returns:
            Dictionary with destinations list
        """
        return self._call("list_destinations_by_region", method="GET", region=region)

    def get_articles_by_destination(self, destination_path: str) -> dict:
        """Retrieve a list of travel articles for a specific destination path.
        
        Args:
            destination_path: The URL path of the destination (e.g., /asia/japan/tokyo)
            
        Returns:
            Dictionary with articles list
        """
        return self._call("get_articles_by_destination", method="GET", destination_path=destination_path)

    def get_article_detail(self, article_path: str) -> dict:
        """Retrieve full details of a specific article including curated attractions.
        
        Args:
            article_path: The URL path of the article
            
        Returns:
            Dictionary with article details including title, content, author, attractions
        """
        return self._call("get_article_detail", method="GET", article_path=article_path)

    def list_trips(self, destination: Optional[str] = None) -> dict:
        """List bookable trips for a given destination.
        
        Args:
            destination: Destination slug (e.g., japan, anywhere)
            
        Returns:
            Dictionary with trips list
        """
        params = {}
        if destination:
            params["destination"] = destination
        return self._call("list_trips", method="GET", **params)

    def get_trip_dates_and_prices(self, trip_url: str) -> dict:
        """Get pricing information for a specific trip.
        
        Args:
            trip_url: Full URL of the trip page
            
        Returns:
            Dictionary with trip details including tour_id, price, currency
        """
        return self._call("get_trip_dates_and_prices", method="GET", trip_url=trip_url)

    def get_popular_cities(self) -> dict:
        """Get popular cities highlighted on the site.
        
        Returns:
            Dictionary with popular cities list
        """
        return self._call("get_popular_cities", method="GET")


def extract_path_from_url(url: str) -> str:
    """Extract the path component from a full URL."""
    parsed = urlparse(url)
    return parsed.path


def main():
    """Practical workflow: Discover destination, read articles, find and price trips."""
    
    client = ParseClient()
    
    print("\n" + "=" * 70)
    print("CULTURE TRIP TRAVEL DISCOVERY TOOL")
    print("=" * 70)
    
    # Step 1: Get popular cities to start exploration
    print("\n[1] Fetching popular cities from the homepage...")
    try:
        popular = client.get_popular_cities()
        if popular.get("data", {}).get("cities"):
            cities = popular["data"]["cities"]
            print(f"✓ Found {len(cities)} popular cities")
            for idx, city in enumerate(cities[:3], 1):
                print(f"   {idx}. {city['name']}")
    except Exception as e:
        print(f"✗ Error fetching popular cities: {e}")
        return
    
    # Step 2: Search for a specific destination
    search_query = "Kyoto"
    print(f"\n[2] Searching for '{search_query}'...")
    try:
        search_results = client.search_trips(search_query)
        suggestions = search_results.get("data", {}).get("suggestions", [])
        print(f"✓ Found {len(suggestions)} search suggestions")
        for idx, sugg in enumerate(suggestions[:3], 1):
            print(f"   {idx}. {sugg['displayName']} ({sugg['type']})")
        
        if not suggestions:
            print("✗ No suggestions found, cannot continue")
            return
        
        # Select the first suggestion (usually the most specific match)
        selected = suggestions[0]
        destination_url = selected["url"]
        destination_name = selected["displayName"]
        print(f"\n→ Selected: {destination_name}")
        
    except Exception as e:
        print(f"✗ Error searching: {e}")
        return
    
    # Step 3: Get articles for the selected destination
    print(f"\n[3] Fetching travel articles for {destination_name}...")
    try:
        articles_response = client.get_articles_by_destination(destination_url)
        articles = articles_response.get("data", {}).get("articles", [])
        print(f"✓ Found {len(articles)} articles")
        
        if not articles:
            print("✗ No articles found")
            return
        
        # Step 4: Get detailed information for each article
        print(f"\n[4] Reading article details (showing first 2)...")
        article_details_list = []
        
        for idx, article in enumerate(articles[:2], 1):
            print(f"\n   Article {idx}: {article['title']}")
            print(f"   Category: {article['category']}")
            
            try:
                # Extract path from full URL
                article_path = extract_path_from_url(article["url"])
                detail_response = client.get_article_detail(article_path)
                detail_data = detail_response.get("data", {})
                
                if detail_data:
                    article_details_list.append(detail_data)
                    
                    if detail_data.get("author"):
                        print(f"   Author: {detail_data['author']}")
                    
                    if detail_data.get("publish_date"):
                        print(f"   Published: {detail_data['publish_date']}")
                    
                    if detail_data.get("content"):
                        preview = detail_data["content"][:120].strip() + "..."
                        print(f"   Preview: {preview}")
                    
                    # List featured attractions
                    attractions = detail_data.get("attractions", [])
                    if attractions:
                        print(f"   Featured attractions ({len(attractions)} total):")
                        for att_idx, attraction in enumerate(attractions[:2], 1):
                            print(f"      • {attraction['name']}")
                
            except Exception as e:
                print(f"   ⚠ Could not fetch full article details: {e}")
        
    except Exception as e:
        print(f"✗ Error fetching articles: {e}")
        return
    
    # Step 5: Find bookable trips for the destination
    print(f"\n[5] Searching for bookable trips...")
    try:
        trips_response = client.list_trips("japan")
        trips = trips_response.get("data", {}).get("trips", [])
        print(f"✓ Found {len(trips)} available trips")
        
        if not trips:
            print("   No trips available")
        else:
            # Step 6: Get detailed pricing for each trip
            print(f"\n[6] Getting pricing details (showing first 2)...")
            
            for idx, trip in enumerate(trips[:2], 1):
                print(f"\n   Trip {idx}: {trip['name']}")
                print(f"   Base Price: {trip['price']}")
                print(f"   Duration: {trip['duration']}")
                
                try:
                    pricing_response = client.get_trip_dates_and_prices(trip["url"])
                    pricing_data = pricing_response.get("data", {})
                    
                    if pricing_data:
                        price = pricing_data.get("price", "N/A")
                        currency = pricing_data.get("currency", "USD")
                        tour_id = pricing_data.get("tour_id", "N/A")
                        
                        print(f"   Exact Price: {price} {currency}")
                        print(f"   Tour ID: {tour_id}")
                
                except Exception as e:
                    print(f"   ⚠ Could not fetch pricing: {e}")
    
    except Exception as e:
        print(f"✗ Error fetching trips: {e}")
    
    # Step 7: Explore other destinations by region
    print(f"\n[7] Exploring other destinations in Asia...")
    try:
        region_response = client.list_destinations_by_region("asia")
        destinations = region_response.get("data", {}).get("destinations", [])
        print(f"✓ Found {len(destinations)} destinations in Asia:")
        
        for idx, dest in enumerate(destinations[:5], 1):
            print(f"   {idx}. {dest['name']}")
    
    except Exception as e:
        print(f"✗ Error fetching region data: {e}")
    
    print("\n" + "=" * 70)
    print("EXPLORATION COMPLETE")
    print("=" * 70 + "\n")


if __name__ == "__main__":
    main()