Costco APIcostco.com ↗

"""
Costco API - Usage Example

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


class ParseClient:
    """Client for Costco API."""

    def __init__(self, api_key=None):
        self.api_key = api_key or os.getenv("PARSE_API_KEY")
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "1802ebc9-74ad-4148-ab24-013ecb147fa5"

    def _call(self, endpoint, method="POST", **params):
        """Make API call."""
        url = f"{self.base_url}/scraper/{self.scraper_id}/{endpoint}"
        headers = {
            "X-API-Key": self.api_key,
            "Content-Type": "application/json",
        }
        payload = dict(params)
        if method.upper() == "GET":
            response = requests.get(url, headers=headers, params=payload)
        else:
            response = requests.post(url, headers=headers, json=payload)
        response.raise_for_status()
        data = response.json()
        return data

    def search_products(self, query, rows=None, start=None, sort_by=None):
        """Search for products by keyword with pagination and sorting. Returns product listings with pricing, ratings, images, and availability information."""
        return self._call("search_products", method="GET", query=query, rows=rows, start=start, sort_by=sort_by)

    def get_category_listing(self, category_path, rows=None, start=None):
        """Browse products within a specific category path. Returns paginated product listings for a given category URL path."""
        return self._call("get_category_listing", method="GET", category_path=category_path, rows=rows, start=start)

    def get_product_details(self, item_numbers):
        """Get detailed product information including price, descriptions, attributes, and ratings via GraphQL. Accepts one or more item numbers from search results."""
        return self._call("get_product_details", method="POST", item_numbers=item_numbers)

    def get_product_reviews(self, product_id, limit=None, offset=None):
        """Get member reviews for a specific product. Uses the Costco catalog product ID (group_id from search results), not the item_number."""
        return self._call("get_product_reviews", method="GET", product_id=product_id, limit=limit, offset=offset)

    def get_warehouse_locations(self, latitude=None, longitude=None, limit=None):
        """Find Costco warehouse locations near a specific latitude and longitude. Returns store details including address, hours, services, and distance."""
        return self._call("get_warehouse_locations", method="GET", latitude=latitude, longitude=longitude, limit=limit)

    def get_savings_deals(self, rows=None, start=None):
        """Retrieve current savings and promotional offers. Returns products with active discounts and deals."""
        return self._call("get_savings_deals", method="GET", rows=rows, start=start)

    def get_gold_and_precious_metals(self, rows=None, start=None):
        """Search specifically for gold bars, silver coins, and precious metals available on Costco.com."""
        return self._call("get_gold_and_precious_metals", method="GET", rows=rows, start=start)

    def get_pharmacy_medications(self, query=None, rows=None, start=None):
        """Browse vitamins, supplements, and health products available on Costco.com. Searches the health and pharmacy product categories."""
        return self._call("get_pharmacy_medications", method="GET", query=query, rows=rows, start=start)


if __name__ == "__main__":
    client = ParseClient()

    result = client.search_products(query="<Search keyword (e.g., 'televis>", rows="<Number of results per page>", start="<Pagination offset (0-based)>", sort_by="<Sort order: price_low_high, pr>")
    print("search_products:", result)

    result = client.get_category_listing(category_path="<Category URL path (e.g., '/tel>", rows="<Number of results per page>", start="<Pagination offset (0-based)>")
    print("get_category_listing:", result)

    result = client.get_product_details(item_numbers="<Comma-separated item numbers f>")
    print("get_product_details:", result)

    result = client.get_product_reviews(product_id="<Costco catalog product ID (gro>", limit="<Number of reviews per page>", offset="<Pagination offset>")
    print("get_product_reviews:", result)

    result = client.get_warehouse_locations(latitude="<Latitude coordinate>", longitude="<Longitude coordinate>", limit="<Maximum number of locations to>")
    print("get_warehouse_locations:", result)

    result = client.get_savings_deals(rows="<Number of results per page>", start="<Pagination offset (0-based)>")
    print("get_savings_deals:", result)

    result = client.get_gold_and_precious_metals(rows="<Number of results per page>", start="<Pagination offset (0-based)>")
    print("get_gold_and_precious_metals:", result)

    result = client.get_pharmacy_medications(query="<Search keyword for health/phar>", rows="<Number of results per page>", start="<Pagination offset (0-based)>")
    print("get_pharmacy_medications:", result)