Google Maps Field ACF PRO Não Carrega: Como Corrigir

Tipo Page Builders

Nome do erro Google Maps Field do ACF PRO não carrega EN: ACF PRO Google Maps Field not loading

Severidade Atenção

Descrição O Google Maps Field do ACF PRO exige uma chave de API do Google registrada via filtro acf/fields/google_map/api ou acf_update_setting. Sem ela, o campo mostra um mapa cinza e o console acusa erro da Google Maps JavaScript API.

O que é Google Maps Field do ACF PRO?

O Google Maps Field do ACF PRO e um campo que renderiza um mapa interativo do Google no editor do WordPress para escolher e salvar um endereco com latitude e longitude. Ele depende da Google Maps JavaScript API, que so funciona com uma chave de API valida do Google e as APIs corretas habilitadas no projeto do Google Cloud. Quando essa chave esta ausente, invalida ou sem as APIs ativadas, o campo não renderiza o mapa: aparece uma área cinza, sem tiles, e o navegador registra um erro da Google Maps JavaScript API no console.

Como identificar

O campo de mapa aparece como uma área cinza vazia no editor, sem os tiles do Google, mas a caixa de busca de endereco continua visivel.
No console do navegador (F12, aba Console) aparece a mensagem ‘Google Maps JavaScript API error: ApiNotActivatedMapError’ quando a Maps JavaScript API não foi habilitada no projeto.
O console mostra ‘Google Maps JavaScript API error: InvalidKeyMapError’ quando a chave informada esta errada ou não existe.
O console mostra ‘Google Maps JavaScript API error: RefererNotAllowedMapError’ quando a restricao de referenciador HTTP da chave não inclui o domínio do site.
O console mostra ‘Google Maps JavaScript API error: BillingNotEnabledMapError’ quando o faturamento (billing) não esta ativo no projeto do Google Cloud.
A busca de endereco no campo não retorna sugestoes, sinal de que a Places API (ou a Legacy Places API) não esta habilitada.

Antes de começar: Faca backup do functions.php antes de edita-lo. Um erro de sintaxe no PHP derruba o site com tela branca; mantenha acesso por FTP para reverter o arquivo se isso acontecer.

Como prevenir

Restrinja a chave de API a referenciadores HTTP do seu domínio e habilite apenas as APIs necessarias, para evitar consumo não autorizado e cobranca surpresa.
Use uma chave diferente para staging e producao, cada uma com a restricao de domínio correta, para nunca cair em RefererNotAllowedMapError ao publicar.
Configure alertas de orcamento (budget alerts) no faturamento do Google Cloud para ser avisado antes de a cobranca da Maps Platform crescer.
Registre a chave em um plugin de snippets versionado ou no tema filho, nunca em um tema pai que será sobrescrito na próxima atualização.

Causa

Nenhuma chave de API foi registrada no ACF: o filtro acf/fields/google_map/api ou a chamada acf_update_setting com google_api_key não existe no functions.php do tema ou em um plugin de snippets.
A Maps JavaScript API não esta habilitada no projeto do Google Cloud Console, entao a chave existe mas o serviço que desenha o mapa esta desligado (gera ApiNotActivatedMapError).
A chave tem restricao de referenciador HTTP configurada apenas para outro domínio (por exemplo, o ambiente de staging), e o domínio de producao do site não foi adicionado a allowlist da chave (gera RefererNotAllowedMapError).
O faturamento não esta ativado no projeto do Google Cloud: desde 2018 o Google exige um cartao vinculado para liberar a Maps Platform, e sem isso a chave e recusada (gera BillingNotEnabledMapError).
A Places API usada pela busca de endereco não esta habilitada; desde 1 de marco de 2025 o Google descontinuou a Places API antiga e novos projetos precisam ativar a Legacy Places API (places-backend.googleapis.com) para o autocomplete de endereco funcionar.

Como resolver

Gerar a chave de API no Google Cloud Console: Acesse o Google Cloud Console, selecione ou crie um projeto e gere uma chave em APIs e serviços, Credenciais, Criar credenciais, Chave de API. Copie o valor da chave para usar no próximo passo.
```
console.cloud.google.com/apis/credentials
```
Habilitar as três APIs exigidas pelo campo: Na biblioteca de APIs, ative as três APIs que o Google Maps Field usa. A Maps JavaScript API desenha o mapa, a Geocoding API converte o endereco em coordenadas e a Places API alimenta o autocomplete de endereco. Em projetos novos, ative também a Legacy Places API.
```
Maps JavaScript API
Geocoding API
Places API
console.cloud.google.com/apis/library/places-backend.googleapis.com
```
Ativar o faturamento e restringir a chave ao domínio: Em Faturamento, vincule uma conta de cobranca ao projeto, exigencia da Maps Platform. Depois, em Credenciais, edite a chave e, na restricao de aplicativo, escolha Referenciadores HTTP e adicione o domínio do site para evitar uso indevido da chave.
```
https://full.services/*
https://*.full.services/*
```
Registrar a chave no ACF via filtro no functions.php: Adicione o filtro do ACF que injeta a chave no campo. Coloque o snippet no functions.php do tema filho ou em um plugin de snippets de código, trocando o valor pela sua chave real. Salve, limpe o cache e recarregue a tela de edição para ver o mapa carregar.
```
add_filter('acf/fields/google_map/api', 'full_acf_google_map_api');
```

PHP

<?php
// functions.php do tema filho ou plugin de snippets

// Metodo 1 — filtro especifico do campo Google Map
function full_acf_google_map_api( $api ) {
    $api['key'] = 'SUA_CHAVE_DE_API';
    return $api;
}
add_filter( 'acf/fields/google_map/api', 'full_acf_google_map_api' );

// Metodo 2 (alternativo) — define a chave global do ACF no acf/init
function full_acf_init() {
    acf_update_setting( 'google_api_key', 'SUA_CHAVE_DE_API' );
}
add_action( 'acf/init', 'full_acf_init' );

Perguntas frequentes

Por que o Google Maps Field do ACF mostra um mapa cinza?

O mapa cinza significa que a Google Maps JavaScript API não conseguiu carregar. Quase sempre a causa e a falta de chave de API valida registrada no ACF ou a Maps JavaScript API desativada no projeto do Google Cloud. Abra o console do navegador para ler a mensagem de erro exata.

Como adiciono a chave de API do Google Maps no ACF PRO?

Use o filtro acf/fields/google_map/api ou a função acf_update_setting com google_api_key dentro de um hook acf/init. Coloque o código no functions.php do tema filho ou em um plugin de snippets, trocando o valor pela sua chave real gerada no Google Cloud Console.

Quais APIs do Google preciso habilitar para o campo funcionar?

Três APIs são exigidas: Maps JavaScript API para desenhar o mapa, Geocoding API para converter endereco em coordenadas e Places API para o autocomplete de endereco. Em projetos criados após marco de 2025, ative também a Legacy Places API.

O que significa o erro ApiNotActivatedMapError?

Esse erro no console indica que a chave existe, mas a Maps JavaScript API não esta habilitada no projeto do Google Cloud. Abra a biblioteca de APIs, procure por Maps JavaScript API e clique em Ativar; depois recarregue a tela de edição do post.

Preciso ativar faturamento no Google Cloud para o mapa do ACF aparecer?

Sim. Desde 2018 a Google Maps Platform exige uma conta de faturamento vinculada ao projeto, mesmo dentro da cota gratuita mensal. Sem faturamento ativo a chave e recusada e o console acusa BillingNotEnabledMapError.

O mapa funciona no staging mas some em producao, por que?

A chave tem restricao de referenciador HTTP apenas para o domínio de staging. Edite a chave em Credenciais, adicione o domínio de producao a lista de referenciadores HTTP e aguarde alguns minutos para a alteração propagar.

A busca de endereco não sugere nada, o que falta?

O autocomplete depende da Places API. Habilite a Places API e, em projetos novos, a Legacy Places API no Google Cloud. Confirme também que a Geocoding API esta ativa, pois ela converte o endereco escolhido em latitude e longitude para salvar.

Grave

Como corrigir o conflito de templates de curso entre Tutor LMS e Elementor

A página de curso fica sem o layout do Elementor (ou mostra o template padrão do Tutor LMS) porque o addon Tutor LMS do Elementor não esta ativo ou a prioridade de template aponta para o template embutido do plugin em vez do seu template Elementor.

Grave

Como corrigir o erro de PHP ao ativar o Elementor Pro em hospedagem compartilhada

O erro de PHP ao ativar o Elementor Pro em hospedagem compartilhada acontece quando o servidor não atende aos requisitos do plugin: a versão do PHP esta abaixo de 7.4, a memória reservada por requisicao e baixa, ou o plugin base gratuito Elementor não esta ativo. O WordPress aborta a ativacao e mostra um erro fatal.

Atenção

Como corrigir o conflito de Custom Fields entre ACF PRO e JetEngine no WordPress

O conflito de Custom Fields entre ACF PRO e JetEngine ocorre quando os dois plugins registram um campo com o mesmo nome de meta e gravam na mesma chave da tabela wp_postmeta, fazendo um sobrescrever o valor salvo pelo outro.

Informativo

Como corrigir o Scroll to Top que não funciona no Astra Pro

O Scroll to Top Astra Pro não funciona quando o botão está desativado para o dispositivo atual no Customizer, quando o JavaScript do tema é bloqueado por um plugin de cache, ou quando outro plugin de voltar ao topo entra em conflito com o do Astra.

Atenção

Como corrigir os Data Stores do JetEngine que não salvam dados do usuário no WordPress

O JetEngine Data Stores não salva quando o tipo de armazenamento escolhido é por sessao do navegador (Local Storage ou Cookies) e o visitante troca de dispositivo ou limpa o navegador, ou quando o tipo Users esta em uso mas o visitante não esta logado, fazendo os itens adicionados sumirem ao recarregar a página.

Atenção

Como corrigir o layout quebrado de páginas de curso do Tutor LMS com Astra Pro no WordPress

O layout quebrado de páginas de curso do Tutor LMS com Astra Pro acontece quando a página de curso herda o container, a sidebar ou os elementos globais do Astra em vez de usar uma largura total sem barra lateral, deixando o conteúdo do curso estreito, espremido ou desalinhado.

Setores

Extensões

Integrações

Como corrigir o Google Maps Field no ACF PRO (chave de API)

O que é Google Maps Field do ACF PRO?

Como identificar

Como prevenir

Causa

Como resolver

Perguntas frequentes

Itens relacionados

Como corrigir o conflito de templates de curso entre Tutor LMS e Elementor

Como corrigir o erro de PHP ao ativar o Elementor Pro em hospedagem compartilhada

Como corrigir o conflito de Custom Fields entre ACF PRO e JetEngine no WordPress

Como corrigir o Scroll to Top que não funciona no Astra Pro

Como corrigir os Data Stores do JetEngine que não salvam dados do usuário no WordPress

Como corrigir o layout quebrado de páginas de curso do Tutor LMS com Astra Pro no WordPress

Setores

Extensões

Integrações

Extensões

Hero Sections

Seções de CTA

Login

Blog

Cabeçalhos

Seções de FAQ

Cadastro

Blog individual

Rodapés

Seções de contato

Seções de preços

Faixas

Portfólio

Seções de equipe

Números

Logotipos