InsightMaps

Appearance

ArcGIS Services Setup ​

Configure your ArcGIS API key to unlock powerful location services including address search and route analysis.

Overview ​

InsightMaps integrates with ArcGIS services to provide:

  • Address Search (Geocoding) - Find locations using ArcGIS World Geocoding Service
  • Route Analysis - Calculate optimal routes and directions
  • Additional Services - Access to Esri's location services

Requirement: An ArcGIS API key is required to use these services.

[insert image later]

What You'll Need ​

ArcGIS API Key ​

An API key from Esri's ArcGIS Platform that grants access to:

  • World Geocoding Service (address search)
  • Network Analyst Service (routing)
  • Other ArcGIS location services

How to Get an API Key:

  1. Visit developers.arcgis.com
  2. Create a free ArcGIS Developer account (if you don't have one)
  3. Navigate to API Keys section
  4. Create a new API key
  5. Configure key permissions (enable Geocoding and Routing)
  6. Copy the API key

[insert image later]

API Key Permissions Required:

  • ✅ Geocoding - For address search and location finding
  • ✅ Routing - For route analysis and directions
  • ✅ Basemaps (optional) - For ArcGIS basemap services

Cost: ArcGIS Developer accounts include free monthly credits. Monitor usage in your Esri dashboard.

Admin Setup (Configure API Key) ​

Administrators configure the ArcGIS API key once in the admin console. All users then benefit from these services.

Step 1: Access Admin Console ​

  1. Sign in at www.insightmaps.app
  2. Open the Admin Console at console.insightmaps.app
  3. Navigate to Settings or Configuration section
  4. Find ArcGIS Services or API Keys settings

[insert image later]

Step 2: Enter API Key ​

  1. Locate the "ArcGIS API Key" field
  2. Paste your API key from ArcGIS Developers
  3. Click "Save" or "Update"

[insert image later]

Security Note: API keys should be kept secure. Only system administrators should have access to view or modify the API key.

Step 3: Test Configuration ​

After saving the API key:

  1. Open the Map Application at map.insightmaps.app
  2. Try the Search widget with an address
  3. Try the Route Analysis tool (if available)
  4. If services work, configuration is successful

[insert image later]

Features Enabled by API Key ​

1. Address Search (Geocoding) ​

What it enables: ArcGIS World Geocoding Service for address search

How users access it:

  1. Click Search icon in toolbar
  2. Type an address (e.g., "123 Main St, Hobart TAS")
  3. Select from suggestions
  4. Map zooms to location

Supported searches:

  • Street addresses worldwide
  • Places and landmarks
  • Postal codes
  • Coordinates
  • Business names

Admin configuration:

  • Add "Locator" search source in Admin Console
  • URL: ArcGIS World Geocoding Service
  • API key automatically applied

[insert image later]

Reference: ArcGIS World Geocoding Service

2. Route Analysis ​

What it enables: Network Analyst routing service for directions and route optimization

How users access it:

  1. Open Route Analysis tool (if available in your deployment)
  2. Add stops by clicking map or searching addresses
  3. Click "Solve Route"
  4. View turn-by-turn directions and route on map

Routing capabilities:

  • Multi-stop route optimization
  • Turn-by-turn directions
  • Drive time and distance calculations
  • Avoid areas (barriers)
  • Travel modes (driving, walking, trucking)

Admin configuration:

  • Route analysis automatically uses configured API key
  • No additional setup required

[insert image later]

Reference: ArcGIS Network Analyst

Managing API Key Usage ​

Monitor Usage ​

ArcGIS API keys have usage limits based on your account plan:

  • Free Tier: Monthly credit allowance
  • Paid Plans: Higher limits with billing

How to monitor:

  1. Log in to developers.arcgis.com
  2. Go to Dashboard
  3. View API key usage statistics
  4. Check geocoding and routing transaction counts

[insert image later]

Usage Tips ​

Optimize geocoding usage:

  • Enable suggestions to reduce full geocoding requests
  • Use layer-based search sources when possible (doesn't use API key)
  • Cache frequently searched locations

Optimize routing usage:

  • Limit number of stops per route
  • Encourage users to plan routes before solving
  • Consider batch routing for multiple routes

Troubleshooting ​

"Search not working" or "No results found" ​

Possible causes:

  • API key not configured
  • API key lacks Geocoding permission
  • API key usage limit exceeded
  • Network connectivity issues

Solutions:

  1. Verify API key is entered in Admin Console
  2. Check API key permissions in ArcGIS Developers
  3. Verify API key hasn't expired
  4. Check usage statistics for limit exceeded
  5. Test API key in ArcGIS Developers playground

"Route analysis failed" ​

Possible causes:

  • API key not configured
  • API key lacks Routing permission
  • API key usage limit exceeded
  • Stops are in unsupported areas

Solutions:

  1. Verify API key has Routing permission enabled
  2. Check usage statistics for limit exceeded
  3. Ensure stops are in areas covered by routing service
  4. Try with fewer stops

"Unauthorized" or "Invalid API key" error ​

Cause: API key is invalid, expired, or incorrectly configured

Solutions:

  1. Verify API key was copied correctly (no extra spaces)
  2. Check API key hasn't been deleted in ArcGIS Developers
  3. Regenerate API key if necessary
  4. Ensure HTTP referrer restrictions match your domain (if configured)

Security Best Practices ​

Protect Your API Key ​

Do:

  • ✅ Store API key securely in admin console only
  • ✅ Limit API key permissions to only what's needed
  • ✅ Monitor usage regularly for unexpected activity
  • ✅ Set HTTP referrer restrictions to your domain
  • ✅ Rotate API keys periodically

Don't:

  • ❌ Share API key in public forums or documentation
  • ❌ Commit API key to version control
  • ❌ Give API key to end users
  • ❌ Enable unnecessary service permissions

[insert image later]

HTTP Referrer Restrictions ​

Configure referrer restrictions in ArcGIS Developers to limit API key usage to your domain:

  1. Go to API key settings in ArcGIS Developers
  2. Add HTTP referrers (e.g., insightmaps.app, map.insightmaps.app, console.insightmaps.app)
  3. API key will only work from listed domains

Alternative: Custom Geocoding Service ​

If you have your own geocoding service or prefer not to use ArcGIS services:

Option 1: Custom GeocodeServer

  • Configure custom GeocodeServer URL in search sources
  • No API key required for self-hosted services
  • Follow ArcGIS REST API specification

Option 2: Layer-Based Search

  • Use layer attribute search (doesn't require API key)
  • Configure search fields in Admin Console
  • Best for searching known datasets (parcels, roads, etc.)

Summary ​

Setup Steps:

  1. Get ArcGIS API key from developers.arcgis.com
  2. Enable Geocoding and Routing permissions
  3. Enter API key in Admin Console settings
  4. Test with address search and route analysis

Features Unlocked:

  • 🔍 Address Search - ArcGIS World Geocoding Service
  • 🗺️ Route Analysis - Network Analyst routing
  • 📍 Place Search - Global places and landmarks

Best Practices:

  • Monitor usage to stay within limits
  • Secure API key (admin-only access)
  • Set HTTP referrer restrictions
  • Use layer search when possible to reduce API calls

Support: For API key issues, contact Esri Support or visit ArcGIS Developers Community