AI Location Intelligence Analyzer

A production-ready Apify Actor that analyzes multiple locations for business suitability using OpenStreetMap data and OpenAI GPT-4o.

🎯 What It Does

This Actor converts Google Maps URLs into actionable location intelligence by:

• Extracting coordinates from Google Maps URLs
• Using AI to select relevant OpenStreetMap data layers
• Fetching nearby points of interest (POIs) from OpenStreetMap
• Analyzing location suitability with GPT-4o
• Generating a comprehensive suitability score (1-10)

📊 Output

Each analyzed location returns:

• Score: Overall suitability (1-10)
• Footfall: Expected foot traffic (Low/Medium/High)
• Competition: Competitive density (Low/Medium/High)
• Accessibility: Location accessibility (Poor/Moderate/Good)
• Summary: AI-generated analysis explanation
• POI Counts: Breakdown of nearby points of interest

🚀 Quick Start

1. Installation

$npm install

2. Local Testing

Create an input.json file:

{
  "locationUrls": [
    "https://maps.google.com/?q=12.9716,77.5946",
    "https://www.google.com/maps/@40.7128,-74.0060,15z"
  ],
  "businessDescription": "restaurant",
  "radiusMeters": 1000,
  "openaiApiKey": "your_openai_api_key_here",
  "model": "gpt-4o",
  "testMode": false
}

Run locally:

$npm start

3. Test Mode

To test without API calls:

{
  "businessDescription": "restaurant",
  "testMode": true
}

📝 Input Parameters

Parameter	Type	Required	Default	Description
locationUrls	array	✅	-	List of Google Maps URLs with coordinates
businessDescription	string	✅	-	Business type (e.g., "restaurant", "gym")
radiusMeters	number	❌	1000	Search radius in meters (100-10000)
testMode	boolean	❌	false	Run with mock data (no API calls)

🔐 Environment Variables

These must be set in Actor Settings (not in input):

Variable	Required	Default	Description
OPENAI_API_KEY	✅	-	Your OpenAI API key (get at https://platform.openai.com/api-keys)
OPENAI_MODEL	❌	gpt-4o	OpenAI model (gpt-4o, gpt-4o-mini, gpt-3.5-turbo)

🌍 Supported URL Formats

• https://maps.google.com/?q=12.9716,77.5946
• https://www.google.com/maps/@12.9716,77.5946,15z
• https://maps.google.com/?ll=12.9716,77.5946

💰 Pricing

This Actor uses pay-per-event pricing:

• Event: location-analysis
• Charged: Only when analysis completes successfully
• Test mode: Free (no charges)

🛡️ Error Handling

• Failed coordinate parsing → Skips URL with warning
• Overpass API errors → Continues with next location
• OpenAI API errors → Falls back to rule-based analysis
• Never crashes the Actor

⚡ Performance

• Processes locations sequentially
• 2-second delay between requests (respects Overpass rate limits)
• 30-second timeout per Overpass call
• Typical runtime: 1-3 minutes for 5 locations

🔧 Advanced Usage

API Integration

curl https://api.apify.com/v2/acts/YOUR_USERNAME~ai-location-intelligence-analyzer/runs \
  -d '{
    "locationUrls": ["https://maps.google.com/?q=12.9716,77.5946"],
    "businessDescription": "coffee shop",
    "openaiApiKey": "sk-..."
  }' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_APIFY_TOKEN'

Dataset Output

Results are stored in Apify dataset with the following structure:

{
  "latitude": 12.9716,
  "longitude": 77.5946,
  "businessType": "restaurant",
  "score": 8,
  "footfall": "High",
  "competition": "Medium",
  "accessibility": "Good",
  "summary": "Excellent location with high foot traffic...",
  "poiCounts": {
    "restaurants": 25,
    "schools": 8,
    "transport": 12
  }
}

📦 Tech Stack

• Runtime: Node.js 20
• Platform: Apify Actor
• AI: OpenAI GPT-4o
• Data: OpenStreetMap (Overpass API)
• Dependencies:
  • apify - Apify SDK
  • openai - OpenAI API client

🌟 Use Cases

• 🏪 Retail site selection
• 🍽️ Restaurant location analysis
• 🏋️ Fitness center placement
• 💼 Coworking space scouting
• 🏥 Healthcare facility planning
• 🏪 Franchise expansion planning

📋 Examples

Example 1: Analyze Restaurant Locations

Input:

{
  "locationUrls": [
    "https://maps.google.com/?q=12.9716,77.5946",
    "https://www.google.com/maps/@40.7128,-74.0060,15z"
  ],
  "businessDescription": "restaurant",
  "radiusMeters": 1000
}

Environment Variables (set in Actor Settings):

• OPENAI_API_KEY: your_openai_api_key
• OPENAI_MODEL: gpt-4o (optional, default is gpt-4o)

Example 2: Test Mode (Free)

{
  "businessDescription": "coffee shop",
  "testMode": true
}

Example 3: Gym Location Analysis

Input:

{
  "locationUrls": [
    "https://maps.google.com/?q=34.0522,-118.2437"
  ],
  "businessDescription": "gym",
  "radiusMeters": 2000
}

Environment Variables:

• OPENAI_API_KEY: your_openai_api_key
• OPENAI_MODEL: gpt-4o-mini (optional)

Example Output

{
  "latitude": 12.9716,
  "longitude": 77.5946,
  "businessType": "restaurant",
  "score": 8,
  "footfall": "High",
  "competition": "Medium",
  "accessibility": "Good",
  "summary": "Excellent location with high foot traffic and moderate competition. Good accessibility makes it ideal for restaurant business.",
  "poiCounts": {
    "restaurants": 25,
    "schools": 8,
    "transport": 12
  }
}

📄 License

ISC

🤝 Support

For issues or feature requests, please open an issue in the repository.