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'