Come integrare una mappa di mobilità nel proprio sito?

Per integrare una mappa di mobilità nel tuo sito senza costruire tutta l’interfaccia, usa un iframe ROOTE. L’embed può ricevere una ricerca per città e filtri adatti alla pagina: bici per una guida bici, toilette per una guida WC, bus e tram per i trasporti.

Gli esempi di questa guida utilizzano embed.roote.ai, il dominio integrato nelle guide ROOTE. La documentazione generale descrive anche l’integrazione di map.roote.ai e distingue i parametri della telecamera da quelli di una ricerca completa.

Aggiungere un iframe responsive

Questo blocco apre una ricerca bici a Bordeaux con zoom 15. L’URL è costruito nel codice; il titolo dell’iframe descrive il contenuto per i lettori di schermo. Adatta questo titolo alla lingua della tua pagina.

<iframe
  title="Carte ROOTE — vélos à Bordeaux"
  src="https://embed.roote.ai/?q=Bordeaux&amp;modes=bicycle&amp;zoom=15"
  width="100%"
  height="480"
  loading="lazy"
  allow="geolocation"
  style="display:block; width:100%; min-height:360px; border:0; border-radius:16px;"
></iframe>

In un attributo HTML, i separatori & si scrivono &. La larghezza del 100% segue quella del contenitore. Mantieni un’altezza utilizzabile su mobile e evita di posizionare controlli indispensabili fuori dalla zona visibile.

Scegliere le modalità corrispondenti alla pagina

Questi valori sono quelli del percorso embed ROOTE collegato alle famiglie mobilità, servizi e transito. Non sostituiscono i parametri REST: Services usa types, mentre Transit usa modes. Una mappa centrata su una città non garantisce che ogni famiglia abbia risultati in essa.

Distinguere la telecamera e l’origine della ricerca

lat e lon posizionano la telecamera. Non sono sufficienti, nel contratto documentato della mappa, per creare una ricerca di prossimità. Per ripristinare una ricerca nota, usa search_lat, search_lon e search_label, con modes e zoom.

https://embed.roote.ai/?search_lat=44.8416106&search_lon=-0.5810938&search_label=Bordeaux&zoom=15&modes=bus,tram

Le coordinate sopra sono un punto di riferimento a Bordeaux, non la posizione dell’utente. Se aggiungi anche parametri della telecamera, puoi mostrare un’altra zona mantenendo il punto usato per le distanze. Fai ciò solo se questa separazione è voluta.

Documentazione dei parametri della mappa ROOTE

Costruire un URL senza perdere caratteri speciali

Usa URL e URLSearchParams invece di una concatenazione manuale. Questo codifica spazi, accenti e separatori. Questo codice è destinato al browser e crea l’indirizzo dell’iframe a partire da un luogo inserito.

const embedUrl = new URL('https://embed.roote.ai/');
embedUrl.searchParams.set('q', 'Place des Quinconces, Bordeaux');
embedUrl.searchParams.set('modes', 'bicycle,toilets');
embedUrl.searchParams.set('zoom', '15');
document.querySelector('iframe').src = embedUrl.toString();

Conservare il contesto verso la mappa completa

Un link a map.roote.ai deve riportare lo stato corrente della ricerca se lo conosci. Ricreare un URL senza parametri perde città, modalità o zoom. Mantieni un oggetto URL comune durante gli aggiornamenti fatti dalla tua pagina.

const fullMapUrl = new URL('https://map.roote.ai/');
fullMapUrl.search = embedUrl.search;
const link = document.querySelector('[data-open-map]');
link.href = fullMapUrl.toString();
link.target = '_blank';
link.rel = 'noopener noreferrer';

Questo codice conserva i parametri conosciuti dalla pagina padre. Se l’utente modifica la ricerca dentro l’iframe, il genitore non può leggere direttamente il suo URL su un altro dominio. Per recuperare questo stato, serve un meccanismo esplicitamente implementato e documentato, per esempio uno scambio postMessage con validazione dell’origine. Non inventare nomi di eventi non forniti dall’embed.

Gestire la localizzazione e le interazioni mobile

allow="geolocation" permette all’iframe di richiedere la localizzazione, subordinato al consenso e alla politica dei permessi del sito. Un rifiuto deve lasciare usabile la ricerca per città. Non chiedere la posizione appena si arriva su una pagina se il lettore non ha scelto questa azione.

In un articolo, un’attivazione volontaria della mappa può evitare che lo scroll o lo zoom catturino gesti durante la lettura. Il controllo deve rimanere accessibile da tastiera e chiaramente nominato. Verifica i cambi di orientamento e uno schermo stretto, non solo la versione desktop.

Verificare il risultato e gli stati di errore

Testa ogni filtro, una città nota, una zona con pochi dati, una ricerca non valida e una famiglia non disponibile. Una mappa senza marker non dice, da sola, se la ricerca è vuota o guasta. Conserva i messaggi dell’embed e un accesso usabile alla mappa completa.

Distinguere assenza di risultato ed errore API

Scegliere tra embed, API e MCP

Esempio di guida per trovare toilette

Domande frequenti

È necessario mettere una chiave API nell’iframe?

Gli URL pubblici mostrati qui non ne contengono. Non mettere un segreto in un URL di embed o nel codice client.

zoom=15 aumenta il raggio di ricerca?

Lo zoom regola la vista. Non confonderlo con il raggio di una richiesta API; verifica i parametri di ricerca dell’interfaccia usata.

Il genitore conosce i cambiamenti fatti nell’iframe?

Conosce i parametri che trasmette. Le modifiche interne richiedono un meccanismo di scambio documentato tra i due domini.