pangolinfo-alexa

Python SDK for the Pangolinfo Amazon Alexa (Rufus) Shopping API.

This SDK provides a thin, typed wrapper around the Pangolinfo amazonAlexa scraper, letting you drive Amazon's Alexa/Rufus shopping assistant programmatically — submit prompts, receive Alexa's natural-language answers, recommended products, follow-up questions, and optional page screenshots.

Features

• Simple, synchronous AlexaClient based on httpx
• Accepts a single prompt or a list of prompts (multi-turn conversations)
• Returns structured product data (ASIN, price, ratings, cover image, ...)
• Optional page URL context and screenshot capture
• Clear exception hierarchy (AuthenticationError, APIError, TimeoutError)
• Context-manager support for automatic resource cleanup

Installation

pip install pangolinfo-alexa

Authentication

You need a Pangolinfo API token (Bearer token). Get a free API key at https://tool.pangolinfo.com.

Quick Start

from pangolinfo_alexa import AlexaClient

with AlexaClient(token="YOUR_TOKEN") as client:
    data = client.ask("What are the best noise-cancelling headphones under $200?")
    for turn in data["json"]:
        print(turn["content"])
        for product in turn.get("products", []):
            for item in product.get("items", []):
                print(item["asin"], item["title"], item["price"])

Multi-turn conversation

Pass a list of prompts — each element is one conversation turn. The response data["json"] array will contain one result element per turn, in order.

with AlexaClient(token="YOUR_TOKEN") as client:
    data = client.ask([
        "Recommend a gift for a 6-year-old boy.",
        "Are any of those educational?",
    ])
    for turn in data["json"]:
        print(turn["prompt"], "->", turn["content"])

API Reference

AlexaClient

AlexaClient(token, base_url="https://scrapeapi.pangolinfo.com", timeout=180)

Parameters

Name	Type	Default	Description
token	str	— (required)	Pangolinfo API Bearer token.
base_url	str	https://scrapeapi.pangolinfo.com	API base URL.
timeout	int	180	Request timeout in seconds. Alexa responses take 60–120s, so extra time is given.

Methods

ask(prompt, url=None, screenshot=False)

Submit one or more prompts to Amazon Alexa (Rufus) and return the parsed response data.

Parameters:

Name	Type	Default	Description
prompt	str or list[str]	— (required)	A single prompt string, or a list of prompts (one per conversation turn). Recommended ≤ 5 prompts.
url	str or None	None	Optional Amazon page URL to provide contextual intelligent responses based on page content.
screenshot	bool	False	Whether to capture page screenshots.

Returns: dict — the data field of the API response, containing:

Key	Type	Description
json	list	Array of per-turn result objects (one per prompt).
taskId	str	Server-side task identifier.
url	str	Echoed/processed URL (may be empty).
screenshot	str	Screenshot URL if screenshot=True, otherwise empty.

Per-turn result object (each element of data["json"]):

Key	Type	Description
prompt	str	The prompt that produced this turn.
content	str	Alexa's natural-language text response.
products	list	Recommended product groups (see below).
follow_up_questions	list[str]	Suggested follow-up questions.
screenshot	str	Per-turn screenshot URL (if enabled).

Product group (element of turn["products"]):

Key	Type	Description
title	str	Group/category title.
items	list	Array of product items (see below).

Product item (element of group["items"]):

Key	Type	Description
asin	str	Amazon Standard Identification Number.
url	str	Product page URL.
title	str	Product title.
cover	str	Cover/main image URL.
score	float	Star rating (e.g. 4.5).
ratingsCount	int	Number of customer ratings.
price	str	Current price (formatted string).
originalPrice	str	Original/list price (formatted string).
describe	str	Short product description / feature summary.

close()

Close the underlying HTTP connection pool.

Context manager

AlexaClient supports with syntax — close() is called automatically on exit.

Exceptions

All exceptions live in pangolinfo_alexa.exceptions and are re-exported from the top-level package.

Exception	Base	Raised when
AlexaError	Exception	Base class for all SDK errors.
AuthenticationError	AlexaError	HTTP 401/403 — invalid or missing token.
APIError	AlexaError	API returns code != 0 or a non-2xx status.
TimeoutError	AlexaError	Request times out.

Credit Consumption

• 6 credits per conversation turn, billed by the length of the param array.
• Example: 1 prompt = 6 credits; 5 prompts = 30 credits.
• Average response time: 60–120 seconds.

Examples

Single prompt

from pangolinfo_alexa import AlexaClient

with AlexaClient(token="YOUR_TOKEN") as client:
    data = client.ask("Best mechanical keyboard for coding")
    print(data["json"][0]["content"])

With page context and screenshot

with AlexaClient(token="YOUR_TOKEN") as client:
    data = client.ask(
        "What are the top reviews for this product?",
        url="https://www.amazon.com/dp/B0XXXXXXXX",
        screenshot=True,
    )
    print(data["screenshot"])

Error handling

from pangolinfo_alexa import AlexaClient, AuthenticationError, APIError, TimeoutError

try:
    with AlexaClient(token="YOUR_TOKEN", timeout=200) as client:
        data = client.ask("Hello")
except AuthenticationError:
    print("Invalid token")
except TimeoutError:
    print("Request timed out — Alexa can take up to 120s")
except APIError as e:
    print(f"API error: {e}")

Links

• Documentation: https://docs.pangolinfo.com
• Source code: https://github.com/Pangolin-spg/pangolinfo-alexa
• Issue tracker: https://github.com/Pangolin-spg/pangolinfo-alexa/issues
• Changelog: https://github.com/Pangolin-spg/pangolinfo-alexa/releases
• Free API Key: https://tool.pangolinfo.com

License

MIT — Copyright (c) 2026 PANGOLIN INFO TECH PTE. LTD.