Macy's Products Actor Documentation

Overview

The Macy's Products actor is a web scraping tool deployed on Apify that extracts product information from Macy's e-commerce website. This actor processes multiple product URLs and retrieves detailed product data.

Features

• Bulk Product Processing: Process multiple Macy's product URLs in a single run
• Flexible Configuration: Support for different currency codes and region codes
• API-Based Extraction: Uses Macy's internal API for reliable data extraction
• Structured Output: Returns consistent, structured product data
• Error Handling: Robust processing with proper error management

Input Configuration

Input Schema

The actor accepts the following input parameters:

Required Parameters

• productUrls (array, required)
  • Array of product URL objects
  • Each object should contain a url field with the full Macy's product URL
  • Example format: [{"url": "https://www.macys.com/shop/product/..."}]

Optional Parameters

• currencyCode (string, optional)

  • Currency code for pricing information
  • Default: "USD"
  • Example: "USD", "CAD", "EUR"

• regionCode (string, optional)

  • Region code for localization
  • Default: "US"
  • Example: "US", "CA", "UK"

Example Input

{
  "productUrls": [
    {
      "url": "https://www.macys.com/shop/product/nike-mens-air-max-90-casual-sneakers-from-finish-line?ID=17395592&swatchColor=Black"
    },
    {
      "url": "https://www.macys.com/shop/product/kenneth-cole-reaction-mens-ready-flex-slim-fit-suit?ID=4799182&swatchColor=Light%20Grey#PRODUCT_DEPARTMENT/Blazers%20%26%20Sport%20Coats%7CSuits"
    }
  ],
  "currencyCode": "USD",
  "regionCode": "US"
}

Output

Data Storage

The actor provides output in two formats:

1. Individual Records: Each product is pushed to the dataset individually using Actor.pushData()
2. Compiled Results: All results are stored as a single array in the key-value store under the key 'output'

Output Structure

• Product name and description
• Pricing information
• Product images
• Availability status
• Product specifications
• Reviews and ratings
• Category information

Usage Instructions

Running the Actor

1. Via Apify Console:

   • Navigate to the Macy's Products actor in your Apify account
   • Configure the input parameters
   • Click "Start" to run the actor

2. Via API:

   const { ApifyApi } = require('apify-client');
   
   const client = new ApifyApi({
       token: 'YOUR_API_TOKEN'
   });
   
   const run = await client.actor('THE_ACTOR_ID').call({
       productUrls: [
           { url: "https://www.macys.com/shop/product/..." }
       ],
       currencyCode: "USD",
       regionCode: "US"
   });
   

Accessing Results

• Dataset: Individual product records are available in the run's dataset
• Key-Value Store: Complete results array is stored under the key 'output'
• API Access: Results can be retrieved via Apify's API endpoints

Error Handling

The actor includes error handling mechanisms to manage:

• Invalid product URLs
• Network connectivity issues
• API rate limiting
• Product availability changes
• Malformed product IDs

Best Practices

Input Preparation

• Ensure all product URLs are valid Macy's product pages
• Use full URLs including all query parameters
• Verify product IDs are extractable from the URLs

Performance Optimization

• Process products in reasonable batch sizes
• Consider rate limiting for large datasets
• Monitor actor performance and adjust accordingly

Data Quality

• Validate output data for completeness
• Handle missing or null values appropriately
• Implement data quality checks for critical fields

Limitations

• Rate Limiting: Subject to Macy's API rate limits
• Product Availability: Some products may become unavailable between runs
• Regional Restrictions: Some products may not be available in all regions
• Currency Support: Limited to currencies supported by Macy's
• URL Format Dependencies: Relies on current Macy's URL structure

Troubleshooting

Common Issues

1. Invalid Product URLs

   • Ensure URLs are from macys.com domain
   • Verify URLs contain extractable product IDs
   • Check for proper URL encoding

2. Empty Results

   • Verify product is still available on Macy's website
   • Check if product is available in specified region
   • Confirm currency code is supported

3. API Errors

   • Monitor for rate limiting responses
   • Verify network connectivity
   • Check for changes in Macy's API endpoints

Debugging

• Enable detailed logging to track processing steps
• Monitor network requests and responses
• Validate product ID extraction logic
• Test with known working product URLs

Support and Maintenance

For issues related to:

• Actor functionality: Check the implementation of the getProduct function
• Apify platform: Refer to Apify documentation and support
• Macy's website changes: Monitor for updates to Macy's URL structure or API endpoints