Geodata Determination – brainX Handbuch

Package: BASIC

1. General

Info

Geodata are data with a geographic reference. They consist of coordinates that describe an exact position on the Earth, as well as additional attributes containing further information about that location.

In brainX, geodata are used for the following functionalities:

Home page - Dashboard Widget - Localisation (country maps)
List view - Geofilter (filter by radius definition)
Action Create Google Maps route plan in List views

Once this setting has been successfully configured, route plans can be created and maps can be displayed showing the exact location of a record (e.g. Organization, Contact, Lead, etc.).

2. Settings for geodata with Google Maps

To obtain geodata in brainX, the following requirements must be met:

The Google Maps Geocoding API key is stored in brainX.
The Google Maps JavaScript API Key is stored in brainX.
The background task Geodata Retrieval must be active.

2.1. Google Maps Geocoding API key

To query geodata, an API key is required, which must be entered in the field “Google Maps Geocoding API key”.

For details on how to generate the API key, refer to the guide Set up the Geocoding API.

For this API key, the “Google Geocoding API” must be activated.

The API key can be restricted to the IP address of the CRM server.

2.2. Google Maps JavaScript API Key

To display Google maps in the CRM, a corresponding API key must be stored in the field “Google Maps JavaScript API Key”. A guide on how to create one is available at https://developers.google.com/maps/documentation/javascript/get-api-key.

Please note that this service is subject to charges. For this key, the Geocoding, Maps JavaScript and Directions API must be activated. It can be restricted via the referring URL of the CRM, e.g. “https://name.brainx.app/*”.

If a key is entered in one of the two input fields, or if one of the two keys is changed, the “Save” button becomes active. To save the changes, simply click the button.

3. Practical examples

1 - A field sales representative plans their daily route

Initial situation: A field sales representative has several customer visits planned in one region on a given day and wants to determine the most efficient order.

Procedure: In the list view of the Organizations module, the desired records are filtered and marked. Using the action Create Google Maps route plan, an optimised route is opened in Google Maps that takes all locations into account.

Result: The representative receives a directly navigable route and saves time on manual planning.

2 - Sales filters customers in the vicinity of a trade fair

Initial situation: Before a trade fair, the sales team wants to identify all customers and prospects within a 50 km radius of the fair location in order to send targeted invitations.

Procedure: In the list view of the Organizations module, the geofilter is used. The address of the fair grounds is entered as the centre point, and the radius is set to 50 km. The filtered records are then processed further for an email campaign.

Result: All relevant contacts in the vicinity are determined within seconds - without manually evaluating addresses.

3 - Geographic analysis of customer density via dashboard

Initial situation: Management wants to see at a glance in which regions most customers are located, in order to deploy sales resources in a targeted manner.

Procedure: The dashboard widget Localisation is embedded on the home page. The widget shows a country map with the geographic distribution of the records.

Result: Regional focal points and gaps in the customer distribution are recognisable at a glance.

4. Frequently asked questions

Do I need a paid Google account for both API keys?

The Google Maps JavaScript API Key is subject to charges, as it uses the Maps JavaScript API, the Geocoding API and the Directions API. However, Google offers a monthly credit that is sufficient for many use cases. The exact cost framework depends on the usage volume and should be clarified directly with Google. It is recommended to set a spending limit in the Google Cloud account.

Can I use a single API key for both fields?

In principle, it is technically possible to create a key that has all required APIs activated. However, it is advisable to use two separate keys and restrict each to the permitted IP address or referring URL in order to prevent misuse.

What happens if the background task “Geodata Retrieval” is not active?

Without an active background task, no geodata are determined for records. In this case, the geofilter, route planning and location maps are not available. The background task can be activated in the settings item Background tasks.

Why are no geodata displayed for some records?

Geodata are determined based on the stored address of a record. If the address is incomplete, incorrect or cannot be resolved unambiguously, no coordinate can be determined. It is advisable to maintain the street, postcode, town and country completely.

Can the API key be restricted to certain accesses?

Yes. The Google Maps Geocoding API key can be restricted to the IP address of the CRM server. The Google Maps JavaScript API Key can be restricted via the referring URL of the brainX instance (e.g. https://name.brainx.app/*). These restrictions are recommended to prevent unauthorised use of the key.