Como adicionar Google Maps ao WordPress em 2026: O guia do programador

Em 2013, adicionar um mapa era colar um <iframe> de maps.google.com. Em 2026 a Google Maps Platform exige chave API, faturação ativa, restrições de segurança e decisões explícitas de RGPD. Um iframe “rápido” ainda funciona para um pin isolado, mas em sites de produção portugueses e europeus o custo aparece em PageSpeed, cookies e faturas surpresa.

Este guia cobre o fluxo de programador: chave segura, enqueue correto no WordPress, padrão fachada, consentimento, Map IDs e alternativas. Sem plugins monólito a não ser que o âmbito o justifique.

#Como a Maps Embed API difere de um iframe copiado

Há dois tipos de iframe. O excerto copiado da caixa “Partilhar” em google.com/maps não leva chave API nem contrato, por isso não há projeto, cota nem relatório de utilização por trás dele. A Maps Embed API é a versão documentada da mesma ideia: um iframe cujo src aponta para https://www.google.com/maps/embed/v1/MAP_MODE?key=YOUR_API_KEY&PARAMETERS, em que o modo é place, view, directions, streetview ou search.

A página de utilização e faturação da Google indica que a Maps Embed API “é de utilização gratuita, com pedidos ilimitados” (tradução própria) e que não há limites por segundo nem por dia. Mesmo assim, cada pedido exige uma chave API, por isso as restrições de chave descritas mais abaixo também se aplicam aqui. Os mapas incorporados não são suportados abaixo de 200 px em qualquer das dimensões, e a Google pede um atributo referrerpolicy no iframe para que o browser envie o seu domínio no cabeçalho Referer. Sem ele, uma chave restrita ao seu site rejeita o pedido.

<iframe
  width="600" height="450" style="border:0" loading="lazy"
  referrerpolicy="no-referrer-when-downgrade"
  src="https://www.google.com/maps/embed/v1/place?key=YOUR_API_KEY&q=YOUR_ADDRESS">
</iframe>

A Embed API serve uma página de contacto com uma localização: sem risco de faturação, sem JavaScript para escrever, e o loading="lazy" nativo do iframe deixa-o fora do carregamento inicial da página. Não resolve a questão da privacidade. O iframe continua a carregar conteúdo de servidores Google no browser do visitante, por isso as regras de consentimento das secções sobre RGPD deste guia aplicam-se a ele tanto como à JavaScript API. Quando precisa de marcadores personalizados, clustering, estilo próprio ou interação com o resto da página, a ferramenta certa é a Maps JavaScript API.

#Como criar a chave API do Google Maps

1. Crie um projeto na Google Cloud Console.
2. Ative Maps JavaScript API (e só as APIs que vai usar, por exemplo Geocoding se precisar).
3. Crie uma chave API ligada a uma conta de faturação.
4. Defina alertas de orçamento: se a restringir mal, a chave é um cartão de crédito com URL pública.

#Como restringir a chave API do Google Maps

• Referrers HTTP: https://oseudominio.pt/* e o staging se existir (https://staging.oseudominio.pt/*).
• Restrições de API: apenas Maps JavaScript API (e Geocoding se necessário). Nunca “Todas as APIs”.
• Chaves de servidor (Geocoding no PHP) usam restrição por IP, não por referrer. Não misture os dois tipos.

Documentação oficial de práticas: API security best practices.

Guarde a chave em wp-config.php ou variável de ambiente, não no repositório Git:

define( 'WPPOLAND_GMAPS_KEY', getenv( 'GMAPS_KEY' ) ?: '' );

#O que fazer se a chave API do Google Maps foi exposta

Uma chave de browser está sempre visível no código-fonte da página, por isso “fuga” significa normalmente que as restrições faltavam ou eram demasiado amplas. As boas práticas de segurança da API da Google indicam a ordem de trabalho:

1. Restrinja primeiro. Adicione uma restrição de aplicação (websites, endereços IP, apps Android ou iOS) e limite a chave às APIs que ela realmente chama. Uma restrição de website aceita wildcards como https://*.example.com, que cobre todos os subdomínios.
2. Use chaves separadas para aplicações e ambientes separados. Se uma chave for comprometida, pode eliminá-la ou rodá-la sem tocar nas outras.
3. Rode a chave só quando restringir não basta. A Google aconselha regenerar chaves “com cautela e apenas como último recurso” (tradução própria). A rotação cria uma chave nova com as restrições da antiga, e as duas funcionam durante a transição, por isso pode colocar a chave nova no WordPress antes de retirar a antiga.
4. Antes de eliminar uma chave, confirme na vista de métricas que ela já não tem tráfego bem-sucedido vindo de produção.

No WordPress, guarde a chave numa opção ou no wp-config.php e imprima-a a partir de um único sítio. Assim, uma rotação é uma única alteração e não uma busca por templates do tema e widgets do page builder.

#Porque é que o Google Maps deixa o WordPress lento

A Maps JavaScript API descarrega um volume grande de JavaScript e compete pela thread principal. Carregá-la no first paint da homepage baixa a pontuação no Lighthouse e pode piorar LCP/INP.

#Como carregar o Google Maps só após clique

1. Mostre uma imagem estática (AVIF/WebP) ou um mapa Static Maps.
2. Só injete maps.googleapis.com após clique, ou após o mapa entrar no viewport e existir consentimento.
3. Inicialize o mapa no callback (initMap).

Conceito em JS puro:

function loadGoogleMaps( apiKey ) {
  if ( window.google && window.google.maps ) {
    window.initMap();
    return;
  }
  const script = document.createElement( 'script' );
  script.src = 'https://maps.googleapis.com/maps/api/js?key=' + encodeURIComponent( apiKey ) + '&libraries=marker&loading=async&callback=initMap';
  script.async = true;
  script.defer = true;
  document.head.appendChild( script );
}

document.getElementById( 'map-placeholder' )?.addEventListener( 'click', function () {
  loadGoogleMaps( window.wppolandMaps.key );
} );

O parâmetro libraries=marker carrega a biblioteca dos marcadores avançados usada mais abaixo, e loading=async segue a recomendação da Google para a tag de script clássica.

No WordPress, prefira wp_enqueue_script / wp_add_inline_script e localize a chave só nas páginas que precisam do mapa, nunca em todo o site.

function wppoland_enqueue_maps_facade() {
	if ( ! is_page( 'contacto' ) ) {
		return;
	}

	wp_register_script( 'wppoland-maps-facade', get_stylesheet_directory_uri() . '/js/maps-facade.js', array(), '2026.09', true );
	wp_localize_script(
		'wppoland-maps-facade',
		'wppolandMaps',
		array(
			'key'     => defined( 'WPPOLAND_GMAPS_KEY' ) ? WPPOLAND_GMAPS_KEY : '',
			'mapId'   => 'YOUR_MAP_ID',
			'lat'     => 38.7223,
			'lng'     => -9.1393,
			'consent' => false,
		)
	);
	wp_enqueue_script( 'wppoland-maps-facade' );
}
add_action( 'wp_enqueue_scripts', 'wppoland_enqueue_maps_facade' );

Ajuste o slug da página e as coordenadas. Lisboa é só exemplo; use a morada real do cliente.

#Google Maps e RGPD no consentimento de cookies

O script do Google Maps contacta infraestruturas Google e pode definir cookies de rastreio. No EEE, não carregue o mapa até o utilizador aceitar a categoria relevante (marketing / cookies de terceiros, conforme o seu CMP).

Implementação típica:

1. Contentor vazio ou imagem + botão: “Aceitar cookies e ver o mapa”.
2. Escute o evento do Cookiebot, Complianz, ou da sua CMP custom.
3. Só então chame loadGoogleMaps().

Pseudocódigo:

window.addEventListener( 'CookiebotOnAccept', function () {
  if ( Cookiebot.consent.marketing ) {
    window.wppolandMaps.consent = true;
    // Ainda pode exigir clique na fachada para performance.
  }
} );

Se faltar consentimento, mantenha a fachada. Não “pré-aqueça” o script em background, porque isso já é tratamento de dados.

Para sites só com um pin e sem necessidade de interação: considere Static Maps API (PNG) ou Leaflet + OSM, que mudam o perfil de privacidade.

#Que base legal cobre o Google Maps no RGPD

Numa página com um mapa Google cruzam-se duas regras distintas. A Diretiva ePrivacy (2002/58/CE, artigo 5.º, n.º 3) exige consentimento antes de guardar informação no dispositivo do visitante ou de a ler a partir dele, salvo quando isso for estritamente necessário para um serviço que o visitante pediu expressamente. O RGPD rege depois os próprios dados pessoais, a começar pelo endereço IP que cada pedido aos servidores Google expõe.

O papel do dono do site foi decidido pelo Tribunal de Justiça da UE no processo Fashion ID (C-40/17), com acórdão de 29 de julho de 2019. O caso dizia respeito a um botão “Gosto” do Facebook, mas o raciocínio abrange qualquer conteúdo de terceiros incorporado: o operador do website pode ser responsável conjunto pelo tratamento na recolha e na transmissão dos dados dos visitantes ao terceiro, mas não pelo que esse terceiro faz com eles depois. Quando o consentimento é a base legal, o operador tem de o obter para essas operações e tem de informar os visitantes no momento da recolha.

O próprio contrato da Google aponta no mesmo sentido. Nos Termos de Serviço da Google Maps Platform, a Google e o cliente aceitam os Controller-Controller Data Protection Terms, pelo que a Google atua como responsável pelo tratamento autónomo dos dados que os visitantes lhe enviam, e não como seu subcontratante. Os termos obrigam também a cumprir a legislação de privacidade “relativa a Serviços que armazenam e acedem a Cookies nos dispositivos dos Utilizadores Finais” (tradução própria). Se o endereço da sua conta de faturação estiver no Espaço Económico Europeu, a sua utilização rege-se pelos Termos de Serviço próprios do EEE. Para transferências para os Estados Unidos, a Comissão Europeia adotou a 10 de julho de 2023 a sua decisão de adequação relativa ao Quadro de Privacidade de Dados UE-EUA, que cobre transferências para empresas norte-americanas certificadas ao abrigo desse quadro.

Na prática, isto significa que o mapa carrega depois do consentimento ou depois de um clique num placeholder claramente identificado, que a política de privacidade indica a Google como destinatária e inclui um link para a política de privacidade da Google, e que a ferramenta de consentimento coloca o mapa na categoria que o bloqueia. Isto é informação geral, não aconselhamento jurídico; quem decide a base legal do seu site é o encarregado de proteção de dados ou o seu advogado.

#Como tratar o botão “a minha localização” no mapa

Um store locator tem muitas vezes um botão que centra o mapa no visitante. O browser pede autorização antes de navigator.geolocation devolver qualquer coisa, mas os termos da Maps Platform acrescentam requisitos próprios. O seu site tem de avisar os visitantes, antecipadamente, sobre que dados de localização recolhe e porquê, e “não obterá nem guardará em cache a localização de qualquer Utilizador Final, exceto com o consentimento expresso, prévio e revogável do Utilizador Final” (tradução própria). Por isso, o pedido do browser não chega sozinho: explique o botão ao lado dele, não guarde coordenadas em cookies nem em user meta sem esse consentimento e ofereça sempre um campo de código postal ou cidade como alternativa para os visitantes que recusam.

#Shortcode de Google Maps para WordPress

function wppoland_map_shortcode( $atts ) {
	$atts = shortcode_atts(
		array(
			'lat'  => '38.7223',
			'lng'  => '-9.1393',
			'zoom' => '14',
		),
		$atts,
		'wppoland_map'
	);

	ob_start();
	?>
	<div class="wppoland-map"
		data-lat="<?php echo esc_attr( $atts['lat'] ); ?>"
		data-lng="<?php echo esc_attr( $atts['lng'] ); ?>"
		data-zoom="<?php echo esc_attr( $atts['zoom'] ); ?>">
		<button type="button" id="map-placeholder" class="wppoland-map__facade">
			<?php esc_html_e( 'Ver mapa interativo', 'wppoland' ); ?>
		</button>
		<div id="map" class="wppoland-map__canvas" hidden></div>
	</div>
	<?php
	return ob_get_clean();
}
add_shortcode( 'wppoland_map', 'wppoland_map_shortcode' );

O JS lê data-*, respeita consentimento e só então cria google.maps.Map. Escape sempre atributos. Não imprima a chave no HTML do shortcode; use wp_localize_script.

#Como personalizar o estilo do Google Maps com Map ID

Deixe de hardcodar JSON gigante de estilos no tema. Na Cloud Console:

1. Crie um estilo (modo escuro, sem POI de concorrentes, etc.).
2. Associe a um Map ID.
3. Passe mapId na inicialização JS.

window.initMap = function () {
  const el = document.getElementById( 'map' );
  el.hidden = false;
  const map = new google.maps.Map( el, {
    center: { lat: Number( window.wppolandMaps.lat ), lng: Number( window.wppolandMaps.lng ) },
    zoom: 14,
    mapId: window.wppolandMaps.mapId,
  } );
  new google.maps.marker.AdvancedMarkerElement( {
    map: map,
    position: { lat: Number( window.wppolandMaps.lat ), lng: Number( window.wppolandMaps.lng ) },
  } );
};

Atualiza o visual na nuvem sem novo deploy do tema. O exemplo já usa AdvancedMarkerElement, que depende do Map ID e da biblioteca marker; a secção seguinte explica porquê.

#Como substituir o google.maps.Marker descontinuado

A maioria dos snippets, plugins e tutoriais antigos para WordPress cria pins com new google.maps.Marker(). A página de descontinuações da Google indica google.maps.Marker como descontinuado desde fevereiro de 2024 e aponta google.maps.marker.AdvancedMarkerElement como substituto. A classe antiga continua a funcionar, mas as funcionalidades novas só chegam aos marcadores avançados.

Os marcadores avançados têm um requisito obrigatório: o mapa precisa de um Map ID. O guia de marcadores avançados da Google diz que, sem um Map ID, “os marcadores avançados não podem carregar” (tradução própria). Crie o ID na Cloud Console, na gestão de mapas, e passe-o como mapId. É o mesmo ID que transporta o estilo na nuvem.

async function initMap(el, lat, lng) {
  const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([
    google.maps.importLibrary('maps'),
    google.maps.importLibrary('marker'),
  ]);
  const map = new Map(el, { center: { lat, lng }, zoom: 15, mapId: 'YOUR_MAP_ID' });
  new AdvancedMarkerElement({ map, position: { lat, lng }, title: 'Escritório' });
}

O padrão de carregamento também mudou. O guia de carregamento da Google descreve a importação dinâmica de bibliotecas: adiciona o carregador bootstrap inline e chama importLibrary() apenas para as bibliotecas que usa. Se mantiver a tag de script clássica, acrescente loading=async ao URL; a documentação considera-o “altamente recomendado” (tradução própria) para a performance. Carregue as bibliotecas em paralelo, como no exemplo, e não com linhas await separadas em sequência. Os parâmetros language e region do carregador definem o idioma dos controlos e dos avisos de direitos de autor e orientam os resultados para um país. Isto conta num site WordPress multilingue, em que cada versão de idioma deve carregar o mapa na sua própria língua.

O mesmo vale para a pesquisa de moradas. O widget Autocomplete legacy pertence à Places API (legacy), que os novos projetos Cloud não conseguem ativar. O widget atual é google.maps.places.PlaceAutocompleteElement, da Places API (New), que se cria e se acrescenta à página como um único elemento.

#Alternativas ao Google Maps no WordPress

Para uma página de contacto com um pin: Static Maps ou Leaflet costumam bastar. Reserve a Maps JavaScript API para rotas, várias marcas, Street View ou UX que justifique o peso.

#Checklist do Google Maps antes de publicar

1. Chave restrita por domínio e por API.
2. Alertas de orçamento no Cloud Billing e cota de pedidos em APIs e serviços.
3. Script só na página necessária (is_page / bloco condicional).
4. Fachada + lazy-load; zero Maps no critical path.
5. Bloqueio até consentimento no EEE.
6. Map ID para branding; sem JSON de estilo no Git se possível.
7. Teste Lighthouse antes/depois na página de contacto.
8. Staging com chave de teste separada.

#wp_enqueue vs script solto no footer

Nunca cole <script src="https://maps.googleapis.com/..."> diretamente no footer.php. Perde dependências, versão e a capacidade de condicionar o carregamento. Use wp_register_script + wp_enqueue_script + wp_localize_script (ou wp_add_inline_script para o callback). Em block themes, o mesmo JS pode ser anexado via enqueue_block_assets só quando o bloco do mapa está presente na página; verifique-o com has_block no conteúdo.

#Porque é que a fatura da API Google Maps aumenta

• Chave sem restrição de referrer usada num CodePen ou site espelho: a fatura sobe em horas.
• Geocoding no browser com a mesma chave do Maps JS sem cota separada.
• Preview do Elementor/Gutenberg a disparar dezenas de cargas de mapa por edição.
• Staging partilhado com a chave de produção e sem referrer de staging na allow-list (o mapa parte), ou staging aberto na allow-list para * (o mapa funciona, a segurança não).

Separe projetos Cloud ou pelo menos chaves: prod, staging. Configure alertas a 50% e 90% do orçamento mensal.

#Como funciona a faturação da Google Maps Platform depois de março de 2025

Tutoriais mais antigos, incluindo versões anteriores deste, mencionam um crédito mensal de 200 USD. Esse modelo acabou. Segundo a página das alterações de faturação de março de 2025 (consultada a 2026-10-14), a Google “substituiu o crédito mensal recorrente de 200 USD por um limite mensal de utilização gratuita para cada SKU dos Core Services” (tradução própria). Cada SKU pertence a uma categoria (Essentials, Pro ou Enterprise), e o limite gratuito varia com a categoria.

Na página de preços atual, os SKUs que um site WordPress típico usa estão em Essentials: Dynamic Maps (um carregamento de mapa na Maps JavaScript API), Static Maps e Geocoding têm cada um um limite gratuito de 10 000 eventos faturáveis por mês, e o SKU Embed aparece como ilimitado. A maioria dos SKUs Pro tem um limite de 5000 e a maioria dos SKUs Enterprise um limite de 1000. Os limites contam por SKU, por isso um site que carrega um mapa dinâmico e também geocodifica moradas usa duas quotas gratuitas separadas. Os preços acima do limite mudam com o tempo; consulte-os na página de preços e não num artigo de blogue.

A Maps JavaScript API continua a exigir uma conta de faturação, mesmo que nunca ultrapasse o limite gratuito. Dois controlos protegem contra uma fatura inesperada. Um orçamento no Cloud Billing envia alertas quando a despesa atinge os limiares que definiu, mas não trava a API. Uma cota em “APIs e serviços” limita o número de pedidos por minuto ou por dia, e os pedidos acima dela falham. As boas práticas de segurança da Google recomendam limites de cota por minuto e por utilizador em projetos do lado do cliente. Defina a cota acima do seu pico real de tráfego, porque os visitantes legítimos também recebem erros quando ela é atingida.

A mesma página de março de 2025 deu o estado Legacy a três serviços: Places API, Directions API e Distance Matrix API. Os serviços legacy não recebem funcionalidades novas, e a página de produtos legacy diz que “não estão disponíveis em novos projetos Cloud” (tradução própria). Um projeto criado hoje tem de usar Places API (New) e Routes API. Por isso, exemplos de código que chamam google.maps.places.Autocomplete ou DirectionsService podem falhar num projeto novo, embora continuem a funcionar em projetos antigos.

#Como testar o impacto do Google Maps nos Core Web Vitals

1. Lighthouse mobile na URL de contacto sem clicar no mapa: o JS do Google não deve aparecer na cascata.
2. Depois do clique (e consentimento): aceite o custo; confirme que LCP do hero não depende do mapa.
3. Compare com Static Maps: muitas vezes o LCP melhora e o RGPD simplifica.

Se o mapa estiver above-the-fold, a fachada deve ser uma imagem real com dimensões reservadas (width/height ou aspect-ratio) para não introduzir CLS quando o canvas interativo substitui o botão.

#Como tornar o Google Maps acessível por teclado e leitor de ecrã

O mapa interativo não é navegável por teclado da mesma forma que um link “Abrir no Google Maps”. Ofereça sempre um fallback textual: morada completa + link https://www.google.com/maps/dir/?api=1&destination=LAT,LNG (ou o equivalente OSM). Leitores de ecrã e utilizadores com mapa bloqueado pelo CMP ainda chegam ao local.

#Plugin de Google Maps ou código próprio no WordPress

Um plugin de mapas justifica-se se a equipa editorial precisa de dezenas de localizações, rotas ou store locators sem developer em cada alteração. Para uma única morada de escritório, shortcode + fachada + CMP é menos superfície de ataque e menos PHP de terceiros a atualizar.

#Como corrigir erros comuns do Google Maps no WordPress

Quando um mapa fica cinzento ou mostra “This page can’t load Google Maps correctly”, a causa aparece na consola do browser como Google Maps API error: ERROR_CODE, seguida de um link. A referência de mensagens de erro da Google lista os códigos. Os que surgem em sites WordPress são estes:

Duas causas específicas do WordPress não aparecem como códigos de erro. Um plugin de cache ou de otimização que combina ou atrasa JavaScript pode executar o seu código de inicialização antes de o carregador do Maps terminar, por isso exclua os scripts do mapa da combinação. E um contentor de mapa sem altura aparece como uma faixa vazia: dê ao wrapper uma altura ou proporção explícita em CSS, o que também evita layout shift quando o mapa surge.

#Resumo

Integrar Google Maps em 2026 é equilíbrio entre UX, faturação e conformidade. Restrinja a chave, atrase o JS com uma fachada, respeite o RGPD e use Map IDs para estilo. Se só precisa de um pin, questione se a JavaScript API é necessária: a Maps Embed API pode bastar.

Mais sobre velocidade: como acelerar um site WordPress. Para implementação em produção (CMP + fachada + enqueue): contacto.