Metadata-Version: 2.4
Name: productinformationapi
Version: 0.1.0
Summary: Product information and stock checks with Product Information API
Author-email: HustleGotReal <contact@hustlegotreal.com>
License-Expression: MIT
Project-URL: Homepage, https://productinformationapi.com
Keywords: product-information,stock,scraping,api,sdk
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Product Information API for Python

Product information and stock checks in Python 3.11+, with type hints and no runtime dependencies.

## Install

```sh
python -m pip install productinformationapi
```

Or install the distributed wheel with `python -m pip install ./productinformationapi-0.1.0-py3-none-any.whl`.

## Quick start

Use a tenant API key from your Product Information API account. MCP OAuth access tokens are scoped
to MCP and cannot authenticate these REST requests. Keep the key in your server environment:

```sh
export PRODUCTINFORMATIONAPI_API_KEY='your-api-key'
```

```python
from productinformationapi import ProductInformationAPI

client = ProductInformationAPI()  # Reads PRODUCTINFORMATIONAPI_API_KEY.
url = "https://www.amazon.com/dp/B0D3BCR3V7"

product = client.get_product_information(url)
print((product.get("productInformation") or {}).get("title"), product["creditsCharged"])

stock = client.check_stock(url)
print(stock["inStock"], stock["offers"], stock["creditsRemaining"])
```

Methods return the complete API response as a dictionary. Response keys retain the API's camelCase
names. The client is synchronous; in an asyncio application, use a worker thread:

```python
import asyncio

stock = await asyncio.to_thread(client.check_stock, url)
```

Cancelling the asyncio waiter does not cancel the worker thread's HTTP request; its socket timeout
still applies.

## Bulk

```python
batch = client.check_stock_bulk([
    "https://www.amazon.com/dp/B0D3BCR3V7",
    {"productUrl": "https://www.amazon.co.uk/dp/B0D3BCR3V7", "sourceSite": "amazon_gb"},
])

for row in batch["results"]:
    if row["httpStatus"] == 200:
        print(row["index"], row["result"])
    else:
        print(row["index"], row["httpStatus"], row["result"]["error"])

# Product information uses the same inputs:
products = client.get_product_information_bulk([
    "https://www.amazon.com/dp/B0D3BCR3V7",
])
```

Bulk calls return inline. A successful HTTP response can contain failed items; inspect each
`httpStatus`. The current default server limit is 100 items per batch. Items are never silently
split, retried, or reordered. Large batches may require a longer HTTP timeout.

## Options and errors

```python
from uuid import uuid4
from productinformationapi import APIError

request_key = str(uuid4())  # Retain this key if you retry this exact request.
try:
    stock = client.check_stock(
        url,
        idempotency_key=request_key,
        timeout=120,
        request_timeout_ms=30_000,
    )
    print(stock["inStock"])
except APIError as error:
    print(error.status, error.code, error.request_id, error.retry_after_s)
```

- Constructor: `ProductInformationAPI(api_key=None, *, base_url="https://api.productinformationapi.com", timeout=120)`.
- All methods accept `idempotency_key` and `timeout` in seconds. `timeout` is the standard-library
  socket timeout for blocking operations, not a guaranteed total wall-clock deadline.
- Singular methods accept `source_site`. `get_product_information` also accepts
  `include_gpsr=True` for Amazon DE GPSR details. Bulk requests do not accept GPSR options.
- `request_timeout_ms` applies only to singular stock requests, from 1000 to 100000 milliseconds.
  It shortens the server execution budget. Leave additional time in `timeout` for server cleanup.
- Timeouts do not prove the server did no work or charged no credits. There are no automatic
  retries. Reuse an idempotency key only for the same operation and payload; keep bulk items in
  the same order on a retry. Keys must contain 1–255 visible ASCII characters.
- `APIError` exposes `status`, `code`, `request_id`, `retryable`, `retry_after_s`, and the parsed
  response as `body`. HTML edge failures still produce `APIError`. Bulk item errors remain in
  `batch["results"]`. Transport failures retain standard-library exceptions such as `URLError`
  and `TimeoutError`.

## Webhooks

Scrape-result webhooks and asynchronous jobs are not currently implemented by the API. These
methods return the result directly; no webhook URL option is available.

## Support and license

Visit [Product Information API](https://productinformationapi.com) or contact
[contact@hustlegotreal.com](mailto:contact@hustlegotreal.com).

This SDK is MIT licensed. API access requires a separate account and is subject to the service's
terms and credit usage.
