Skip to content

The agent that turns websites into APIs!

18.2 KB
Raw Blame
"""
IKEA API Client - Production Ready
A comprehensive Python client for interacting with IKEA's e-commerce APIs.

This client provides access to:
- Product search
- Product details
- Shopping cart management
- Guest authentication
- Price calculations
"""

import requests
from typing import Dict, List, Optional, Any
from dataclasses import dataclass
import json
from datetime import datetime, timedelta


@dataclass
class IKEAConfig:
    """Configuration for IKEA API client"""
    country: str = "us"
    language: str = "en"
    base_url: str = "https://www.ikea.com"
    search_api: str = "https://sik.search.blue.cdtapps.com"
    web_api: str = "https://web-api.ikea.com"
    cart_api: str = "https://prod.cart.caas.selling.ingka.com"
    auth_api: str = "https://api.ingka.ikea.com"
    accounts_api: str = "https://accounts.ikea.com"


class IKEAAPIClient:
    """
    IKEA API Client for e-commerce operations.

    This client handles authentication, product search, cart management,
    and other IKEA e-commerce API interactions.

    Example:
        client = IKEAAPIClient()
        products = client.search_products("chair")
        cart = client.add_to_cart("59305928", quantity=1)
    """

    def __init__(self, country: str = "us", language: str = "en"):
        """
        Initialize the IKEA API client.

        Args:
            country: Country code (default: "us")
            language: Language code (default: "en")
        """
        self.config = IKEAConfig(country=country, language=language)
        self.session = requests.Session()
        self.access_token: Optional[str] = None
        self.token_expires_at: Optional[datetime] = None
        self.cart_id: Optional[str] = None

        # Set default headers
        self.session.headers.update({
            'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36',
            'Accept': 'application/json',
            'Accept-Language': f'{language}-{country.upper()},{language};q=0.9',
        })

    def _ensure_authenticated(self) -> None:
        """Ensure we have a valid guest token."""
        if self.access_token and self.token_expires_at:
            if datetime.now() < self.token_expires_at:
                return

        # Get guest token
        self._authenticate_guest()

    def _authenticate_guest(self) -> Dict[str, Any]:
        """
        Authenticate as a guest user and obtain an access token.

        Returns:
            Dict containing access_token, expires_in, and token_type

        Raises:
            requests.HTTPError: If authentication fails
        """
        url = f"{self.config.auth_api}/guest/token"

        # Required headers for guest token
        headers = {
            'accept': 'application/json;version=2',
            'content-type': 'application/json',
            'x-client-id': 'b477b9e4-b836-40fb-842f-43db89dd3c52',
            'origin': 'https://www.ikea.com',
            'referer': 'https://www.ikea.com/'
        }

        # POST body with retail unit
        payload = {
            'retailUnit': self.config.country
        }

        try:
            response = self.session.post(url, json=payload, headers=headers, timeout=10)
            response.raise_for_status()

            data = response.json()
            self.access_token = data['access_token']

            # Parse expires_in (format: "720h")
            expires_hours = int(data['expires_in'].replace('h', ''))
            self.token_expires_at = datetime.now() + timedelta(hours=expires_hours)

            # Update session headers with token
            self.session.headers.update({
                'Authorization': f"Bearer {self.access_token}"
            })

            return data

        except requests.exceptions.RequestException as e:
            raise Exception(f"Failed to authenticate: {e}")

    def search_products(
        self,
        query: str,
        limit: Optional[int] = None,
        sort: Optional[str] = None
    ) -> Dict[str, Any]:
        """
        Search for products on IKEA.

        Args:
            query: Search query string
            limit: Maximum number of results to return
            sort: Sort order (e.g., "RELEVANCE", "PRICE_LOW_TO_HIGH")

        Returns:
            Dictionary containing search results with products, filters, and metadata

        Example:
            results = client.search_products("chair", limit=20)
            for product in results.get('results', []):
                if product.get('component') == 'PRIMARY_AREA':
                    print(product.get('products', []))
        """
        self._ensure_authenticated()

        url = f"{self.config.search_api}/{self.config.country}/{self.config.language}/search"

        params = {
            'c': 'sr',
            'v': '20250507'
        }

        # Build the comprehensive payload structure
        window_size = limit if limit else 24

        payload = {
            'searchParameters': {
                'input': query,
                'type': 'QUERY'
            },
            'allowAutocorrect': True,
            'isUserLoggedIn': False,
            'components': [
                {
                    'component': 'PRIMARY_AREA',
                    'columns': 4,
                    'types': {
                        'main': 'PRODUCT',
                        'breakouts': ['PLANNER', 'CATEGORY', 'CONTENT', 'MATTRESS_WARRANTY', 'FINANCIAL_SERVICES']
                    },
                    'filterConfig': {
                        'subcategories-style': 'tree-navigation',
                        'max-num-filters': 4
                    },
                    'window': {
                        'size': window_size,
                        'offset': 0
                    },
                    'allVariants': False,
                    'forceFilterCalculation': True
                },
                {
                    'component': 'CONTENT_AREA',
                    'types': {
                        'main': 'CONTENT',
                        'breakouts': []
                    },
                    'window': {
                        'size': 12,
                        'offset': 0
                    }
                },
                {'component': 'RELATED_SEARCHES'},
                {'component': 'QUESTIONS_AND_ANSWERS'},
                {'component': 'STORES'},
                {'component': 'CATEGORIES'},
                {'component': 'SIMILAR_PRODUCTS'},
                {'component': 'SEARCH_SUMMARY'},
                {'component': 'PAGE_MESSAGES'},
                {'component': 'RELATED_CATEGORIES'},
                {'component': 'PRODUCT_GROUP'}
            ]
        }

        if sort:
            payload['searchParameters']['sort'] = sort

        try:
            response = self.session.post(url, params=params, json=payload, timeout=10)
            response.raise_for_status()
            return response.json()

        except requests.exceptions.RequestException as e:
            raise Exception(f"Search failed: {e}")

    def get_product_details(self, item_no: str) -> Dict[str, Any]:
        """
        Get detailed information about a specific product.

        This method uses the search API to fetch product details by item number,
        as IKEA's direct product API requires additional authentication.

        Args:
            item_no: Product item number (e.g., "59305928" or "S59305928")

        Returns:
            Dictionary containing product details including:
            - product: Product information (name, price, images, etc.)
            - availability: Stock information
            - measurements: Product dimensions
            - categoryPath: Product category

        Example:
            product = client.get_product_details("59305928")
            print(product['product']['name'])
            print(product['product']['salesPrice']['numeral'])

        Raises:
            Exception: If product is not found or API call fails
        """
        self._ensure_authenticated()

        # Remove 'S' prefix if present
        if item_no.startswith('S'):
            item_no = item_no[1:]

        # Use search API with item number to get product details
        url = f"{self.config.search_api}/{self.config.country}/{self.config.language}/search"

        params = {
            'c': 'sr',
            'v': '20250507'
        }

        # Search for the exact item number
        payload = {
            'searchParameters': {
                'input': item_no,
                'type': 'QUERY'
            },
            'isUserLoggedIn': False,
            'components': [
                {
                    'component': 'PRIMARY_AREA',
                    'columns': 4,
                    'types': {
                        'main': 'PRODUCT',
                        'breakouts': []
                    },
                    'window': {
                        'size': 5,  # Only need a few results
                        'offset': 0
                    }
                }
            ]
        }

        try:
            response = self.session.post(url, params=params, json=payload, timeout=10)
            response.raise_for_status()
            data = response.json()

            # Extract the product from search results
            for result in data.get('results', []):
                if result.get('component') == 'PRIMARY_AREA':
                    items = result.get('items', [])
                    # Find the exact match by item number
                    for item in items:
                        product = item.get('product', {})
                        if product.get('itemNo') == item_no:
                            return product

            # If no exact match found, return first result if available
            for result in data.get('results', []):
                if result.get('component') == 'PRIMARY_AREA':
                    items = result.get('items', [])
                    if items and items[0].get('product'):
                        return items[0]['product']

            raise Exception(f"Product {item_no} not found")

        except requests.exceptions.RequestException as e:
            raise Exception(f"Failed to get product details: {e}")

    def get_cart(self, fetch_price: bool = True) -> Dict[str, Any]:
        """
        Get the current shopping cart.

        Args:
            fetch_price: Whether to fetch pricing information

        Returns:
            Dictionary containing cart information

        Example:
            cart = client.get_cart()
            print(f"Total: ${cart['cart']['price']['totalPrice']['current']['exclTax']}")
        """
        self._ensure_authenticated()

        url = f"{self.config.cart_api}/api/v1/{self.config.country}"

        params = {
            'fetchItemInfo': 'true',
            'fetchCartContext': 'false',
            'fetchIndicativeAvailability': 'false',
            'fetchPrice': str(fetch_price).lower(),
            'shoppingProfile': 'ONLINE',
            'group': 'DEFAULT'
        }

        headers = {
            'x-consumer-name': 'Web Cart',
            'accept': '*/*',
            'accept-language': self.config.language
        }

        try:
            response = self.session.get(url, params=params, headers=headers, timeout=10)
            response.raise_for_status()

            data = response.json()
            if data.get('cart', {}).get('cartId'):
                self.cart_id = data['cart']['cartId']

            return data

        except requests.exceptions.RequestException as e:
            raise Exception(f"Failed to get cart: {e}")

    def add_to_cart(self, item_no: str, quantity: int = 1) -> Dict[str, Any]:
        """
        Add a product to the shopping cart.

        Args:
            item_no: Product item number (e.g., "59305928")
            quantity: Quantity to add (default: 1)

        Returns:
            Dictionary containing updated cart information

        Example:
            cart = client.add_to_cart("59305928", quantity=2)
            print(f"Added to cart. Total items: {cart['cart']['quantity']}")
        """
        self._ensure_authenticated()

        url = f"{self.config.cart_api}/api/v1/{self.config.country}/items"

        payload = {
            'items': [
                {
                    'itemNo': item_no,
                    'quantity': float(quantity),
                    'itemType': 'SPR'
                }
            ],
            'languageCode': self.config.language.upper()
        }

        headers = {
            'x-consumer-name': 'Web Cart',
            'accept': '*/*',
            'accept-language': self.config.language
        }

        try:
            response = self.session.post(url, json=payload, headers=headers, timeout=10)
            response.raise_for_status()

            data = response.json()
            if data and data.get('cart', {}).get('cartId'):
                self.cart_id = data['cart']['cartId']

            return data if data else {}

        except requests.exceptions.RequestException as e:
            raise Exception(f"Failed to add to cart: {e}")

    def remove_from_cart(self, item_no: str) -> Dict[str, Any]:
        """
        Remove a product from the shopping cart.

        Args:
            item_no: Product item number to remove

        Returns:
            Dictionary containing updated cart information
        """
        self._ensure_authenticated()

        url = f"{self.config.cart_api}/api/v1/{self.config.country}/items/{item_no}"

        try:
            response = self.session.delete(url, timeout=10)
            response.raise_for_status()
            return response.json()

        except requests.exceptions.RequestException as e:
            raise Exception(f"Failed to remove from cart: {e}")

    def update_cart_quantity(self, item_no: str, quantity: int) -> Dict[str, Any]:
        """
        Update the quantity of a product in the cart.

        Args:
            item_no: Product item number
            quantity: New quantity

        Returns:
            Dictionary containing updated cart information
        """
        self._ensure_authenticated()

        url = f"{self.config.cart_api}/api/v1/{self.config.country}/items/{item_no}"

        payload = {
            'quantity': float(quantity)
        }

        try:
            response = self.session.patch(url, json=payload, timeout=10)
            response.raise_for_status()
            return response.json()

        except requests.exceptions.RequestException as e:
            raise Exception(f"Failed to update cart quantity: {e}")


    def calculate_price(self, amount: float) -> Dict[str, Any]:
        """
        Calculate pricing with tax and other fees.

        Args:
            amount: Base amount to calculate

        Returns:
            Dictionary containing price calculation details
        """
        self._ensure_authenticated()

        url = f"{self.config.web_api}/v2/calculation/hyperlink/{self.config.country}/{self.config.language}/{int(amount)}"

        try:
            response = self.session.get(url, timeout=10)
            response.raise_for_status()
            return response.json()

        except requests.exceptions.RequestException as e:
            raise Exception(f"Failed to calculate price: {e}")

    def get_discounts(self, item_numbers: List[str]) -> Dict[str, Any]:
        """
        Get available discounts for products.

        Args:
            item_numbers: List of product item numbers

        Returns:
            Dictionary containing discount information
        """
        self._ensure_authenticated()

        url = f"{self.config.web_api}/wdm/api/discounts/get"

        payload = {
            'itemNos': item_numbers,
            'retailUnit': self.config.country
        }

        try:
            response = self.session.post(url, json=payload, timeout=10)
            response.raise_for_status()
            return response.json()

        except requests.exceptions.RequestException as e:
            raise Exception(f"Failed to get discounts: {e}")


# Example usage
if __name__ == "__main__":
    # Initialize the client
    client = IKEAAPIClient(country="us", language="en")

    print("=== IKEA API Client Demo ===\n")

    # 1. Search for products
    print("1. Searching for 'chair'...")
    search_results = client.search_products("chair", limit=10)

    # Extract products from search results
    products = []
    for result in search_results.get('results', []):
        if result.get('component') == 'PRIMARY_AREA':
            products = result.get('items', [])
            break

    if products:
        print(f"   Found {len(products)} products (showing first 3):")
        for i, product in enumerate(products[:3], 1):
            product_info = product.get('product', {})
            name = product_info.get('name', 'Unknown')
            item_no = product_info.get('itemNo', 'N/A')
            price = product_info.get('salesPrice', {}).get('numeral', 'N/A')
            print(f"   {i}. {name} (Item: {item_no}) - ${price}")
    else:
        print("   No products found in search results")

    # 2. Get product details
    print("\n2. Getting product details...")
    if products:
        first_item_no = products[0].get('product', {}).get('itemNo')
        if first_item_no:
            try:
                product_details = client.get_product_details(first_item_no)
                print(f"   Product: {product_details.get('name')} ({first_item_no})")
                print(f"   Price: ${product_details.get('salesPrice', {}).get('numeral', 'N/A')}")
                print(f"   Type: {product_details.get('typeName', 'N/A')}")
            except Exception as e:
                print(f"   Error getting details: {e}")

    # 3. Get current cart
    print("\n3. Getting current cart...")
    cart = client.get_cart()
    cart_items = cart.get('cart', {}).get('groups', [])
    if cart_items and cart_items[0].get('items'):
        print(f"   Cart has {len(cart_items[0]['items'])} items")
    else:
        print("   Cart is empty")

    # 4. Add item to cart (Note: Cart add may require browser cookies/session)
    print("\n4. Adding items to cart (skipped - requires browser session cookies)")

    # 5. Calculate price
    print("\n5. Calculating price for $149...")
    try:
        price_calc = client.calculate_price(149)
        print(f"   Calculation result: {price_calc}")
    except Exception as e:
        print(f"   Error: {e}")

    print("\n=== Demo Complete ===")