How EspoCRM Google Maps integration shows addresses on a map
Sales and service staff often need to see where their accounts and contacts are before a visit, a dispatch or a territory review. EspoCRM supports Google Maps out of the box, so this does not require an official extension. You enable it by entering a Google Maps API key at Administration > Integrations > Google Maps. The key must have the Geocoding, Maps JavaScript and Maps Static APIs enabled in your Google Cloud project, because EspoCRM uses them to convert addresses to coordinates, draw interactive maps and render static map images.
Every Address field in EspoCRM has a matching Map field. To show a location, add that Map field to the detail layout of the entity, such as Account or Contact, using the layout editor in the Entity Manager. Staff then see the map on the record itself. Decide early which address fields matter for each entity, since a company may need a billing address map and a shipping address map on the same account. Confirm which field types and entities support maps in the version you run, because coverage can change between releases.
Map dashlets and Map IDs are the parts of this feature most likely to differ by installed version. Before you promise a dashboard view of accounts by location, check the EspoCRM maps documentation for your release and test the dashlet with a small set of real records. Also confirm with your Google Cloud administrator how the API key is restricted and who pays for usage under your billing account, because geocoding and map loads are billed by Google and cost depends on how often records are viewed and imported.
What you need before enabling Google Maps in EspoCRM
Enabling Google Maps in EspoCRM depends on decisions made in three places: Google Cloud, the EspoCRM instance itself, and the address data your teams already keep. Check each of the items below before you open the Maps settings, because a missing API or a blocked outbound connection shows up later as a map that never loads.
Google Cloud project with billing
Create or choose a Google Cloud project that your organization controls and that will own the API key. Google requires an active billing account on the project before the Maps APIs return results, so confirm who holds billing ownership and who receives invoice alerts. Confirm Google's current billing and quota terms in your own Google Cloud console rather than relying on figures from this page, since they can change.
Three Google Maps APIs enabled
EspoCRM needs the Geocoding API, the Maps JavaScript API and the Maps Static API enabled on the same project as the key. Enabling only the JavaScript API is a common mistake: addresses will display, but coordinates will not be resolved and static map images will fail. Review the API list in the EspoCRM maps documentation before you create the key.
API key restrictions planned
Decide how the key will be restricted before you paste it into Administration > Integrations > Google Maps. Restrictions by API and by the server address that calls Google reduce the damage if the key leaks from the EspoCRM configuration. Record who can rotate the key, because a rotated key must be updated in EspoCRM before the old one is disabled.
Administrator account in EspoCRM
Only an administrator can add the Google Maps API key and change the detail layouts that add map fields. Name the person who will own this configuration and confirm that they have admin access in the instance where the change will be made. Use a named admin account rather than a shared login, since the EspoCRM security guidance recommends avoiding admin accounts for daily work.
Running instance with outbound HTTPS
Confirm the EspoCRM version and its supported PHP and database versions against the EspoCRM server configuration docs before you start, and check that cron or a scheduled task is running. The server must be able to reach Google over outbound HTTPS, and browsers of end users must load Google's map scripts, so proxies and firewall rules on both sides need review.
Clean address data on entities
Maps are only as useful as the address fields behind them. Audit Account and Contact addresses for missing country codes, inconsistent formats and duplicate entries before enabling maps, since geocoding errors will appear on records that look correct. Decide which address fields your teams will rely on for routing and territory views, and agree on who fixes records that fail to resolve.
Configuring the Google Maps API key and APIs in EspoCRM
This sequence takes you from a Google Cloud project to a working map on an EspoCRM record, with a check at each stage so a failure is caught where it happens. Google Cloud and EspoCRM administrators should run it together, since the key is created in one and entered in the other.
Select or create the Google Cloud project
The Google Cloud administrator selects an existing project or creates a new one that will own the Maps billing and the API key. Use a project the organization controls and that has billing enabled, since Google requires billing before the Maps APIs return results. Confirm the project appears in the project selector and that the billing account linked to it is the one your finance team expects to be charged. The step is complete when the project is active and billing shows as enabled.
Enable the Geocoding, Maps JavaScript and Maps Static APIs
In the same project, open the API library and enable the three APIs EspoCRM needs for maps: Geocoding API, Maps JavaScript API and Maps Static API. Geocoding converts addresses to coordinates, the JavaScript API renders the interactive map on records, and the Static API produces the image used in places where a full map is not loaded. Check the enabled APIs list and confirm all three are present. If any is missing, the map or the address lookup will fail without an obvious error in the record.
Create the Maps API key
Create an API key from the Credentials page of the same project. Copy the key once it is generated and store it in your secrets manager or password vault, because the console will not show the full value again later. Record which project and billing account the key belongs to in your configuration notes. The step is complete when the key exists in the Credentials list and you have the value available for entry in EspoCRM.
Restrict the API key to the required APIs and your domain
Edit the key and restrict it to the three enabled APIs, so the key cannot be used for other Google services if it leaks. Where your setup allows it, add application restrictions that match the EspoCRM host, such as the URL where users reach the CRM. Test that the restricted key still works in the next steps, since an overly narrow restriction is a common reason maps stop rendering. Confirm the saved restriction lists only the three APIs before you move on.
Enter the key in EspoCRM Google Maps settings
As an EspoCRM administrator, go to Administration, then Integrations, then Google Maps, and paste the API key into the field. Save the settings and reload the page to confirm the value persisted. Then geocode a test address by saving an account or contact record with a full postal address, and check that the record's map field populates with coordinates. If the coordinates do not appear, check the key, the enabled APIs and the project billing status before retrying.
Add Map fields to the detail layout
Each EspoCRM Address field has a matching Map field. Open the Layout Manager for the target entity, such as Account or Contact, and add the Map field to the detail layout in the position where users will look for it. Save the layout and open a record with a populated address to confirm the map renders. Repeat for each entity that needs the view, because layouts are set per entity. The step is complete when the map displays on a record in the browser you use for daily work.
Confirm Map ID and dashlet requirements in the official docs
Before you roll this out, check the official EspoCRM maps documentation for any requirement that applies to your Google setup, including whether a Map ID is needed for the map styling you plan to use and how map dashlets are configured. Treat the documentation as the authority for those settings, since they can change between EspoCRM and Google releases. Note the version of EspoCRM you tested against, and repeat the record check after any upgrade. Your run is complete when you have documented the answers and the test results for your environment.
How address fields become map fields on layouts
Every Address field group in EspoCRM has a corresponding Map field, and that Map field appears on a record only after you add it to a detail layout. The map is therefore a presentation choice made per entity and per layout, not a property that switches on for every address automatically. Before you add maps, list the entities that hold address data (accounts and contacts are the usual candidates, leads often have one, and custom entities built in the Entity Manager may too) and decide which of them staff need to see geographically. Then, for each entity, check which layouts your sales, service and field roles actually use, because a map added to a layout that nobody opens delivers nothing. Confirm the exact field names in your own instance, since they follow the address groups you have configured.
Address completeness determines what the map can show. A Map field can only display a location when the underlying address fields contain enough information for the lookup to succeed, so records with partial addresses, missing postal codes or free-text entries in the wrong field may show nothing or a less precise location than users expect. Run a short data check on a sample of records from each entity before rollout, and compare what the map displays with the address the user sees in the standard fields. The EspoCRM maps documentation describes how the Google Maps lookup works, so read it alongside your own test records rather than assuming the map will resolve every format your team enters.
A map on a layout is a display of the stored address, not a change to it. Adding or removing the Map field from a detail layout does not alter address values, and viewing a map does not write coordinates or corrected addresses back to the record. Keep this in mind when you plan data cleanup: standardizing addresses is a separate task from adding maps, and it should be done in the address fields themselves, through forms, imports or your data governance process. Also note that the map is only as good as your address data, so decide early who owns address quality for accounts and contacts.
Which address fields feed which map fields
This table matches each entity that carries an address to its address field group, the map field that displays it, the layout where the map is placed, and the Google APIs the map depends on. EspoCRM creates a map field for each address field, so the map must be added to the detail layout of the same entity. Confirm the exact field names and which entities offer address fields in your own instance, because standard fields and layout options vary by entity and version.
| Entity | Address field group | Map field and layout placement | Google APIs required |
|---|---|---|---|
| Account | Billing and shipping address groups, where present in your instance | One map field per address group, added to the Account detail layout in the Layout Manager | Geocoding, Maps JavaScript and Maps Static APIs |
| Contact | Primary address group, where present in your instance | Map field matching the address group, added to the Contact detail layout | Geocoding, Maps JavaScript and Maps Static APIs |
| Lead | Primary address group, where present in your instance | Map field matching the address group, added to the Lead detail layout | Geocoding, Maps JavaScript and Maps Static APIs |
| Custom entity created in the Entity Manager | Address field group that you add to the entity before mapping | Map field appears only after the address field exists, then is added to the entity's detail layout | Geocoding, Maps JavaScript and Maps Static APIs |
| Other standard entities with an address group | Confirm each one in Entity Manager before planning the layout | Check whether the entity offers a map field and whether its detail layout is editable for your roles | Geocoding, Maps JavaScript and Maps Static APIs |
Map fields on detail layouts or map dashlets
A Map field sits on the detail layout of an entity and mirrors one of its Address fields, so the map appears next to the address the user already reads. This placement suits people who work one record at a time, such as account owners preparing a visit or service agents checking where a customer is before a call. Setup is small, but it depends on the address data being complete.
- Typical user: account owners, field sales staff and service agents who open a single account or contact to plan the next step.
- Data shown: only the address stored on that record, displayed in the context of its other fields.
- Setup effort: add the Map field to the detail layout for each entity that needs it, and confirm the Address field it mirrors is maintained by the teams who enter data.
- Permissions: the map is visible only to users who can see both the record and the underlying address, so compare the field permissions for the map field and the address field.
- Checks: open one record with a complete address, one with a partial address and one with no address, and confirm the map renders correctly for each user role.
Before rollout, review address quality on the entities involved, because a map cannot correct a mistyped or incomplete address.
A map dashlet places records from a list on a user dashboard so the viewer sees where a group of accounts or contacts sits. This placement suits managers and planners who need the spread of a territory rather than the detail of one record. Before designing around it, confirm dashlet availability and any Map ID requirements in the EspoCRM maps documentation for the version you run.
- Typical user: regional managers, dispatchers and territory planners who scan many records and decide where to focus.
- Data shown: the records matched by the dashlet's entity and filter, plotted from their addresses. Check the dashlet's own limits for large sets.
- Setup effort: create a saved list filter for the territory, add the dashlet to the user dashboard and set its options for your version.
- Map IDs: confirm in the maps documentation whether a Map ID is required for the styling or features you plan to use, and who creates it in your Google Cloud project.
- Checks: compare the plotted count with the list view for the same filter, and test the dashboard as a user whose team access is restricted.
Confirm dashlet availability for your installed version before promising this view to managers, since it is the placement most likely to depend on version-specific behavior.
Most deployments need both placements, but they serve different questions and carry different operating costs. The platform owner or CRM administrator should decide placement by the question each user asks: what is at this record, or what is across this group. Both placements call Google services through the same API key, so usage and access decisions apply to both.
- Decision by question: per-record lookups belong on detail layouts, and territory overviews belong on dashboards.
- Usage and billing: both placements generate requests against your Google Cloud project. Confirm the billing account, quotas and pricing with Google, because usage grows with the number of users and views.
- Key restrictions: limit the key to the required APIs and to your EspoCRM origin, following Google's own guidance on key restrictions.
- Rollout order: start with the entities users open most often, then add dashlets for managers once the layout view is stable.
- Governance: decide who may edit layouts and dashboards, since changes alter what staff see and which data appears on the map.
Write the chosen placements into the written scope so both views are tested with real user roles before handover.
Restricting the Google Maps API key and address data
A Google Maps key sits in your EspoCRM configuration and sends address data to Google on every map view, so it needs the same care as other integration credentials. The controls below cover the key itself, its usage, and who in EspoCRM can see the addresses it is used to display.
Restrict the key by HTTP referrer
Limit the key to requests coming from your EspoCRM hostname, so a copy of the key pulled from the browser or configuration cannot be reused on another site. Use the exact hostname users type, including the scheme and any subdomain, and add a separate entry for any staging host. Confirm the referrer format and wildcard rules in your own Google Cloud console, because Google changes its restriction options over time. Test the map views after each change, since a mismatched referrer fails silently for users.
Limit the key to three APIs
Enable only the Geocoding, Maps JavaScript and Maps Static APIs, and restrict the key to those three services. EspoCRM needs these to convert addresses to coordinates and to render maps, so any other API on the key is unused access that still counts against your project if the key leaks. Review the list after each EspoCRM upgrade, since a later release could add a dependency you must enable.
Store the key in integration settings only
Enter the key only at Administration > Integrations > Google Maps and keep it out of custom scripts, layout files, shared spreadsheets and tickets. Limit who holds the administrator role to people who need it, and use a dedicated administrator account for this work rather than a daily-use login. The EspoCRM security docs recommend avoiding admin accounts for daily work and restricting administrator access by IP address, which applies here as well.
Monitor usage and billing alerts
Set billing alerts and review API usage for the Google Cloud project that holds the key. A sudden rise in geocoding or map loads can indicate a leaked key being used elsewhere, or a bulk import that geocodes far more addresses than expected. Ask your Google Cloud administrator who receives alerts and confirm the budget thresholds and quota limits in the console, since these settings are yours to define.
Rotate the key when access changes
Create a new key and retire the old one when a staff member who could read the key or the integration settings leaves, or when a key may have been exposed. Update the EspoCRM setting first, confirm maps still render, then delete the old key in Google Cloud. Record the rotation date and owner in your change log so the next review knows which key is live.
Review which roles see address data
Address fields and their map fields are visible according to EspoCRM roles and team assignments, so a map on an account detail layout shows the same addresses as the field itself. Check each role that can read accounts and contacts, and confirm that teams restrict records to the right users. Run a test with a user from each role to see the map and the address fields they actually get, because a layout visible to a broad role exposes location data to everyone in it.
Why the map does not appear and how to fix it
This table lists the most common reasons a map fails to show on an EspoCRM record, with the likely cause, how to confirm it and the fix for each. Work down the rows in order, since the layout and API key checks are the fastest to rule out.
| Symptom or cause | How to confirm | Fix |
|---|---|---|
| Map field missing from the detail layout | Open the record's detail layout in Administration > Layout Manager and check whether the Map field for the address is placed on it | Add the Map field that corresponds to the address field to the detail layout and save |
| API key missing or required APIs not enabled | Open Administration > Integrations > Google Maps and confirm an API key is saved; in Google Cloud, check that Geocoding API, Maps JavaScript API and Maps Static API are enabled for the project | Enter the key in the Google Maps integration settings and enable all three required APIs for the same project |
| Key restrictions blocking the EspoCRM hostname | In Google Cloud, review the key's application restrictions and API restrictions, then compare them with the exact domain users type in the browser | Add the EspoCRM hostname to the allowed referrers and allow the three required APIs on the key, then reload the record |
| Billing not enabled on the Google Cloud project | Check the project's billing status in Google Cloud; requests may be rejected even when the APIs are enabled | Link an active billing account to the project that owns the API key, then retest a record |
| Addresses fail to geocode | Open the affected record and compare the street, city, postal code and country fields with a valid postal address; a missing country or postal code is a common cause | Complete the address fields on the record and save so the geocoding request can resolve the location |
| Browser content blocking | Open the browser developer console on the record page and look for blocked scripts or requests to Google domains; test in a private window with extensions disabled | Allow Google Maps domains in the content blocker or privacy extension for the EspoCRM site, then reload |
| EspoCRM version lacks the feature | Check the installed version under Administration > Upgrade or the instance footer; confirm the Maps documentation matches that version | Upgrade EspoCRM to a version that includes the Google Maps integration, planning the upgrade as a separate change |
| Map not refreshing after address edits | Edit an address, save, and reload the record; compare the map with the saved address values | Reload the record after saving and confirm the address fields changed; if the map still shows old data, clear the browser cache and retest |
What a Google Maps setup in EspoCRM takes and what it needs from you
How much effort does a Google Maps setup take for one team compared with many entities?
For one team using the standard Account and Contact entities, the core work is small: add a Google Maps API key, confirm the required APIs are enabled, and place the map field on the detail layouts those users see. Effort rises with each additional entity, layout and role that needs a map, because every Address field has a matching Map field that must be placed and tested separately. Custom entities add modeling work before any map can be added. Ask the partner to count entities, layouts and roles in the written scope so the effort is visible.
Can our own team set up Google Maps in EspoCRM without outside help?
Often yes, for a simple setup. The EspoCRM maps documentation describes the steps: enter the API key at Administration > Integrations > Google Maps, make sure the Geocoding, Maps JavaScript and Maps Static APIs are enabled, and add Map fields to detail layouts through the layout editor. Your team needs admin access to EspoCRM and someone with rights in the Google Cloud project. Outside help becomes more useful when layouts differ by role, when records need cleanup before addresses geocode correctly, or when you want the setup documented and tested for your team.
What Google Cloud access and billing responsibilities stay with our organization?
Your organization keeps ownership of the Google Cloud project, the billing account, the API key and the decision about who can change key restrictions. Google bills usage of the Geocoding, Maps JavaScript and Maps Static APIs under your account, so the cost depends on how many addresses are geocoded and how often maps load. Partners can build the configuration, but the written scope should state who creates the project, who holds the billing owner role, where the key is stored, and who rotates it. Confirm current pricing and free-usage terms directly with Google.
How long does the work take with more entities and layouts?
No duration is fixed for this topic. The main variables are the number of entities that hold addresses, the number of detail layouts that need a map, whether you use custom entities, and how many roles need different views. A single-team setup on standard entities is usually a short configuration task. Each added entity or role adds layout work, testing and review. Ask for a timeline that lists these items separately so you can see which parts drive the schedule.
What makes the scope grow for a Google Maps project?
Four factors usually expand the work: custom entities with address fields that were not part of the standard model, multiple detail layouts for different teams, data cleanup because incomplete or inconsistent addresses will not place correctly on a map, and map dashlets built for many roles. Each factor adds design decisions about who sees which address and what each team needs from the map. Mention these factors early so the quote reflects them rather than adding them later.
What should we ask for in a written quote for this work?
Ask for a written scope that lists each entity and address field in scope, each detail layout that will show a Map field, each dashlet and role it serves, and the APIs to be enabled. Request a statement of who creates and owns the Google Cloud project and billing account, how the API key is stored and restricted, and what testing is included with each role. Ask what is one-time work and what recurs, such as key rotation, layout changes after upgrades and Google usage charges that your organization pays directly.
How do API key restrictions affect the setup and security?
Restricting the key limits which Google APIs and websites can use it, which reduces misuse if the key leaks. Restrictions must match the three required APIs, or maps and geocoding will fail for users. Your engineers should confirm the exact restriction settings against Google's current documentation, because the options change over time. Include restriction testing, key storage and a rotation procedure in the scope, and record who approved the final configuration.
How DeployOpen scopes and delivers EspoCRM map integrations
DeployOpen plans, implements, tests, documents and supports self-hosted open-source platforms inside your own infrastructure, including EspoCRM. For map work, we agree the Google Maps setup, the address fields to display and the layouts that show them in writing before any configuration begins.
How we scope
- Confirm which account, contact and custom entities hold address fields that should appear on a map.
- Agree which Google Cloud project, billing account and API key ownership the client will provide.
- Record the Geocoding, Maps JavaScript and Maps Static APIs, plus any restrictions on the key, in the written scope.
- Engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts.
How we build
- Configure the Google Maps API key at Administration, Integrations, Google Maps in a staging instance first.
- Add the Map fields to detail layouts for each role, checking that users without access see nothing extra.
- Build and test map dashlets for the teams that need them, using sample records that match real address formats.
- Verify that address data displays correctly and that API key restrictions block requests from unauthorized domains.
How we hand over
- Document the API key settings, enabled Google APIs, layout changes and dashlet configuration for your administrators.
- Walk through the steps for rotating the API key and updating its restrictions without downtime.
- Record which Google billing and quota settings your finance and platform owners must monitor.
- Hand over configuration as reviewable changes, so your team can repeat or extend the setup later.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers after handover.
- Review map behavior after each EspoCRM upgrade, since layouts and integration settings may need checks.
- Agree in writing who responds to changes in Google API availability, billing or key restrictions.
- Ask us to confirm any Google Maps feature not covered in the written scope before relying on it.
