Aperçu

unmap est une API cartographique canadienne, axée sur la protection de la vie privée. Une seule clé couvre trois services :

• Cartes : le fond de carte lui-même, soit des données cartographiques servies en périphérie et des styles MapLibre prêts à l'emploi qui les dessinent. Neuf styles de carte, chacun en clair et en sombre, avec le relief et les courbes de niveau là où les données existent.
• Géocodage : recherche en texte intégral, saisie semi-automatique, recherche par catégorie (« la pharmacie la plus proche ») et géocodage inverse sur les adresses et lieux canadiens. Bilingue (anglais et français) par défaut, avec les noms de lieux autochtones officiels lorsque les sources les fournissent.
• Itinéraires : itinéraires point à point et zones de temps de trajet sur le réseau routier canadien, en voiture, en camion, à vélo et à pied.

L'objectif de conception est un délai jusqu'au premier Hello World de moins de 60 secondes, avec deux instructions de code après l'installation.

Le vocabulaire des cartes, en une minute

Si vous n'avez jamais intégré d'API cartographique, ces termes couvrent l'essentiel de ce que le reste de ces pages suppose connu.

• Tuile. La carte est découpée en carrés pour que le navigateur ne télécharge que ceux qui sont à l'écran. /tiles/11/375/685 désigne un carré : zoom 11, colonne 375, ligne 685. Vous en demanderez rarement un vous-même, car MapLibre détermine ceux dont il a besoin.
• Zoom. Un nombre entier de 0, le monde entier dans une seule tuile, à 14, le niveau le plus détaillé servi par unmap. Chaque palier double le détail. Une ville tient autour du zoom 11.
• Tuile vectorielle. Nos tuiles contiennent des données (une route, un parc, une étiquette) plutôt qu'une image de route. C'est le navigateur qui les dessine, ce qui explique pourquoi la carte reste nette sur un écran haute densité et pourquoi une même tuile peut être dessinée dans neuf styles différents.
• Fond de carte. La carte sous tout ce que vous ajoutez par-dessus. Vos marqueurs, vos itinéraires et vos données vous appartiennent; le fond de carte est l'arrière-plan sur lequel ils reposent.
• Style. Un document JSON qui indique à MapLibre comment dessiner les tuiles : quelles couleurs, quelles polices, quoi afficher à quel zoom. Ce n'est pas du CSS, et vous n'avez pas à en écrire un. Vous demandez un style par son nom.
• Géocodage. Transformer du texte en coordonnée, par exemple « Calgary Tower » en une longitude et une latitude. Le géocodage inverse fait le chemin contraire, d'une coordonnée vers l'adresse ou le lieu le plus proche.
• Isochrone. La zone que vous pouvez atteindre depuis un point dans un temps donné, retournée sous forme de polygone. Tout ce qui est à moins de 15 minutes en voiture, par exemple.

Une règle piège presque tout le monde au moins une fois : les coordonnées sont [longitude, latitude], dans cet ordre, ici comme en GeoJSON. La longitude est le nombre est-ouest, négatif au Canada. La latitude est le nombre nord-sud. Si votre carte atterrit dans l'océan Indien, les deux sont inversés.

Le paquet @unmap/sdk réunit les trois services derrière une seule clé de style Stripe (um_live_... en production, um_test_... en développement). Créez l'instance une seule fois :

import { Unmap } from "@unmap/sdk";
 
const unmap = new Unmap({ key: "um_live_..." });
 
await unmap.geocoder.search("Calgary Tower");
await unmap.router.route([-114.07, 51.05], [-113.99, 51.05]);

Passez un container et vous obtenez aussi une carte affichée :

const map = new Unmap({
  key: "um_live_...",
  container: "map",
  center: [-114.07, 51.05],
});
 
map.map; // la carte MapLibre GL sous-jacente
map.geocoder; // search / autocomplete / nearby / reverse
map.router; // route / isochrone

La surface de l'API

new Unmap(options) accepte :

style choisit la façon dont la carte est dessinée; center et zoom choisissent où elle commence. mode, lang et theme choisissent comment elle est dessinée. style: 'base' avec mode: 'dark' et center: [-73.5673, 45.5017] est une requête valide. La liste complète des styles, et ce que mode, lang et theme font sur la passerelle, se trouve dans l'API de cartes.

L'instance expose :

• .map est la carte MapLibre GL (seulement quand un container a été fourni). Surface compatible Mapbox-GL-JS.
• .geocoder offre search(q, opts?), autocomplete(q, opts?), nearby(category, opts), reverse(lng, lat, opts?). Voir l'API de géocodage.
• .router offre route(from, to, opts?), isochrone(center, { minutes, mode? }). Voir l'API d'itinéraires.

Chaque méthode retourne une promesse du même JSON que la passerelle renvoie, donc les pages de référence de l'API décrivent aussi les types de retour du SDK. Une réponse non 2xx lève une GeocoderError ou une RouterError qui porte le status HTTP.

Ce que documente unmap, et ce que documente MapLibre

@unmap/maps est une enveloppe mince. createMap() construit l'URL du style, y insère votre clé et retourne une carte MapLibre GL JS, sans envelopper la carte elle-même. Ces pages documentent donc la passerelle, les neuf styles et les trois éléments ajoutés par le SDK : .map, .geocoder et .router. Tout ce que vous faites à une carte par la suite relève de l'API de MapLibre, documentée en amont sur maplibre.org, en anglais seulement.

Cette répartition vaut la peine d'être connue avant de venir chercher ici une page qui n'existe pas :

• Événements : map.on('click', …), 'load', 'moveend', 'error'. MapLibre.
• Sources et couches : addSource(), addLayer(), setPaintProperty(). MapLibre, ainsi que la spécification de style.
• Caméra : flyTo(), fitBounds(), easeTo(). MapLibre.
• Marqueurs, infobulles et contrôles : Marker, Popup, ScaleControl. MapLibre. (NavigationControl est déjà sur la carte ; controls: false le retire.)
• Styles, clés, quotas et les points de terminaison correspondants : ici.

Aucun second import n'est nécessaire. @unmap/maps réexporte l'exemplaire même de MapLibre que votre application a installé (il prend maplibre-gl comme dépendance de pair au lieu d'embarquer le sien) : import { maplibregl } from "@unmap/maps" vous donne les mêmes constructeurs Marker et Popup, sans dupliquer MapLibre dans votre paquet.

Villes de démonstration

Trois villes de lancement, exportées sous DEMO_CITIES. Ce sont des cadrages de départ, pas des cartes différentes, et chaque style fonctionne sur chacune d'elles.

• calgary pour Calgary, en Alberta
• montreal pour Montréal, au Québec
• iqaluit pour Iqaluit, au Nunavut

Réglez le cadrage avec center et zoom, pas avec style. Un nom de ville dans style est reconnu puis écarté (le SDK n'ira pas chercher /styles/montreal.json), donc style: 'montreal' affiche base depuis le cadrage par défaut au lieu de déplacer la caméra. Les tuiles couvrent tout le Canada, donc une fois la carte affichée, vous pouvez la déplacer n'importe où. Une ville n'est que le point de départ.

Paquets

@unmap/sdk est l'installation en une ligne. Chacune de ses pièces est aussi publiée séparément, pour quand vous n'avez besoin que d'un service ou voulez garder un bundle léger. Aucun n'est requis : la passerelle est du HTTPS et du JSON ordinaires, et Appeler l'API directement montre les mêmes appels depuis curl, fetch, Python et un MapLibre standard. Si votre page n'a aucune étape de compilation, le SDK se charge aussi depuis une balise de script ; voyez le Démarrage rapide.

Les utilisateurs de React commencent par @unmap/react (les hooks) ou, avec l'App Router de Next.js, par @unmap/next (un <Map> prêt à poser). Pour une interface plus riche et modifiable, comme une boîte de recherche, un panneau d'itinéraire et des marqueurs, le registre de composants installe des composants de style shadcn construits sur @unmap/maps, dont vous possédez le code.

Pourquoi unmap

• Untracked (sans pistage). Les clés sont mesurées, pas les personnes.
• Unlocked (sans verrou). Mise en cache permissive, aucune horloge d'expiration sur ce que vous mettez en cache.
• Unbundled (dégroupé). Une seule clé pour les cartes, le géocodage et les itinéraires.
• Infrastructure nord-américaine. Le réseau périphérique nord-américain de Cloudflare (ENAM/WNAM). Nous ne pouvons pas garantir une résidence des données limitée au Canada sur les forfaits libre-service. Contactez-nous si vous avez besoin d'une garantie contractuelle.

Attribution et sources de données

Contient des renseignements rendus disponibles sous la Licence du gouvernement ouvert - Canada par Ressources naturelles Canada (Base de données toponymiques du Canada). Données cartographiques et d'adresses (c) contributeurs d'OpenStreetMap. Le graphe d'itinéraires est construit à partir des mêmes données OpenStreetMap, sous la licence Open Database License (ODbL). Le relief est dérivé du Modèle numérique d'élévation du Canada de RNCan.

Pour les avis sur les données de compte et les caches, consultez la politique de confidentialité et les conditions.

Une note sur les noms de lieux autochtones. Les données de géocodage d'unmap comprennent des noms de lieux officiels en langues autochtones, tirés de la Base de données toponymiques du Canada, un jeu de données ouvert et maintenu par le gouvernement. Il s'agit uniquement de noms officialisés. Les noms de lieux détenus par les communautés et les noms traditionnels font l'objet d'une démarche distincte, fondée sur le consentement, que nous n'avons pas entreprise : tout travail futur dans cette direction suivrait les principes PCAP (propriété, contrôle, accès et possession), en partenariat avec les communautés concernées, plutôt qu'une importation de données. Rien ici ne doit être interprété comme un appui des communautés.

Prêt à afficher quelque chose? Rendez-vous au Guide de démarrage ou aux Exemples. Avant la mise en production, Authentification couvre les formes de clé, les origines autorisées et la séparation navigateur/serveur. Vous venez de Google Maps, Mapbox, HERE ou Esri? Les guides de migration traduisent les appels que vous avez. Vous vous demandez pourquoi ce produit existe? Nous en faisons la démonstration, preuves à l'appui, dans Why another maps API? (en anglais).