Handyman Service - Documentation

Manage Nearby Providers

1. Overview

Nearby Providers helps visitors discover active providers around a selected location using a distance-based map search. It is available in the Handyman Service Platform and is controlled by an admin toggle.

This feature enables:

  • Map-based provider discovery using latitude and longitude
  • Radius and category filtering
  • Admin-level control to enable or disable the feature globally
  • Consistent API output for web and mobile consumers

2. How It Works

The feature starts from a public web map screen where users search for providers around their current or selected location. The system uses location coordinates, distance, and category filters to return the nearest active providers first.

Feature Toggle and Availability

The feature can be enabled or disabled from Admin settings.

When disabled:

  • The Browse Nearby action is hidden in the landing page header
  • Direct access to the nearby page is redirected to the home page

Provider Matching Logic

Provider matching is based on these rules:

ItemDescription
Provider roleOnly provider accounts are considered
Active statusProvider status must be active
Valid coordinatesProfile must include valid latitude and longitude
Distance checkDistance must be ≤ requested radius
Service availabilityProvider must have at least one active service
Subscription modeProvider must be subscribed when subscription earning type is enabled

3. User Roles & Access

3.1 Visitor / Customer

  • Can open the Nearby Providers page
  • Can filter by category and search radius
  • Can view provider cards
  • Cannot manage feature settings
  • Authorization: Public read-only discovery flow

3.2 Admin

  • Can enable/disable the feature in Other Settings
  • Can configure map defaults via Site Setup
  • Controls provider data quality
  • Must configure Google Maps API key with Billing enabled
  • Authorization: Admin panel access

3.3 Provider

  • Appears in results only when eligibility rules are met
  • Automatically excluded when service status or coordinates are invalid
  • Cannot change global feature toggle
  • Inclusion is data-driven

4. Workflows & User Actions

4.1 Discovering Nearby Providers

User Role: Visitor / Customer

  1. Open website landing page
  2. Click Browse Nearby
  3. Allow location access
  4. Adjust search radius and category filter
  5. View map pins and open provider cards

Result: Users discover nearby active providers for booking decisions.

Admin Panel Screen

  1. Navigate to Settings > Other Settings
  2. Toggle Nearby Provider
  3. Click Save
  4. Update Site Setup values

Result: Feature visibility and search behavior update instantly.

Tip: Keep default latitude and longitude aligned with your primary service region.

5. Settings & Configuration

SettingDescription
OTHER_SETTING.nearby_providerGlobal feature toggle
site-setup.radiousMaximum selectable radius
site-setup.distance_typeDistance calculation unit
site-setup.latitudeDefault map center
site-setup.longitudeDefault map center
Google Maps API keyRequired for map services

Where to Configure

  • Admin UI → Settings > Other Settings
  • Admin UI → Settings > Site Setup

Admin Setup Checklist

  1. Enable Nearby Provider toggle
  2. Configure distance unit and default map center
  3. Add Google Maps API key with Billing enabled
  4. Ensure providers have valid coordinates

Note: Billing-enabled Google Maps API key is required for proper latitude/longitude handling.

6. Important Notes

  • The Nearby API endpoint is public and does not require authentication.
  • Providers without valid latitude and longitude are excluded automatically.
  • In subscription earning mode, only subscribed providers are returned.
  • Feature availability depends on nearby_provider toggle.
  • Without Google Maps Billing, map services may fail or behave inconsistently.

Conclusion

Nearby Providers improves provider discovery using:

  • Geospatial filtering
  • Category-based narrowing
  • Configurable radius controls

It ensures:

  • Nearest-first provider discovery
  • Admin-controlled rollout
  • Structured API output for frontend and mobile apps

Related Features

  • Nearby Providers – Client Setup and Operations Guide
  • Nearby Providers – User Guide