{"id":2185,"date":"2026-04-28T10:07:02","date_gmt":"2026-04-28T10:07:02","guid":{"rendered":"https:\/\/documentation.iqonic.design\/handyman\/?p=2185"},"modified":"2026-05-11T06:04:35","modified_gmt":"2026-05-11T06:04:35","slug":"manage-nearby-providers","status":"publish","type":"post","link":"https:\/\/documentation.iqonic.design\/handyman\/manage-nearby-providers\/","title":{"rendered":"Manage Nearby Providers"},"content":{"rendered":"
\n

1. Overview<\/strong><\/h2>\n\n\n\n

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

This feature enables:<\/p>\n\n\n\n

    \n
  • Map-based provider discovery<\/strong> using latitude<\/strong> and longitude<\/strong><\/li>\n\n\n\n
  • Radius<\/strong> and category filtering<\/strong><\/li>\n\n\n\n
  • Admin-level control<\/strong> to enable or disable the feature globally<\/li>\n\n\n\n
  • Consistent API output<\/strong> for web<\/strong> and mobile<\/strong> consumers<\/li>\n<\/ul>\n\n\n\n

    2. How It Works<\/strong><\/h2>\n\n\n\n

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

    Feature Toggle and Availability<\/strong><\/h3>\n\n\n\n

    The feature can be enabled<\/strong> or disabled<\/strong> from Admin settings<\/strong>.<\/p>\n\n\n\n

    When disabled:<\/p>\n\n\n\n

      \n
    • The Browse Nearby<\/strong> action is hidden in the landing page header<\/strong><\/li>\n\n\n\n
    • Direct access to the nearby page is redirected to the home page<\/strong><\/li>\n<\/ul>\n\n\n\n

      Provider Matching Logic<\/strong><\/h3>\n\n\n\n

      Provider matching is based on these rules:<\/p>\n\n\n\n

      Item<\/th>Description<\/th><\/tr><\/thead>
      Provider role<\/strong><\/td>Only provider accounts<\/strong> are considered<\/td><\/tr>
      Active status<\/strong><\/td>Provider status must be active<\/strong><\/td><\/tr>
      Valid coordinates<\/strong><\/td>Profile must include valid latitude<\/strong> and longitude<\/strong><\/td><\/tr>
      Distance check<\/strong><\/td>Distance must be \u2264 requested radius<\/strong><\/td><\/tr>
      Service availability<\/strong><\/td>Provider must have at least one active service<\/strong><\/td><\/tr>
      Subscription mode<\/strong><\/td>Provider must be subscribed<\/strong> when subscription earning type is enabled<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

      3. User Roles & Access<\/strong><\/h2>\n\n\n\n

      3.1 Visitor \/ Customer<\/strong><\/h3>\n\n\n\n
        \n
      • Can open the Nearby Providers page<\/strong><\/li>\n\n\n\n
      • Can filter by category<\/strong> and search radius<\/strong><\/li>\n\n\n\n
      • Can view provider cards<\/strong><\/li>\n\n\n\n
      • Cannot manage feature settings<\/strong><\/li>\n\n\n\n
      • Authorization:<\/strong> Public read-only discovery flow<\/strong><\/li>\n<\/ul>\n\n\n\n

        3.2 Admin<\/strong><\/h3>\n\n\n\n
          \n
        • Can enable\/disable<\/strong> the feature in Other Settings<\/strong><\/li>\n\n\n\n
        • Can configure map defaults<\/strong> via Site Setup<\/strong><\/li>\n\n\n\n
        • Controls provider data quality<\/strong><\/li>\n\n\n\n
        • Must configure Google Maps API key<\/strong> with Billing enabled<\/strong><\/li>\n\n\n\n
        • Authorization:<\/strong> Admin panel access<\/strong><\/li>\n<\/ul>\n\n\n\n

          3.3 Provider<\/strong><\/h3>\n\n\n\n
            \n
          • Appears in results only when eligibility rules<\/strong> are met<\/li>\n\n\n\n
          • Automatically excluded when service status<\/strong> or coordinates<\/strong> are invalid<\/li>\n\n\n\n
          • Cannot change global feature toggle<\/strong><\/li>\n\n\n\n
          • Inclusion is data-driven<\/strong><\/li>\n<\/ul>\n\n\n\n
            \n\n\n\n

            4. Workflows & User Actions<\/strong><\/h2>\n\n\n\n

            4.1 Discovering Nearby Providers<\/strong><\/h3>\n\n\n\n

            User Role:<\/strong> Visitor \/ Customer<\/strong><\/p>\n\n\n\n

              \n
            1. Open website landing page<\/strong><\/li>\n\n\n\n
            2. Click Browse Nearby<\/strong><\/li>\n\n\n\n
            3. Allow location access<\/strong><\/li>\n\n\n\n
            4. Adjust search radius<\/strong> and category filter<\/strong><\/li>\n\n\n\n
            5. View map pins<\/strong> and open provider cards<\/strong><\/li>\n<\/ol>\n\n\n\n

              Result:<\/strong> Users discover nearby active providers<\/strong> for booking decisions.<\/p>\n\n\n\n

              Admin Panel Screen<\/strong><\/h4>\n\n\n\n
                \n
              1. Navigate to Settings > Other Setting<\/strong>s<\/li>\n\n\n\n
              2. Toggle Nearby Provider<\/strong><\/li>\n\n\n\n
              3. Click Save<\/strong><\/li>\n\n\n\n
              4. Update Site Setup values<\/strong><\/li>\n<\/ol>\n\n\n\n

                Result:<\/strong> Feature visibility and search behavior update instantly.<\/p>\n\n\n\n

                \n

                Tip:<\/strong> Keep default latitude<\/strong> and longitude<\/strong> aligned with your primary service region<\/strong>.<\/p>\n<\/blockquote>\n\n\n\n

                5. Settings & Configuration<\/strong><\/h2>\n\n\n\n
                Setting<\/th>Description<\/th><\/tr><\/thead>
                OTHER_SETTING.nearby_provider<\/strong><\/td>Global feature toggle<\/td><\/tr>
                site-setup.radious<\/strong><\/td>Maximum selectable radius<\/td><\/tr>
                site-setup.distance_type<\/strong><\/td>Distance calculation unit<\/td><\/tr>
                site-setup.latitude<\/strong><\/td>Default map center<\/td><\/tr>
                site-setup.longitude<\/strong><\/td>Default map center<\/td><\/tr>
                Google Maps API key<\/strong><\/td>Required for map services<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

                Where to Configure<\/strong><\/h3>\n\n\n\n
                  \n
                • Admin UI \u2192 Settings > Other Settings<\/strong><\/li>\n\n\n\n
                • Admin UI \u2192 Settings > Site Setup<\/strong><\/li>\n<\/ul>\n\n\n\n

                  Admin Setup Checklist<\/strong><\/h3>\n\n\n\n
                    \n
                  1. Enable Nearby Provider toggle<\/strong><\/li>\n\n\n\n
                  2. Configure distance unit<\/strong> and default map center<\/strong><\/li>\n\n\n\n
                  3. Add Google Maps API key<\/strong> with Billing enabled<\/strong><\/li>\n\n\n\n
                  4. Ensure providers have valid coordinates<\/strong><\/li>\n<\/ol>\n\n\n\n
                    \n

                    Note:<\/strong> Billing-enabled Google Maps API key<\/strong> is required for proper latitude\/longitude handling<\/strong>.<\/p>\n<\/blockquote>\n\n\n\n

                    6. Important Notes<\/strong><\/h2>\n\n\n\n
                      \n
                    • The Nearby API endpoint<\/strong> is public<\/strong> and does not require authentication<\/strong>.<\/li>\n\n\n\n
                    • Providers without valid latitude<\/strong> and longitude<\/strong> are excluded automatically<\/strong>.<\/li>\n\n\n\n
                    • In subscription earning mode<\/strong>, only subscribed providers<\/strong> are returned.<\/li>\n\n\n\n
                    • Feature availability depends on nearby_provider toggle<\/strong>.<\/li>\n\n\n\n
                    • Without Google Maps Billing<\/strong>, map services may fail or behave inconsistently<\/strong>.<\/li>\n<\/ul>\n\n\n\n

                      Conclusion<\/strong><\/h2>\n\n\n\n

                      Nearby Providers<\/strong> improves provider discovery<\/strong> using:<\/p>\n\n\n\n

                        \n
                      • Geospatial filtering<\/strong><\/li>\n\n\n\n
                      • Category-based narrowing<\/strong><\/li>\n\n\n\n
                      • Configurable radius controls<\/strong><\/li>\n<\/ul>\n\n\n\n

                        It ensures:<\/p>\n\n\n\n

                          \n
                        • Nearest-first provider discovery<\/strong><\/li>\n\n\n\n
                        • Admin-controlled rollout<\/strong><\/li>\n\n\n\n
                        • Structured API output<\/strong> for frontend<\/strong> and mobile apps<\/strong><\/li>\n<\/ul>\n\n\n\n

                          Related Features<\/strong><\/h2>\n\n\n\n
                            \n
                          • Nearby Providers \u2013 Client Setup and Operations Guide<\/strong><\/li>\n\n\n\n
                          • Nearby Providers \u2013 User Guide<\/strong><\/li>\n<\/ul>\n\n\n\n

                            <\/p>\n<\/div>","protected":false},"excerpt":{"rendered":"

                            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: 2. How It Works The feature starts from a public web map screen where users search for providers around […]<\/p>\n","protected":false},"author":11,"featured_media":0,"parent":259,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[],"class_list":["post-2185","post","type-post","status-publish","format-standard","hentry","category-handyman-services"],"featured_image_src":null,"author_info":{"display_name":"laraveladminiq","author_link":"https:\/\/documentation.iqonic.design\/handyman\/author\/laraveladminiq\/"},"children":[],"_links":{"self":[{"href":"https:\/\/documentation.iqonic.design\/handyman\/wp-json\/wp\/v2\/posts\/2185","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/documentation.iqonic.design\/handyman\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/documentation.iqonic.design\/handyman\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/documentation.iqonic.design\/handyman\/wp-json\/wp\/v2\/users\/11"}],"replies":[{"embeddable":true,"href":"https:\/\/documentation.iqonic.design\/handyman\/wp-json\/wp\/v2\/comments?post=2185"}],"version-history":[{"count":9,"href":"https:\/\/documentation.iqonic.design\/handyman\/wp-json\/wp\/v2\/posts\/2185\/revisions"}],"predecessor-version":[{"id":2201,"href":"https:\/\/documentation.iqonic.design\/handyman\/wp-json\/wp\/v2\/posts\/2185\/revisions\/2201"}],"up":[{"embeddable":true,"href":"https:\/\/documentation.iqonic.design\/handyman\/wp-json\/wp\/v2\/posts\/259"}],"wp:attachment":[{"href":"https:\/\/documentation.iqonic.design\/handyman\/wp-json\/wp\/v2\/media?parent=2185"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/documentation.iqonic.design\/handyman\/wp-json\/wp\/v2\/categories?post=2185"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/documentation.iqonic.design\/handyman\/wp-json\/wp\/v2\/tags?post=2185"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}