TripAdvisor APItripadvisor.com ↗

"""
TripAdvisor Parse API Client

A practical Python client for the TripAdvisor Scraper API that enables searching locations,
listing hotels with rich metadata, and retrieving place details.

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

import os
import requests
from typing import Optional, Dict, Any


class ParseClient:
    """Client for interacting with the TripAdvisor Scraper API via Parse."""

    def __init__(self, api_key: Optional[str] = None):
        """
        Initialize the Parse 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 = "f436cbcf-96a4-4f9e-85b0-3acad164fed6"
        self.api_key = api_key or os.getenv("PARSE_API_KEY")

        if not self.api_key:
            raise ValueError(
                "API key not provided. Set PARSE_API_KEY environment variable or pass api_key parameter."
            )

    def _call(self, endpoint: str, method: str = "POST", **params) -> Dict[str, Any]:
        """
        Make an API call to the Parse scraper.

        Args:
            endpoint: The endpoint name to call.
            method: HTTP method (GET or POST).
            **params: Parameters to send with the request.

        Returns:
            Response data as a dictionary.

        Raises:
            requests.RequestException: If the API request fails.
        """
        url = f"{self.base_url}/scraper/{self.scraper_id}/{endpoint}"
        headers = {
            "X-API-Key": self.api_key,
            "Content-Type": "application/json",
        }

        if method.upper() == "GET":
            response = requests.get(url, headers=headers, params=params)
        elif method.upper() == "POST":
            response = requests.post(url, headers=headers, json=params)
        else:
            raise ValueError(f"Unsupported HTTP method: {method}")

        response.raise_for_status()
        return response.json()

    def search_location(self, query: str) -> Dict[str, Any]:
        """
        Search for locations (cities, regions, hotels, attractions) to get their locationId.

        Args:
            query: Search keyword (e.g., 'London', 'Paris', 'New York City').

        Returns:
            Dictionary containing results array with location objects.
            Each location object contains: locationId, name, placeType, coordinates, etc.
        """
        return self._call("search_location", method="GET", query=query)

    def list_hotels(
        self, geo_id: int, limit: int = 30, offset: int = 0
    ) -> Dict[str, Any]:
        """
        List hotels in a specific location by geoId.

        Returns rich data including ratings, address, contact, and pricing.

        Args:
            geo_id: Location ID from search_location.
            limit: Number of results to return (default: 30).
            offset: Pagination offset (default: 0).

        Returns:
            Dictionary containing hotels array with hotel objects.
            Each hotel contains location data with name, rating, reviews, and contact info.
        """
        return self._call(
            "list_hotels", method="GET", geo_id=geo_id, limit=limit, offset=offset
        )

    def get_place_details(self, location_id: int) -> Dict[str, Any]:
        """
        Get special offers and basic metadata for a specific location ID.

        Args:
            location_id: Specific location/hotel ID.

        Returns:
            Dictionary containing special offer details for the location.
        """
        return self._call(
            "get_place_details", method="GET", location_id=location_id
        )


def main():
    """Practical workflow: Search for a city, list hotels, and get details for top results."""

    # Initialize the client
    client = ParseClient()

    # Step 1: Search for a destination
    print("=" * 70)
    print("STEP 1: SEARCHING FOR DESTINATIONS")
    print("=" * 70)

    query = "London"
    print(f"\nSearching for locations matching: '{query}'...\n")

    search_results = client.search_location(query)

    if not search_results.get("data", {}).get("results"):
        print(f"No results found for '{query}'")
        return

    locations = search_results["data"]["results"]
    total = search_results["data"].get("total", len(locations))
    print(f"Found {total} location(s):\n")

    for idx, location in enumerate(locations[:3], 1):
        location_id = location.get("locationId")
        name = location.get("name")
        place_type = location.get("placeType")
        address = location.get("address")
        latitude = location.get("latitude", "N/A")
        longitude = location.get("longitude", "N/A")
        parent_name = location.get("parentName", "N/A")

        print(f"{idx}. {name}")
        print(f"   Type: {place_type} | Location ID: {location_id}")
        print(f"   Address: {address}")
        print(f"   Parent: {parent_name}")
        print(f"   Coordinates: ({latitude}, {longitude})\n")

    # Step 2: Get the first city location and list hotels
    print("=" * 70)
    print("STEP 2: LISTING HOTELS")
    print("=" * 70)

    # Find a city type location for hotel listing
    city_location = None
    for location in locations:
        if location.get("placeType") == "CITY":
            city_location = location
            break

    if not city_location:
        city_location = locations[0]

    location_id = city_location.get("locationId")
    location_name = city_location.get("name")

    print(f"\nFetching hotels in {location_name}...\n")

    hotels_response = client.list_hotels(geo_id=int(location_id), limit=5)

    if not hotels_response.get("data", {}).get("hotels"):
        print(f"No hotels found in {location_name}")
        return

    hotels = hotels_response["data"]["hotels"]
    print(f"Found {hotels_response['data'].get('total', len(hotels))} hotels in {location_name}:\n")

    hotel_location_ids = []
    for idx, hotel in enumerate(hotels, 1):
        hotel_location_id = hotel.get("locationId")
        hotel_name = hotel.get("name")
        rating = hotel.get("rating", "N/A")
        review_count = hotel.get("reviewCount", 0)
        address_data = hotel.get("address", {})
        street = address_data.get("street", "N/A")
        city = address_data.get("city", "N/A")
        phone = hotel.get("telephone", "Not available")
        price_range = hotel.get("priceRange", "N/A")
        latitude = hotel.get("latitude", "N/A")
        longitude = hotel.get("longitude", "N/A")

        print(f"{idx}. {hotel_name}")
        print(f"   ⭐ Rating: {rating}/5.0 ({review_count} reviews)")
        print(f"   Address: {street}, {city}")
        print(f"   Phone: {phone}")
        print(f"   Price Range: {price_range}")
        print(f"   Coordinates: ({latitude}, {longitude})")
        print(f"   Location ID: {hotel_location_id}\n")

        if hotel_location_id:
            hotel_location_ids.append(hotel_location_id)

    # Step 3: Get special offers for top hotels
    print("=" * 70)
    print("STEP 3: FETCHING SPECIAL OFFERS")
    print("=" * 70)

    if hotel_location_ids:
        for hotel_id in hotel_location_ids[:3]:
            hotel_name = next(
                (h.get("name") for h in hotels if h.get("locationId") == hotel_id),
                f"Hotel {hotel_id}",
            )
            print(f"\nFetching special offers for: {hotel_name} (ID: {hotel_id})...")

            try:
                details = client.get_place_details(int(hotel_id))

                offers_data = details.get("data", {}).get(
                    "BaAggregation_getSpecialOfferDetailsBulk", []
                )
                if offers_data:
                    for offer_item in offers_data:
                        special_offers = offer_item.get("specialOffers", [])
                        if special_offers:
                            print(f"  ✓ Found {len(special_offers)} special offer(s):")
                            for offer in special_offers:
                                offer_id = offer.get("specialOfferId", "N/A")
                                print(f"    - Offer ID: {offer_id}")
                        else:
                            print("  ✗ No special offers currently available")
                else:
                    print("  ✗ No offer data available")

            except requests.exceptions.RequestException as e:
                print(f"  ✗ Error fetching details: {e}")

    # Summary
    print("\n" + "=" * 70)
    print("WORKFLOW SUMMARY")
    print("=" * 70)
    print(f"\nDestination searched: {query}")
    print(f"Selected city: {location_name}")
    print(f"Hotels retrieved: {len(hotels)}")
    print(f"Special offers checked: {min(3, len(hotel_location_ids))} hotels")
    print("\nTop hotel recommendations:")

    for idx, hotel in enumerate(hotels[:3], 1):
        hotel_name = hotel.get("name")
        rating = hotel.get("rating", "N/A")
        review_count = hotel.get("reviewCount", 0)

        print(f"  {idx}. {hotel_name}")
        print(f"     ⭐ {rating}/5.0 ({review_count} reviews)\n")


if __name__ == "__main__":
    main()