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

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://beta-securitybyobscurity.apify.com/pintostudio/macys-store-by-proximity.md
- **Developed by:** [Pinto Studio](https://beta-securitybyobscurity.apify.com/pintostudio) (community)
- **Categories:** E-commerce, Developer tools, Other
- **Stats:** 1 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks
- **User rating**: No ratings yet

## Pricing

$4.00 / 1,000 results

This Actor is paid per result. You are not charged for the Apify platform usage, but only a fixed price for dataset items the Actor outputs.

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

# 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("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).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": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=pintostudio/macys-store-by-proximity",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Macys Store By Proximity",
        "description": "Macys Store By Proximity is a powerful Apify actor that helps you find the nearest Macy's department store location based on geographic coordinates.",
        "version": "1.0",
        "x-build-id": "1c1D8SjhxolobOH1c"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/pintostudio~macys-store-by-proximity/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-pintostudio-macys-store-by-proximity",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/pintostudio~macys-store-by-proximity/runs": {
            "post": {
                "operationId": "runs-sync-pintostudio-macys-store-by-proximity",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/pintostudio~macys-store-by-proximity/run-sync": {
            "post": {
                "operationId": "run-sync-pintostudio-macys-store-by-proximity",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "required": [
                    "latitude",
                    "longitude",
                    "radius"
                ],
                "properties": {
                    "latitude": {
                        "title": "latitude",
                        "pattern": "^-?([1-8]?\\d(\\.\\d+)?|90(\\.0+)?)$",
                        "type": "string",
                        "description": "Latitude in decimal degrees (-90 to 90). Example: '40.7500'"
                    },
                    "longitude": {
                        "title": "longitude",
                        "pattern": "^-?(180(\\.0+)?|((1[0-7]\\d)|([1-9]?\\d))(\\.\\d+)?)$",
                        "type": "string",
                        "description": "Longitude in decimal degrees (-180 to 180). Example: '-73.9967'"
                    },
                    "radius": {
                        "title": "radius",
                        "pattern": "^[MK]\\d+$",
                        "type": "string",
                        "description": "Search radius with unit prefix. 'M' for meters, 'K' for kilometers. Example: 'M100'"
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```
