Appearance
Visitor Location
The Visitor Location function detects and provides access to visitor geographic location data through dynamic tags. Version 1.6.1 adds latitude and longitude dynamic tags for precise coordinate access.
What’s New in 1.6.1
- @site(visitor.latitude): New dynamic tag for geographic latitude
- @site(visitor.longitude): New dynamic tag for geographic longitude
Overview
Visitor Location detects the geographic location of site visitors using either browser geolocation or IP-based detection. The location data is then available through dynamic tags for use in templates, widgets, and conditional logic.
Key Features
- Automatic visitor location detection
- Browser geolocation (precise) with IP fallback
- Multiple IP geolocation APIs with consensus
- Configurable cache duration
- Dynamic tags for all location components
- Local IP detection filtering
Available Dynamic Tags
| Tag | Description | Example Output |
|---|---|---|
@site(visitor.location) | Full location string | “Los Angeles, California, United States” |
@site(visitor.city) | City name only | “Los Angeles” |
@site(visitor.state) | State/Region name | “California” |
@site(visitor.country) | Country name | “United States” |
@site(visitor.latitude) | Geographic latitude (NEW) | “34.0522” |
@site(visitor.longitude) | Geographic longitude (NEW) | “-118.2437” |
Setup Instructions
Step 1: Enable the Function
- Navigate to Voxel Toolkit → Functions
- Find Visitor Location in the list
- Toggle the switch to enable
- Click Save Changes
Step 2: Configure Settings
- Click the settings icon next to Visitor Location
- Select detection mode (IP or Browser)
- Set cache duration
- Save your changes
Configuration Settings
| Setting | Description | Default |
|---|---|---|
| Detection Mode | IP-based or Browser geolocation | IP |
| Cache Duration | How long to cache location data (seconds) | 3600 (1 hour) |
Detection Modes
IP Mode (Default):
- Uses multiple free geolocation APIs (geojs.io, ipapi.co, ip-api.com)
- Consensus-based results for accuracy
- No user permission required
- City-level accuracy
Browser Mode:
- Uses HTML5 Geolocation API
- Prompts user for permission
- Precise coordinates (street-level)
- Falls back to IP mode if denied
Using Latitude & Longitude (New)
The new latitude and longitude tags enable powerful location-based functionality:
Pre-fill Search Coordinates
Use the coordinates to pre-fill location search fields or map center points.
Distance Calculations
Pass coordinates to external services for distance-based sorting or filtering.
Map Integration
Center maps on the visitor’s location using the coordinate tags.
Example Usage
Your coordinates: @site(visitor.latitude), @site(visitor.longitude)Use Cases
Personalized Welcome
Display “Welcome visitor from [City]!” messages using the city tag.
Location-Based Content
Show different content or promotions based on visitor location using visibility conditions.
Auto-Center Maps
Use latitude and longitude to automatically center maps on the visitor’s location.
Pre-fill Search Forms
Pre-populate location search fields with the visitor’s detected location.
Nearby Listings
Use coordinates to sort or filter listings by proximity to the visitor.
Troubleshooting
Tags Return Empty
- Check that Visitor Location function is enabled
- Wait for initial detection (may take a moment)
- Local development IPs (127.0.0.1, localhost) are filtered out
- Try clearing the cache
Inaccurate Location
- IP detection is typically city-level accurate
- VPNs and proxies affect IP-based detection
- Switch to Browser mode for more precision
- Mobile networks may show ISP location instead
Browser Mode Permission Denied
- Falls back to IP detection automatically
- Ensure site is served over HTTPS
- User may have blocked location for all sites