Metadata-Version: 2.4
Name: nocode-amazon
Version: 0.0.1
Summary: No code Amazon scraper and Amazon API client: search, product, pricing and featured or sponsored placements via ScrapingBee.
Author: wordstotech
License: MIT
Project-URL: Homepage, https://github.com/ScrapingBee/nocode-amazon
Project-URL: Repository, https://github.com/ScrapingBee/nocode-amazon
Project-URL: Documentation, https://www.scrapingbee.com/documentation/
Keywords: amazon scraper,amazon api,no code scraper,scrape amazon products,amazon product scraper,amazon featured products,web scraping,scrapingbee
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Markup :: HTML
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Dynamic: license-file

# nocode-amazon

A Python client for ScrapingBee's three dedicated Amazon endpoints, plus the helpers that separate paid placements from earned ones.

The package name comes from the no code Make and Airtable workflow this grew out of. The library is the code path for people who outgrew the spreadsheet: same data, same public Amazon pages, no visual scenario to maintain.

**Verified against the live API on 2026-09-10.** Every parameter name, response field and credit figure below came back from a real call. Where the documentation and the API disagreed, the API won and the difference is noted.

```bash
pip install nocode-amazon
```

Requires Python 3.8 or newer and `requests`.

## Authentication

Header based, on every request:

```
Authorization: Bearer YOUR_API_KEY
```

The `api_key` query parameter still answers but the current documentation marks it deprecated. This client sends the header.

```python
from nocode_amazon import AmazonScraper

bee = AmazonScraper("YOUR_API_KEY")
```

Get a key and 1,000 free credits from [ScrapingBee](https://www.scrapingbee.com/). Full reference: [Amazon API documentation](https://www.scrapingbee.com/documentation/amazon/).

---

## Endpoint reference

### `search(query, pages=1, **params)`

`GET /api/v1/amazon/search`. **5 credits per page.**

Amazon search results as structured JSON. No HTML, no selectors.

```python
page = bee.search("fitness tracker")
page["products_count"]   # 23
page["products"]         # list of product dicts
page["refinements"]      # Amazon's own facets for this query
page["url"]              # the Amazon URL that was fetched
page["page"]             # 1
```

Live call on `fitness tracker` returned 23 products and a `refinements` object with 53 facet groups, including `brands`, `band_color`, `band_material_type`, `battery_average_life`, `battery_charge_time` and `case_diameter`.

Optional parameters, all verified present on the endpoint:

| Parameter | Notes |
|---|---|
| `pages` | Pages to fetch. Billed per page |
| `sort_by` | `featured`, `most_recent`, `price_low_to_high`, `price_high_to_low`, `average_review`, `bestsellers` |
| `category_id` | Restrict to one Amazon category |
| `merchant_id` | Restrict to one seller |
| `domain` | Marketplace top level domain: `com`, `co.uk`, `de`, `in` |
| `country` | Proxy geolocation |
| `currency` | ISO 4217 display currency |
| `language` | ISO language code |
| `device` | `desktop` or `mobile` |
| `zip_code` | Postal code. Changes prices and delivery promises |
| `light_request` | Default `True` at 5 credits. `False` forces a browser at 15 |
| `add_html` | Include the raw page alongside the JSON |
| `autoselect_variant` | Pick a variant automatically |
| `screenshot` | Capture the page. Always 15 credits, ignores `light_request` |
| `tag` | Your own label, returned in the response headers |

Related landing pages: [Amazon search API](https://www.scrapingbee.com/scrapers/amazon-search-api/), [Amazon keyword scraper API](https://www.scrapingbee.com/scrapers/amazon-keyword-scraper-api/), [Amazon organic results API](https://www.scrapingbee.com/scrapers/amazon-organic-results-api/), [Amazon filters API](https://www.scrapingbee.com/scrapers/amazon-filters-api/), [Amazon related searches API](https://www.scrapingbee.com/scrapers/amazon-related-searches-api/), [Amazon spell check API](https://www.scrapingbee.com/scrapers/amazon-spell-check-api/), [Amazon zip code API](https://www.scrapingbee.com/scrapers/amazon-zip-code-api/).

### `product(asin, **params)`

`GET /api/v1/amazon/product`. **5 credits.**

**The wire parameter is `query`, not `asin`.** The value has to be a valid 10 character ASIN, but the field is named `query`. This client takes `asin` as its argument name and sends `query` for you.

```python
detail = bee.product("B0GTMTZF3V")
detail["brand"]          # 'Fitbit'
detail["price"]          # 99.99
detail["currency"]       # 'USD'
detail["rating"]         # 4.3
detail["reviews_count"]  # 2036
```

The live response carried **56 top level keys**. The ones worth knowing:

| Field | Contents |
|---|---|
| `bullet_points` | The feature bullets, newline separated |
| `category` | A `ladder` of breadcrumb steps, each with `name` and `url` |
| `featured_merchant` | `name`, `seller_id`, `shipped_from`, `is_amazon_fulfilled` |
| `product_details` | Spec table as key and value pairs, including `best_sellers_rank` |
| `technical_details` | The second spec table |
| `rating_stars_distribution` | Review counts per star rating |
| `sales_rank` | Category rank entries |
| `variations` | Other sizes, colours and configurations |
| `images` | Image URLs |
| `delivery` | Delivery promises with type and date |
| `pricing_url` | The offer listing page for this ASIN |
| `parent_asin` | The variation parent |
| `discount_percentage`, `price_strikethrough`, `coupon` | Promotion state |
| `stock`, `max_quantity` | Availability |

Related: [Amazon ASIN API](https://www.scrapingbee.com/scrapers/amazon-asin-api/), [Amazon image API](https://www.scrapingbee.com/scrapers/amazon-image-api/), [Amazon review API](https://www.scrapingbee.com/scrapers/amazon-review-api/), [Amazon best sellers API](https://www.scrapingbee.com/scrapers/amazon-best-sellers-api/), [Amazon video results API](https://www.scrapingbee.com/scrapers/amazon-video-results-api/), [Amazon URL API](https://www.scrapingbee.com/scrapers/amazon-ulr-api/).

### `pricing(asin, **params)`

`GET /api/v1/amazon/pricing`. **5 credits.**

**This endpoint takes `asin` on the wire.** Search and product both take `query`. Pricing does not, and it rejects `query` explicitly:

```json
{"errors": {"query": {"asin": ["Missing data for required field."], "query": ["Unknown field."]}}}
```

That rejected call was billed **0 credits**, confirmed by `spb-cost: 0` on the response. This client raises `ScrapingBeeError` with the API's own error dict in `.payload`, so the offending field is never a guess.

```python
offers = bee.pricing("B0GTMTZF3V")
for offer in offers["pricing"]:
    print(offer["seller"], offer["price"], offer["condition"])
```

Each offer carries `seller`, `seller_id`, `seller_link`, `condition`, `price`, `price_shipping`, `currency`, `rating_count` and a `delivery_options` list.

Related: [Amazon offers API](https://www.scrapingbee.com/scrapers/amazon-offers-api/), [Amazon seller API](https://www.scrapingbee.com/scrapers/amazon-seller-api/), [Amazon vendor API](https://www.scrapingbee.com/scrapers/amazon-vendor-api/), [Amazon shipping API](https://www.scrapingbee.com/scrapers/amazon-shipping-api/).

### `usage()`

`GET /api/v1/usage`. **Free.**

```python
bee.usage()
# {'max_api_credit': 1000000, 'used_api_credit': 353946,
#  'max_concurrency': 100, 'current_concurrency': 0,
#  'renewal_subscription_date': '2026-09-21T12:06:28'}
```

Call this before a large run. Note it lags by minutes, so do not read it immediately afterwards to compute what a batch cost.

---

## Placement helpers

Amazon search markup gives every card the same classes, so CSS selectors cannot tell a paid slot from an earned rank. The endpoint labels each result instead, which turns the problem into a filter.

Per product placement fields:

| Field | Type | Meaning |
|---|---|---|
| `is_sponsored` | bool | Paid placement |
| `sponsored_position` | int or None | Rank among the ads |
| `organic_position` | int or None | Rank among earned results |
| `is_amazons_choice` | bool | Amazon's Choice badge |
| `best_seller` | bool | Best Seller badge |
| `sales_volume` | str | For example `10K+ bought in past month` |

```python
page = bee.search("fitness tracker", sort_by="featured")

AmazonScraper.featured(page)   # sponsored, ordered by ad slot
AmazonScraper.organic(page)    # earned, ordered by organic rank
AmazonScraper.badged(page)     # Amazon's Choice or Best Seller
AmazonScraper.facets(page)     # the refinements object
```

Two live runs on the same query returned 7 featured of 24 products, then 9 of 26. Paid density moves between requests, so measure it rather than assuming a fixed ratio.

`is_prime` came back `False` on every row of both pages, so verify it against your own target category before building a Prime filter on it.

---

## Credit cost

Measured from `spb-cost` response headers, not quoted from a pricing page. This client stores the value on `bee.last_cost` after every call.

| Call | Credits |
|---|---|
| Search, default light request | 5 per page |
| Search, `light_request=False` | 15 per page |
| Product, default | 5 |
| Product, `light_request=False` | 15 |
| Pricing | 5 |
| Any screenshot | 15 |
| Rejected request | 0 |
| `usage()` | 0 |

Light requests skip the browser. They were sufficient for search, product and pricing on every call made here. Turn them off when you need review text or other content that appears only after JavaScript runs.

Failed requests are retried inside the API for up to 30 seconds, so set client timeouts above that. This client defaults to 60 seconds.

Plan tiers: [ScrapingBee pricing](https://www.scrapingbee.com/pricing).

---

## Scope

Public Amazon listing and product pages. Nothing in this package signs in, and scraping under login credentials is prohibited by ScrapingBee's terms of service.

## Related features

[AI web scraping](https://www.scrapingbee.com/features/ai-web-scraping-api/), [data extraction rules](https://www.scrapingbee.com/features/data-extraction/), [Amazon feature page](https://www.scrapingbee.com/features/amazon/), [screenshots](https://www.scrapingbee.com/features/screenshot/), [markdown scraper](https://www.scrapingbee.com/features/markdown-scraper/), [Make integration](https://www.scrapingbee.com/features/make/), [n8n integration](https://www.scrapingbee.com/features/n8n/), [Zapier integration](https://www.scrapingbee.com/features/zapier/).

The no code version of this workflow, with the Make scenario and the extraction rules, is at [github.com/ScrapingBee/nocode-amazon](https://github.com/ScrapingBee/nocode-amazon).

## License

MIT
