Google Map Field ACF PRO: corrigir API key

Tipo Page Builders

Nome do erro Google Map Field do ACF PRO não carrega (API Key) EN: ACF PRO Google Map Field not loading (Google Maps API error)

Severidade Grave

Descrição O Google Map Field do ACF PRO renderiza um mapa cinza ou vazio quando não ha uma chave da Google Maps JavaScript API registrada no WordPress, ou quando a chave existe mas as APIs e restricoes do Google Cloud estão incorretas.

O que é Google Map Field do ACF sem API key?

O Google Map Field e um campo do ACF PRO que renderiza um mapa interativo do Google Maps no editor e no frontend, usando a Google Maps JavaScript API para desenhar o mapa, geocodificar enderecos e mostrar o autocomplete de busca. Diferente de outros campos, ele depende de um serviço externo pago: sem uma chave de API valida registrada e com as APIs certas habilitadas no Google Cloud, o campo não consegue inicializar o mapa. A documentação oficial do ACF e clara: para usar a Google Maps JavaScript API e preciso primeiro registrar uma chave de API valida. O sintoma classico e um retangulo cinza no lugar do mapa, tanto na tela de edição do campo quanto na página publicada, acompanhado de mensagens de erro no console do navegador.

Como identificar

Mensagem sobreposta no próprio mapa: ‘This page can’t load Google Maps correctly’, com o mapa escurecido e a marca d’agua do Google
Retangulo cinza ou área em branco no lugar do mapa, tanto no editor do ACF quanto no frontend do post
No console do navegador (F12, aba Console): ‘Google Maps JavaScript API error: ApiNotActivatedMapError’ quando a Maps JavaScript API não esta habilitada no projeto
No console: ‘Google Maps JavaScript API error: RefererNotAllowedMapError’ quando o domínio do site não esta na lista de referrers permitidos da chave
No console: ‘InvalidKeyMapError’ ou ‘MissingKeyMapError’ quando nenhuma chave (ou uma chave errada) foi registrada no WordPress
No console: ‘BillingNotEnabledMapError’ quando o projeto do Google Cloud não tem uma conta de faturamento ativa
O campo de busca de endereco (autocomplete) do Google Map Field não retorna sugestoes ao digitar

Como prevenir

Mantenha a chave da Google Maps API sempre restrita por referrer HTTP ao seu domínio, para que ela não possa ser reutilizada por terceiros e gere cobranca indevida.
Configure um teto de cota e um alerta de orcamento no Google Cloud para ser avisado antes de a Maps JavaScript API estourar o limite do período gratuito.
Registre a chave por filtro no código (functions.php ou plugin de snippets) e não espalhada em campos do tema, para ter uma fonte única fácil de auditar.
Após qualquer atualização do ACF PRO, abra um post com o Google Map Field e confira o console para flagrar deprecacao de API antes que o mapa quebre em producao.

Causa

Nenhuma chave de API foi registrada no WordPress: o ACF PRO não traz chave embutida e exige que você informe a sua via filtro acf/fields/google_map/api ou via acf_update_setting('google_api_key', ...), o que gera InvalidKeyMapError ou MissingKeyMapError.
A Maps JavaScript API não esta habilitada no projeto do Google Cloud (somente Geocoding ou Places foi ligada), produzindo o erro ApiNotActivatedMapError no console.
A chave tem restricao de referrer HTTP e o domínio do site (incluindo www e https) não foi adicionado a lista de sites permitidos, gerando RefererNotAllowedMapError.
O projeto do Google Cloud não tem uma conta de faturamento ativa vinculada, condicao obrigatoria desde 2018 para a Maps JavaScript API, resultando em BillingNotEnabledMapError.
A Places API exigida pelo autocomplete de endereco não foi habilitada; desde 1 de marco de 2025 sites novos precisam habilitar a 'Legacy Places API' especificamente para o Google Map Field do ACF.
Um plugin de cache ou de minificacao agrupou o JavaScript do ACF e quebrou o parametro da chave na URL de carregamento da Maps JavaScript API.

Como resolver

Crie e configure a chave no Google Cloud Console: No Google Cloud Console crie um projeto, vincule uma conta de faturamento e habilite as três APIs que o Google Map Field usa. Em APIs e serviços ative, uma a uma, as APIs abaixo. Sem faturamento ativo o mapa retorna BillingNotEnabledMapError mesmo com a chave correta.
```
Maps JavaScript API
Geocoding API
Places API (sites novos: Legacy Places API)
```
Restrinja a chave ao domínio do seu site: Ainda no Google Cloud, em Credenciais, edite a chave e em Restricoes de aplicativo escolha Sites (referenciadores HTTP) e adicione os padroes do seu domínio. Inclua a versão com e sem www e o curinga de caminho, senao o Google bloqueia com RefererNotAllowedMapError.
```
https://seusite.com.br/*
https://www.seusite.com.br/*
```
Registre a chave no WordPress via filtro do ACF: No arquivo functions.php do tema filho (ou em um plugin de snippets), registre a chave usando o filtro oficial do ACF para o Google Map. Esta e a forma recomendada pela documentação do ACF. Troque o valor de exemplo pela sua chave real.
```
function full_acf_google_map_api( $api ) {
    $api['key'] = 'SUA_CHAVE_AQUI';
    return $api;
}
add_filter( 'acf/fields/google_map/api', 'full_acf_google_map_api' );
```
Limpe o cache e valide no console do navegador: Limpe o cache do plugin de cache e do navegador, abra um post com o Google Map Field e confira o console (F12). Se persistir RefererNotAllowedMapError revise o padrão de referrer do passo 2; se persistir ApiNotActivatedMapError confirme a Maps JavaScript API do passo 1. A chave demora alguns minutos para propagar após a criação.

PHP

<?php
// Registra a chave da Google Maps API para o Google Map Field do ACF.
// Via filtro (forma recomendada pela doc do ACF):
add_filter( 'acf/fields/google_map/api', function ( $api ) {
    $api['key'] = 'SUA_CHAVE_AQUI';
    return $api;
} );

// Alternativa equivalente via setting global do ACF:
add_action( 'acf/init', function () {
    acf_update_setting( 'google_api_key', 'SUA_CHAVE_AQUI' );
} );

Perguntas frequentes

O Google Map Field do ACF PRO funciona sem chave de API?

Não. A documentação oficial do ACF exige uma chave valida da Google Maps JavaScript API registrada no WordPress. Sem chave o campo so mostra um retangulo cinza e erros como MissingKeyMapError no console.

Por que aparece 'This page can't load Google Maps correctly' no meu mapa?

Essa mensagem sobreposta indica um erro crítico da Google Maps JavaScript API. O motivo exato aparece no console do navegador, normalmente chave ausente, API não habilitada, domínio não autorizado ou faturamento desativado no Google Cloud.

Onde eu coloco a chave da API no WordPress para o ACF?

No functions.php do tema filho ou num plugin de snippets, usando o filtro acf/fields/google_map/api ou a função acf_update_setting('google_api_key', ...) no hook acf/init. As duas formas estão na documentação oficial do ACF.

Quais APIs do Google Cloud o Google Map Field do ACF exige?

Maps JavaScript API para desenhar o mapa, Geocoding API para converter enderecos em coordenadas e Places API para o autocomplete de busca. Sites novos criados a partir de marco de 2025 devem habilitar a Legacy Places API.

O que significa o erro RefererNotAllowedMapError no console?

Significa que a URL atual não esta na lista de referenciadores permitidos da chave. Edite a chave no Google Cloud e adicione o seu domínio com e sem www no formato de curinga, por exemplo o endereco do site seguido de barra asterisco.

Por que o mapa funciona no editor mas quebra no frontend?

Em geral e um plugin de cache ou minificacao que reagrupou o JavaScript e quebrou o parametro da chave no carregamento da Maps JavaScript API no frontend. Exclua o script do ACF da minificacao e limpe o cache.

Preciso ativar faturamento no Google Cloud para o ACF usar o mapa?

Sim. Desde 2018 a Maps JavaScript API exige uma conta de faturamento ativa vinculada ao projeto, mesmo com cota gratuita mensal. Sem ela o mapa retorna BillingNotEnabledMapError mesmo com a chave correta.

Grave

Como corrigir o erro de query no Listing Grid do JetEngine

O erro de query no Listing Grid do JetEngine ocorre quando a Custom Query do Query Builder falha ou não retorna nada: tipo de query trocado, SQL invalido, meta query que exclui todos os registros ou macro vazia. O grid fica vazio ou exibe aviso de banco enquanto o Preview do Query Builder parece correto.

Grave

Como corrigir o Customizer que não salva alterações no Astra Pro

O erro do Astra Customizer que não salva acontece quando o Astra Pro no Personalizar acumula muitos controles e o POST de gravação é truncado pelo max_input_vars ou bloqueado por mod_security, fazendo o botão Publicar girar sem nunca confirmar. A correção é liberar o limite de campos e a requisição customize_save no servidor.

Atenção

Como corrigir o layout quebrado do Blog Pro no Astra Pro no WordPress

O layout quebrado do Blog Pro no Astra Pro acontece quando o módulo Blog Pro não esta ativado nas Astra Options, quando o cache serve um CSS antigo, ou quando um layout personalizado sobrepoe o arquivo do blog, fazendo o grid e as colunas não aplicarem no frontend.

Atenção

Como corrigir o Gallery Field com imagens que não carregam no ACF PRO

O ACF Gallery Field não carrega imagem quando o código do template trata o retorno da galeria de forma diferente do Return Format configurado no campo, ou quando o grupo de campos não casa com o post editado, fazendo a galeria voltar vazia no frontend.

Atenção

Como corrigir o JetTabs que não alterna conteúdo no frontend

O JetTabs não alterna conteúdo no frontend quando o JavaScript do widget não carrega, IDs de aba duplicados colidem ou a otimização de cache adia o script, deixando as abas presas no primeiro item ao clicar.

Grave

Como corrigir o conflito de JavaScript entre Ultimate Addons e WP Rocket

Widgets interativos do Ultimate Addons for Elementor param de funcionar no frontend quando o WP Rocket segura o uael-frontend-script.js pelo Delay JavaScript Execution ou o junta com outros arquivos pelo Combine JavaScript. A correção e excluir o script do plugin dessas otimizacoes e limpar o cache.

Setores

Extensões

Integrações

Como corrigir o Google Map Field do ACF PRO (erro de Google Maps API)

O que é Google Map Field do ACF sem API key?

Como identificar

Como prevenir

Causa

Como resolver

Perguntas frequentes

Itens relacionados

Como corrigir o erro de query no Listing Grid do JetEngine

Como corrigir o Customizer que não salva alterações no Astra Pro

Como corrigir o layout quebrado do Blog Pro no Astra Pro no WordPress

Como corrigir o Gallery Field com imagens que não carregam no ACF PRO

Como corrigir o JetTabs que não alterna conteúdo no frontend

Como corrigir o conflito de JavaScript entre Ultimate Addons e WP Rocket

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