# Macys Store By Proximity (`pintostudio/macys-store-by-proximity`) Actor

Macys Store By Proximity is a powerful Apify actor that helps you find the nearest Macy's department store location based on geographic coordinates.

- **URL**: https://apify.com/pintostudio/macys-store-by-proximity.md
- **Developed by:** [Pinto Studio](https://apify.com/pintostudio) (community)
- **Categories:** E-commerce, Developer tools, Other
- **Features:** Limited permissions
- **Stats:** 2 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$4.00 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Macys Store By Proximity - Apify Actor Documentation

### Overview

**Macys Store By Proximity** is a powerful Apify actor that helps you find the nearest Macy's department store location based on geographic coordinates. This actor uses Macy's official store locator API to retrieve detailed information about the closest store within a specified radius, making it perfect for location-based applications, retail analytics, and customer service tools.

### 🚀 Quick Start

#### Input Parameters

The actor requires three essential parameters:

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `latitude` | String | Yes | `40.7500` | Latitude coordinate (decimal degrees) |
| `longitude` | String | Yes | `-73.9967` | Longitude coordinate (decimal degrees) |
| `radius` | String | Yes | `M100` | Search radius (format: M + number in miles) |

#### Example Input

```json
{
  "latitude": "40.7500",
  "longitude": "-73.9967",
  "radius": "M100"
}
```

#### Example Output

The actor returns comprehensive store information including:

```json
{
  "preferredStore": {
    "storeId": "70",
    "storeNumber": "3",
    "locationNumber": "10",
    "divisionId": "6",
    "name": "Macy's Herald Square",
    "address": {
      "id": "70",
      "line1": "151 West 34th Street",
      "line2": "",
      "city": "New York",
      "state": "NY",
      "zipCode": "10001",
      "countryCode": "USA"
    },
    "phoneNumber": "212-695-4400",
    "geoLocation": {
      "latitude": "40.751455",
      "longitude": "-73.9902",
      "distance": "0.3951",
      "distanceUnit": "mi"
    },
    "schedule": {
      "todaysHours": {
        "openTime": "10:00 am",
        "closeTime": "10:00 pm"
      },
      "tomorrowsHours": {
        "openTime": "10:00 am",
        "closeTime": "10:00 pm"
      }
    }
  }
}
```

### 📍 Use Cases

#### 1. **E-commerce Integration**

- **Store Locator Features**: Integrate into websites to help customers find nearby Macy's locations
- **Click-and-Collect Services**: Enable customers to choose pickup locations based on proximity
- **Inventory Management**: Check which stores are closest to customers for efficient order fulfillment

#### 2. **Marketing & Analytics**

- **Geo-targeted Campaigns**: Create location-specific marketing campaigns based on store proximity
- **Market Analysis**: Analyze store coverage and identify market gaps
- **Customer Demographics**: Map customer locations relative to store positions

#### 3. **Mobile Applications**

- **Location-based Services**: Build mobile apps that automatically suggest the nearest Macy's store
- **Navigation Integration**: Provide turn-by-turn directions to the closest store
- **Store Hours Display**: Show real-time opening hours for nearby locations

#### 4. **Business Intelligence**

- **Competitor Analysis**: Map Macy's store locations for market research
- **Site Selection**: Analyze existing store coverage for new location planning
- **Supply Chain Optimization**: Optimize delivery routes based on store locations

#### 5. **Customer Service Tools**

- **Call Center Support**: Help customer service representatives quickly find store information
- **Live Chat Integration**: Automatically suggest nearby stores during customer inquiries
- **Appointment Scheduling**: Connect customers with services at their nearest location

### 🛠 Technical Implementation

#### API Integration

This actor seamlessly integrates with Macy's official store locator system, ensuring:

- **Real-time Data**: Always current store information and hours
- **Reliable Performance**: Built-in request delays prevent rate limiting
- **Error Handling**: Comprehensive validation and error management

#### Rate Limiting

The actor includes intelligent rate limiting with random delays (0-0.5 seconds) between requests to ensure stable performance and compliance with API guidelines.

#### Data Quality

Each response includes:

- Complete store contact information
- Precise geographic coordinates with calculated distance
- Current and next-day operating hours
- Store hierarchy information (division, location numbers)

### 🔧 Configuration Guide

#### Basic Setup

1. **Input Coordinates**: Use decimal degree format for latitude and longitude
2. **Set Radius**: Specify search radius using "M" prefix (e.g., "M50" for 50 miles)
3. **Run Actor**: Execute to retrieve the nearest store information

#### Advanced Configuration

- **Multiple Locations**: Run the actor multiple times with different coordinates for batch processing
- **Custom Radius**: Adjust radius based on your specific use case (urban vs. rural areas)
- **Integration**: Use Apify SDK or API to integrate into your applications

### 📊 Output Data Structure

The actor returns structured JSON data containing:

#### Store Information

- **Identifiers**: Store ID, number, location number, division ID
- **Basic Details**: Store name and complete address
- **Contact**: Phone number for customer inquiries

#### Geographic Data

- **Coordinates**: Precise latitude and longitude
- **Distance**: Calculated distance from input coordinates
- **Units**: Distance measurement unit (miles)

#### Operating Hours

- **Today's Schedule**: Current day opening and closing times
- **Tomorrow's Schedule**: Next day operating hours for planning

### 🌟 Why Choose This Actor?

#### ✅ **Accurate & Reliable**

- Uses official Macy's API for guaranteed accuracy
- Real-time store information and hours
- Robust error handling and validation

#### ✅ **Easy Integration**

- Simple JSON input/output format
- Compatible with all major programming languages
- Comprehensive documentation and examples

#### ✅ **Cost-Effective**

- Pay-per-use pricing model
- No setup fees or monthly subscriptions
- Efficient processing with minimal compute usage

#### ✅ **Developer-Friendly**

- Clean, structured data output
- RESTful API compatibility
- Extensive use case examples

### 🚀 Getting Started

1. **Sign up** for an Apify account
2. **Find** the "Macys Store By Proximity" actor in the Apify Store
3. **Configure** your input parameters (latitude, longitude, radius)
4. **Run** the actor and retrieve your store data
5. **Integrate** the results into your application

### 💡 Pro Tips

- **Optimize Radius**: Use smaller radius values in dense urban areas, larger ones in rural areas
- **Cache Results**: Store results temporarily to reduce API calls for repeated queries
- **Batch Processing**: Process multiple locations efficiently by running the actor in sequence
- **Error Handling**: Always check for successful responses before processing data

### 🆘 Support & Troubleshooting

#### Common Issues

- **Invalid Coordinates**: Ensure latitude/longitude are in decimal degree format
- **Radius Format**: Use "M" prefix followed by number (e.g., "M100")
- **No Results**: Try increasing radius if no stores found in specified area

#### Error Messages

- `Please provide the latitude parameter`: Latitude input is missing or invalid
- `Please provide the longitude parameter`: Longitude input is missing or invalid
- `Please provide the radius parameter`: Radius input is missing or invalid

### 📈 SEO Keywords

Macy's store locator, department store finder, retail location API, store proximity search, Macy's near me, retail analytics, location-based services, store hours API, geographic store search, retail automation, e-commerce integration, store locator tool, Macy's API, retail data extraction, location intelligence

***

For additional support, refer to the Apify documentation or contact us.

# Actor input Schema

## `latitude` (type: `string`):

Latitude in decimal degrees (-90 to 90). Example: '40.7500'

## `longitude` (type: `string`):

Longitude in decimal degrees (-180 to 180). Example: '-73.9967'

## `radius` (type: `string`):

Search radius with unit prefix. 'M' for meters, 'K' for kilometers. Example: 'M100'

## Actor input object example

```json
{
  "latitude": "40.7500",
  "longitude": "40.7500",
  "radius": "M100"
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "latitude": "40.7500",
    "longitude": "40.7500",
    "radius": "M100"
};

// Run the Actor and wait for it to finish
const run = await client.actor("pintostudio/macys-store-by-proximity").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "latitude": "40.7500",
    "longitude": "40.7500",
    "radius": "M100",
}

# Run the Actor and wait for it to finish
run = client.actor("pintostudio/macys-store-by-proximity").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "latitude": "40.7500",
  "longitude": "40.7500",
  "radius": "M100"
}' |
apify call pintostudio/macys-store-by-proximity --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,pintostudio/macys-store-by-proximity"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/ZClX53SGhStk32dVZ/builds/1c1D8SjhxolobOH1c/openapi.json
