Module version: auto 
Publisher/Licence: Federico García-Patiño Barbolani / GPL-v3
User interface language: English, Spanish, French
Help/Support: federico.garcí[email protected]
Prerequisites:

• Dolibarr min version: auto
• Dolibarr max version: auto

Install (For Dolibarr v9+):

• Go into menu Home - Setup - Modules - Deploy an external module and submit the zip file
• Module or skin is then available and can be activated.

Install (For Dolibarr v8-):

• Download the archive file of module (.zip file) from web site DoliStore.com
• Put the file into the root directory of Dolibarr.
• Uncompress the zip file, for example with command  unzip module_geoaddresses-1.0.zip
• Module or skin is then available and can be activated.

Introduction

There are some business processes whose efficiency depends on the quality of the information of the postal addresses that are stored for clients, suppliers, contacts, warehouses... Examples of these services would be the optimization of routes in a system of distribution of merchandise, or other marketing actions or corporate communications that are carried out by postal mail (Christmas, congratulations, changes in service conditions...). There are even other utilities, where being able to have quality data on locations allows for much more intuitive and direct data representations than tabular views.

In this way, the geo-location of postal addresses conceptually provides added value on the following chapters:

• Improves data quality through visual validation and adjustment thereof

• Allows the deployment of new services

• Allows the development of new views of the data such cluster reports

The solution

GeoAddresses integrates with the usual components of Dolibarr where postal addresses appear (warehouses or stores, third parties, and contacts) and adds a graphical utility for the automatic capture of information based on existing data, and the subsequent validation workflow of these data allowing manually validations with automatically positioned information. Regardless of the state in which the data is found, it is possible to start consuming the services of the GeoAddresses from the first moment.

Map and location service provider

The services of the GeoAddresses module are based on the integration with the map and location service provider for developers mapbox (mapbox.com), which offers its services free of charge through an API, for all its products in significant ranges of use, which in the case of the consumption of GeoAddresses (fordward geocoding) are in the limit of 50,000 map services and 100,000 monthly geolocation requests (as of 04/03/2022). 

You can consult other service possibilities on the website of the manufacturer mapbox.com indicated above.

GeoAddresses works on the services of mapbox.com and is not responsible for changes in the conditions of service, nor in the technical interfaces used for integration with Dolibarr that this provider may apply to its products in the future.

Installation

To install the GeoAddresses module, follow the usual steps for installing any module in Dolibarr.

Configuration

Before starting to use GeoAddresses it is necessary to complete a user registration process in mapbox.com, from which the necessary information is obtained as a result to be able to consume its services. The registry enables a control panel where it is possible to consult the consumption of the service at all times.

Once the registration is complete, it is necessary to complete the module configuration as shown in the following screen:

Where:

• Projection system: EPSG:3857

• Service URL: https://api.mapbox.com/geocoding/v5 /mapbox.places/

• Name of the parameter for the security token: access_token

• token: the one assigned by mapbox.com in the registry

Use case

After the installation and configuration of GeoAddresses, a tab called “Map” is enabled in the tabs of information from each module involved: warehouses, third parties (customers, potential customers, suppliers), and contacts.

When accessing the content of this tab, the module makes a query to the mapbox address service, processing and sending the data that appears as the postal address of the Dolibarr object, and offers a tentative location on the map. At this time, a record is inserted with the geo data obtained in a "draft" state that can be visually validated by the user.

Access to services

The following screen corresponds to a Dolibarr client, it shows the main functional elements of the integration:

Where

1. Access to services

2. tab Alternative search engine: in the event that it is verified that the automatically calculated location is not valid, it is it is possible to carry out alternative searches and establish the location from this service

3. Placeholder: visually indicates the location. It is possible to fine-tune this marker using “drag & drop” actions. The orange color indicates that the address is not validated, and the green color indicates that the address has been validated.

4. Information panel: offers information on the coordinates (longitude and latitude) in the projection system used.

5. Commands:

1. Validate: indicates that the information is validated

2. Restore position: If a manual change was made, it allows placing the marker in its original position.

Address Validation

Address validation turns the placeholder green. Once an address is validated, it is possible to return to the draft state for correction if an error is subsequently detected.

Good practices

At the time of installation, there is no geographic information available on the existing address database in Dolibarr, so it is advisable to include a visit to the map tab and validate the data of each client. 

For the registration of new clients, it is advisable that the data of the postal addresses follow a clear and clean nomenclature, paying attention to the documentation of the standardized administrative information (city, postal code, province, region, country). As a general rule, the address line of can be specified as follows:

1. Type of road

2. Name of the road

3. Number of the road

4. in a new line additional information (block, floor, stair, door…)