Un filigrane « API KEY REQUIRED » est apparu sur votre carte OpenStreetMap ? Voici ce qui a changé

Depuis quelques jours, un filigrane diagonal « API KEY REQUIRED » barre la carte de contact de milliers de sites. Si le vôtre est concerné, rien n'a changé chez vous : c'est CARTO, le fournisseur du fond de carte, qui a changé les règles. Voici ce qui s'est passé, les options qui restent, celle que nous avons retenue pour notre propre carte, et un prompt prêt à l'emploi pour corriger vos sites.

Quand on intègre une « carte OpenStreetMap » sur un site, on utilise en réalité deux choses distinctes : les données (OpenStreetMap, libres) et le fond de carte, c'est-à-dire les images ou les tuiles vectorielles qui dessinent ces données dans un certain style. Ce fond est servi par un hébergeur, et pendant des années l'hébergeur le plus populaire a été CARTO (carto.com), une entreprise de cartographie et de géo-analytique.

CARTO proposait gratuitement, sans compte ni clé, trois styles devenus des standards de fait : Positron (le fond gris clair très sobre, light_all), Dark Matter (dark_all) et Voyager. Une URL à copier dans Leaflet, une ligne d'attribution, et c'était réglé. Des milliers de tutoriels, de thèmes WordPress et de plugins de carte reposent sur ces URL en basemaps.cartocdn.com.

CARTO vient de rendre une clé d'API obligatoire pour ces fonds. La raison avancée est double : un volume de requêtes devenu massif et l'impossibilité d'identifier ou de contacter les utilisateurs abusifs. Sans clé, le service n'est pas coupé, mais chaque tuile est livrée avec le filigrane « API KEY REQUIRED ». L'allocation gratuite est de 5 millions de tuiles par mois, la clé s'obtient par e-mail sans créer de compte, et la mesure s'applique d'abord aux tuiles raster (PNG) avant de s'étendre aux tuiles vectorielles.

Autrement dit : votre site n'a pas de bug. Il dépend d'un service tiers gratuit dont les conditions ont changé du jour au lendemain, ce qui est le risque inhérent à tout service tiers gratuit.

Le symptôme est sans ambiguïté : un texte gris en diagonale, « API KEY REQUIRED », répété sur toute la carte, avec parfois la mention carto.com/basemaps/apikey. Si vous voulez vérifier sans attendre qu'un client vous le signale, deux méthodes :

• Dans le navigateur, ouvrez les outils de développement, onglet Réseau, filtrez sur cartocdn et rechargez la page de contact. Toute requête vers ce domaine confirme la dépendance.
• Dans le code du site (thème, plugins, scripts), cherchez la chaîne cartocdn.com :

Les plugins de carte WordPress sont un cas particulier : le fond CARTO est souvent choisi dans un menu déroulant et l'URL n'apparaît nulle part dans vos fichiers. Regardez alors dans les réglages du plugin quel « tile provider » ou « basemap » est sélectionné.

C'est la voie de moindre effort : demander une clé, l'ajouter en paramètre de l'URL des tuiles, redéployer. Cinq millions de tuiles par mois couvrent largement un site vitrine. Le revers : vous restez dépendant d'un acteur qui vient précisément de démontrer qu'il pouvait changer les conditions d'usage sans préavis, avec désormais un compteur et un identifiant attachés à votre site.

Les serveurs de la fondation OpenStreetMap servent le style historique, celui que l'on voit sur openstreetmap.org, sans clé. C'est un dépannage honnête, mais le rendu est très différent d'un Positron (couleurs saturées, beaucoup de détails), et la politique d'usage de ces serveurs décourage explicitement les sites à fort trafic : ils sont financés par des dons et ne sont pas un CDN.

OpenFreeMap (openfreemap.org) publie des tuiles vectorielles issues d'OpenMapTiles, avec plusieurs styles dont un Positron quasi identique à celui de CARTO. Pas de clé, pas de quota, pas d'inscription : le projet est financé par des dons et son auteur est l'un des mainteneurs d'OpenMapTiles. Vous retrouvez la carte que vous aviez, à un détail technique près : les tuiles sont vectorielles, il faut donc un moteur de rendu GL pour les afficher. C'est l'option que nous avons retenue.

Notre carte était construite avec Leaflet, comme la majorité des cartes que nous croisons. Plutôt que de tout réécrire, nous avons conservé Leaflet (marqueur personnalisé, popup, contrôles de zoom) et remplacé uniquement la couche de fond, grâce à MapLibre GL, le moteur libre de rendu vectoriel, et au pont officiel @maplibre/maplibre-gl-leaflet. Deux dépendances de plus, une dizaine de lignes modifiées :

Si votre carte est déjà en MapLibre GL ou Mapbox GL, il suffit de changer l'URL du style. Sous OpenLayers, ol-mapbox-style joue le même rôle de pont. Dans tous les cas, l'attribution OpenFreeMap / OpenMapTiles / OpenStreetMap est obligatoire : c'est la seule contrepartie demandée.

Le résultat, en direct (la carte ci-dessous est celle de notre page de contact, insérée dans cet article) :

Première mise en ligne locale : la carte est grise. Le marqueur est là, l'attribution aussi, la console est vide, aucune erreur réseau. Le style est bien téléchargé, les sprites aussi, mais pas une seule tuile n'est demandée et map.isStyleLoaded() reste à false indéfiniment.

L'explication tient à la façon dont MapLibre travaille : le décodage des tuiles se fait dans un Web Worker, et depuis la version 5 la bibliothèque n'est distribuée qu'en modules ES. Elle crée son worker avec new Worker(new URL('./maplibre-gl-worker.mjs', import.meta.url), { type: 'module' }). Certains bundlers, Turbopack dans notre cas, interceptent ce motif et remplacent l'URL par l'un de leurs propres chunks, enveloppé dans leur runtime. Chargé dans un contexte worker, ce chunk ne fait strictement rien : il attend un runtime qui n'existe pas là. Le worker ne répond jamais, le style ne se charge jamais, et rien ne le signale.

Le correctif consiste à sortir le worker du circuit du bundler : copier maplibre-gl-worker.mjs et maplibre-gl-shared.mjs (le premier importe le second en chemin relatif) dans le dossier des fichiers statiques, puis indiquer à MapLibre où le trouver avant de créer la carte.

Le script tourne avant chaque démarrage et chaque build (dossier cible ignoré par Git, régénéré à chaque fois), ce qui évite de figer une version du worker dans le dépôt. Vérifiez que votre serveur renvoie ces fichiers en application/javascript.

Le style Positron affiche les noms de lieux en name:latin, avec repli anglais : vous verrez « Germany » et « Switzerland ». Les tuiles OpenMapTiles contiennent pourtant les noms dans des dizaines de langues. Une fois le style chargé, il suffit de réécrire l'expression text-field des calques de noms, en épargnant ceux des numéros de routes :

Sur un site multilingue, passez la langue de la page : la carte suit alors le visiteur, « Suisse » en français, « Switzerland » en anglais.

MapLibre GL pèse environ 250 Ko compressés, auxquels s'ajoute le module partagé rechargé par le worker. C'est dix fois plus que Leaflet seul. Si la carte se trouve en bas de page, ne la montez qu'à l'approche du viewport, avec un IntersectionObserver et un espace réservé de même hauteur pour ne pas provoquer de décalage de mise en page. Sur une page de contact, ce surcoût reste invisible pour le visiteur ; sur une page d'accueil, il mérite ce montage différé.

Si vous travaillez avec un agent de code (Claude Code ou équivalent), voici le prompt que nous utilisons pour appliquer cette correction sur un site existant. Il est volontairement complet : inventaire avant modification, bascule adaptée à la bibliothèque en place, attribution, piège du worker, libellés localisés, performance, et une liste de vérifications qui interdit à l'agent de déclarer la tâche terminée sans avoir regardé le résultat dans un navigateur. Adaptez la section « Contraintes » à vos propres règles.

Un service gratuit sans contrat n'est pas une dépendance gratuite : c'est une dépendance dont le coût est différé et dont l'échéance ne dépend pas de vous. CARTO a le droit de changer ses conditions, et l'a fait proprement, avec un filigrane plutôt qu'une coupure. Il n'en reste pas moins que des milliers de sites affichent aujourd'hui une carte dégradée sans que personne, côté propriétaire, n'ait touché à quoi que ce soit.

La correction prend une heure quand on connaît le piège du worker, une demi-journée quand on le découvre. Le résultat vaut la peine : le même rendu, des libellés dans la langue de vos visiteurs, et une chaîne entièrement libre, des données OpenStreetMap au moteur de rendu, avec un hébergeur dont le modèle est précisément de ne pas exiger de clé. Si votre carte affiche le filigrane et que vous ne savez pas par où commencer, notre page de contact a une carte toute neuve pour vous montrer le chemin.