Utiliser l’API Google Maps avec ACF dans votre administration WordPress

Si vous utilisez le champ Google Maps de l’extension Advanced Custom Fields, il est dorénavant nécessaire d’obtenir une clé d’API auprès de Google pour chacun de vos projets Web.

ACF vous permet de déclarer cette clé pour la partie back-office de WordPress, à l’aide d’un réglage ou d’un filtre. Sans elle, la carte du champ s’affiche assombrie, barrée de la mention « For development purposes only », et un message indique « Impossible de charger Google Maps correctement sur cette page ».

Google exige en effet une clé valide pour chaque requête, sur les anciens sites comme sur les nouveaux, ainsi qu’un compte dont la facturation est activée. Si vous vérifiez votre console JavaScript à partir des outils de développement de votre navigateur favori, il y a de fortes chances que vous obteniez les messages d’erreurs suivants :

Google Maps JavaScript API error: ApiProjectMapError
https://developers.google.com/maps/documentation/javascript/error-messages#api-project-map-error
Google Maps JavaScript API warning: NoApiKeys https://developers.google.com/maps/documentation/javascript/error-messages#no-api-keys

Pour obtenir cette fameuse clé, suivez simplement les instructions de Google. Elles sont très simples à comprendre et rédigées en français. Pas de panique donc !

Dans votre projet Google Cloud, activez la facturation, exigée par Google pour une utilisation en production, puis les trois API qu’utilise le champ d’ACF : Maps JavaScript API, Geocoding API et Places API.

Pour Places API, ACF s’appuie encore sur l’ancienne version, au statut « Legacy » chez Google depuis le 1er mars 2025 : la console JavaScript signale d’ailleurs que sa classe de recherche d’adresse, google.maps.places.Autocomplete, n’est plus disponible pour les nouveaux clients. Sur un nouveau projet, la documentation d’ACF indique d’activer cette ancienne Places API, et non Places API (New), en attendant que le champ passe à la nouvelle version.

Restreignez ensuite votre clé, comme le recommande Google dans ses bonnes pratiques de sécurité pour les clés d’API : limitez-la à vos sites Web et aux seules API utilisées. Elle apparaît en effet en clair dans le code source des pages où le champ affiche la carte.

ACF propose deux méthodes pour déclarer la clé, décrites dans la documentation de son champ Google Map. Elles fonctionnent avec la version gratuite comme avec ACF PRO, qui partage le même code : choisissez-en une seule. Elles valent aussi pour Secure Custom Fields, l’extension publiée par WordPress.org à partir du code d’ACF, qui reprend le même réglage et le même filtre.

Méthode n°1 – Le réglage google_api_key

Dans un mu-plugins de préférence ou votre fichier functions.php présent dans votre thème, copiez ces lignes de code :

/* ACF Google Maps */
function wpc_acf_init() {
	acf_update_setting('google_api_key', 'VOTRE_CLE_ICI');
}
add_action('acf/init', 'wpc_acf_init');

Remplacez VOTRE_CLE_ICI par la clé obtenue auprès de Google puis enregistrez le fichier.

Méthode n°2 – Le filtre acf/fields/google_map/api

Autre possibilité, au même endroit : le filtre acf/fields/google_map/api, qui reçoit les paramètres de chargement de l’API Google Maps, dont la clé. Remplacez là aussi VOTRE_CLE_ICI par votre clé :

function wpc_acf_google_map_api($api) {
	$api['key'] = 'VOTRE_CLE_ICI';
	return $api;
}
add_filter('acf/fields/google_map/api', 'wpc_acf_google_map_api');

Une fois la clé renseignée, Google Maps sera de nouveau opérationnelle en back-office et votre console JavaScript n’affichera plus de messages d’erreurs.

Si la console signale encore une erreur, son code vous indique quoi corriger : InvalidKeyMapError pour une clé erronée, ApiNotActivatedMapError si Maps JavaScript API n’est pas activée, LegacyApiNotActivatedMapError si c’est l’ancienne Places API, BillingNotEnabledMapError si la facturation n’est pas activée, RefererNotAllowedMapError si votre site ne fait pas partie de ceux autorisés pour la clé. Les avertissements sur google.maps.Marker et google.maps.places.Autocomplete, eux, viennent des classes qu’utilise encore ACF, et non de votre clé.

Ces deux méthodes servent au champ, dans l’administration : elles ne chargent pas l’API Google Maps sur les pages de votre site. Pour y afficher la carte, votre thème doit la charger lui-même avec votre clé, comme dans le code d’exemple de la documentation d’ACF citée plus haut.

Vous utilisez ACF avec Elementor ? Voici comment afficher un champ répéteur ACF dans Elementor.