Amazon Search

Amazon Product Search

Setup

Read your credentials from ~/.gooseworks/credentials.json:

export GOOSEWORKS_API_KEY=$(python3 -c "import json;print(json.load(open('$HOME/.gooseworks/credentials.json'))['api_key'])")
export GOOSEWORKS_API_BASE=$(python3 -c "import json;print(json.load(open('$HOME/.gooseworks/credentials.json')).get('api_base','https://api.gooseworks.ai'))")

If ~/.gooseworks/credentials.json does not exist, tell the user to run: npx gooseworks login

All endpoints use Bearer auth: -H "Authorization: Bearer $GOOSEWORKS_API_KEY"

Search for products on Amazon. Find items by keyword, category, or criteria.

When to Use

• User wants to find a product on Amazon
• User asks "find me a [product] on Amazon"
• User wants to compare prices
• User needs product recommendations

How It Works

Uses the SearchAPI Amazon Search engine to query Amazon's catalog.

Usage

Basic Product Search

curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"searchapi","path":"/api/v1/search","query":{"engine":"amazon_search","q":"wireless earbuds"}}'

<details>

<summary>curl equivalent</summary>

curl -X POST "https://api.orth.sh/v1/run" \

  -H "Content-Type: application/json" \
  -d '{"api":"searchapi","path":"/api/v1/search","query":{"engine":"amazon_search","q":"wireless earbuds"}}'

</details>

Search with Category

curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"searchapi","path":"/api/v1/search","query":{"engine":"amazon_search","q":"laptop","category_id":"electronics"}}'

Parameters

• engine (required) - Must be amazon_search
• q (required) - Search query
• category_id - Amazon category (electronics, books, etc.)
• page - Page number for pagination

Response

Top-level keys: search_metadata, search_parameters, search_information, organic_results, filters, pagination.

Each item in organic_results array:

• position (integer) - Result rank
• asin (string) - Amazon product ID
• title (string) - Product name
• link (string) - Product page URL
• image (string) - Product thumbnail URL
• price (string) - Display price (e.g., "$69.99")
• extracted_price (number) - Numeric price for comparison
• original_price / extracted_original_price - Pre-discount price (if on sale)
• currency (string) - Currency code (e.g., "USD")
• rating (number) - Star rating (0-5)
• reviews (integer) - Number of reviews
• is_prime (boolean) - Prime eligible
• is_best_seller / is_amazon_choice (boolean) - Badge flags
• delivery (string) - Delivery estimate text

Pagination: Use page=2, page=3, etc. for more results.

Examples

User: "Find wireless earbuds on Amazon"

curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"searchapi","path":"/api/v1/search","query":{"engine":"amazon_search","q":"wireless earbuds"}}'

User: "Search for laptops under $500"

curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"searchapi","path":"/api/v1/search","query":{"engine":"amazon_search","q":"laptop under 500"}}'

User: "Find highly rated coffee makers"

curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"searchapi","path":"/api/v1/search","query":{"engine":"amazon_search","q":"coffee maker best rated"}}'

Error Handling

• 400 - Invalid engine name or missing q parameter
• 401 - Invalid API key
• 429 - Rate limit — wait and retry
• Empty organic_results array means no products matched the query — try broader search terms
• Use separate -q flags if & in query string causes issues: -q 'engine=amazon_search' -q 'q=wireless earbuds'