Contacts Route Planner — Mapbox GL

The Problem It Solves

Customer visit planning in Odoo is fragmented. Your contacts live in a list — you know their names and addresses, but not where they cluster geographically or how efficiently you could visit a group of them in a single trip. There is no map, no geographic context, and no quick way to see which customers are near each other on a given day.

Building a customer-visit route compounds the problem. Even with the Route Planner installed, you have to open it, create a new route manually, and type in each contact's name one by one — with nothing to help you decide which contacts to visit together or in what order.

Contacts Route Planner solves both sides at once. It adds a live Mapbox map directly inside the Contacts application — so you can browse your customers geographically, see density patterns, spot coverage gaps, and select exactly who you want to visit right on the map. One action then turns that selection into a fully geocoded, travel-time-aware Customer Visit route, with your chosen stop order preserved and all details configurable before the route is created.

Product Overview

Contacts Route Planner — Mapbox GL is the CRM-to-dispatch bridge for Odoo. It adds three modules on top of the Route Planner Suite, turning the Odoo Contacts application into a map-first customer browser and wiring selected contacts directly into the Route Planner through a one-click wizard.

The result: account managers, field sales, and outreach teams plan their day on a map, pick the customers they want to visit, and get a fully geocoded, travel-time-aware route — ready to review, confirm, and send to the driver or representative's portal.

This page focuses on what Contacts Route Planner adds on top of that suite.

What Contacts Route Planner Adds

Three purpose-built extension modules — one foundation-layer, two application-layer — that turn geocoded records into maps, Odoo Contacts into a map-first application, and selected contacts into routes.

How It Works

The end-to-end workflow from the Contacts app to a dispatched customer-visit route:

1. Open the Contacts application and switch to the Map view from the view switcher.
2. Geocoded contacts appear as color-coded markers; zoom in and out, hover for popups, click markers or sidebar entries for full details.
3. Select the contacts you want to visit — Shift-click individual markers, or hold Shift and drag a rectangle to box-select a whole area at once. Selection also works in the classic list view.
4. Click Action → Route Planner. A wizard opens with your selected contacts already loaded as waypoints, in the order you selected them.
5. Review the route: drag to reorder waypoints, set the route name and optional driver/vehicle/departure date, and adjust the description.
6. Click Create Route. The wizard creates a Customer Visit route, auto-selecting the Directions API so your chosen stop order is preserved.
7. The route opens on an interactive Mapbox map with travel time and distance per segment, ready to confirm and dispatch to the driver or field rep's mobile-friendly portal.

Validation runs automatically along the way: contacts without coordinates or with duplicate coordinates are surfaced in an orange warning banner in the wizard with the affected names, route creation is blocked until you resolve the issues, and the Mapbox 25-waypoint limit is enforced with a clear message. The Route Planner action only appears for users with the Route Planner User role, so the workflow respects your existing access controls.

Key Features

All features below are additions contributed by the three Contacts Route Planner extension modules on top of the underlying Route Planner Suite.

Geolocate Map View (Foundation)

• Coordinate-Based Mapping — Display any Odoo model with latitude and longitude fields as point markers — no GeoJSON conversion needed.
• Smart Overlap Handling — Markers at the same location are automatically spread in a ~10 meter circular pattern so every record stays individually clickable.
• Connection Lines — Dotted lines link distributed markers back to their shared location at zoom level 17+; line color matches the marker's stroke color.
• Shifted Marker Indicator — A blue info icon in the popup of any offset marker, with a tooltip explaining the shift and pointing to the original location.
• Optional Heatmap Layer — Visualize point density at zoom levels 0-9, fading out as you zoom in (mutually exclusive with clustering).
• Optional Clustering Layer — Groups markers into numbered clusters up to zoom 14; clusters are color- and size-coded by record count (blue <100, yellow 100-750, pink 750+).
• Box-Zoom Selection — Hold Shift and drag a rectangle to select every marker within it — including individual records inside visible clusters (up to 100 per cluster).
• Shift+Click Selection — Toggle markers in and out of the current selection directly on the map, without opening the record.
• Color-Coded Markers — Style markers using Odoo color index integers, named colors, or hex codes via a configurable field.
• Human-Readable Coordinates — Coordinates displayed with N/S/E/W indicators and 6-decimal precision (~0.11 m) in popups and the sidebar.
• Declarative XML Configuration — Define new map views with a simple block; install-time validation catches missing field declarations.
• Performance Optimized — Batch marker processing (100/batch), throttled mouse events (100 ms), and debounced map operations for smooth interaction with thousands of records.

Contacts Map Experience

• Map View in Contacts — A dedicated Map view in the Contacts view switcher, available alongside list, kanban, and form, with no extra setup needed.
• Contact Avatars — Photos visible in both the sidebar list (24×24) and the marker popup (64×64) for instant visual recognition.
• Formatted Address in Sidebar — Full address shown as the subtitle under each contact name in the sidebar — no need to open the form.
• Custom Marker Colors per Contact — A Marker Color field on the contact form lets you assign a color for visual grouping (customers vs. suppliers, priority tiers, territories, etc.).
• Color Picker in Geo Localization Section — Straightforward color selection on the contact form without needing to know color codes.
• Always-On Clustering — Clustering is enabled by default in the Contacts map so large contact bases stay readable at any zoom level.
• Overlap Separation for Shared Addresses — Contacts at the same coordinates are spread in a circle and linked by dotted lines, so every contact at a shared address remains selectable.
• Automatic Geocoding — A scheduled task runs every 12 hours and processes up to 80 contacts per run, auto-assigning coordinates to contacts that have an address but no latitude/longitude yet.
• Multi-Selection — Shift-click individual markers or Shift-drag a rectangle to select groups of contacts directly on the map. Works with clusters too.

Route Creation From Contacts

• Route Planner Action — A dedicated action on the Contacts list and map views that opens a wizard pre-populated with the selected contacts as waypoints.
• Preserved Selection Order — Contacts are added in the order they were selected; the first contact becomes the departure point, and the rest become the ordered stops.
• Customer Visit Route Type — Routes are automatically typed as "Customer Visit" with a default service duration of 30 minutes per stop; vehicle, driver, and departure date are all optional at confirmation.
• Directions API Routing — The wizard sets the navigation API to Directions, so the stop order as arranged by the user is preserved — no automatic reordering.
• Reorderable Waypoints — Drag-and-drop the wizard's stops list to fine-tune the sequence before creating the route.
• Smart Default Route Details — Route name defaults to "Customer visit by {current user}"; departure date defaults to now. Responsible, vehicle, driver, and description can all be set upfront in the wizard.
• Geolocation Validation Warning — An orange warning banner surfaces contacts with missing or duplicate coordinates (listed by name) and blocks route creation until all issues are resolved. A Geolocalize button in the banner auto-geocodes contacts that are missing coordinates in one click.
• Minimum & Maximum Stop Enforcement — At least 2 waypoints required; maximum 25 to match the Mapbox API limit, each with clear error messages.
• Geolocated Contacts Only — The stop contact field in the wizard is filtered to only partners with non-zero latitude and longitude.
• Access Controlled — The Route Planner action is visible only in list and map views, and only to users with the Route Planner User role or higher.

Use Cases & Benefits

What's in the Bundle

Contacts Route Planner — Mapbox GL is a complete 10-module package. Seven modules come from the Route Planner Suite; the three modules highlighted below are the contacts-specific extensions — one foundation-layer view type, one application-layer Contacts extension, and one route creation bridge.

For a detailed feature breakdown of the six Route Planner Suite modules, see the Route Planner with Mapbox product page.