JavaScript and Node packages

Five npm packages, TypeScript first: @yatmo/sdk wraps the REST API for servers, browsers and edge runtimes; @yatmo/maps brings the browser plugins into a bundler project; @yatmo/elements gives any site the map, the nearest places and the neighbourhood text as HTML elements, with no framework; @yatmo/react and @yatmo/vue do the same with React and Vue components, server rendering included. ESM and CommonJS, Node 18 and later.

Install

npm install @yatmo/sdk        # server side: the API
npm install @yatmo/maps       # browser: the plugins
npm install @yatmo/elements   # any site: HTML elements (also from a CDN, no install)
npm install @yatmo/react      # React components
npm install @yatmo/vue        # Vue and Nuxt components

Source and issues: github.com/Yatmo/yatmo-sdk-js. Packages: @yatmo/sdk, @yatmo/maps, @yatmo/elements, @yatmo/react, @yatmo/vue. A runnable example is in yatmo-examples.

@yatmo/sdk

One client per country. Every method sends your key in the LicenseKey header, appends the language, and throws a YatmoError with the HTTP status on failure (400 point outside the country, 401 unknown key, 403 country or feature not in the licence, 429 quota, 0 network).

import { createYatmoClient } from '@yatmo/sdk';

const yatmo = createYatmoClient({ key: process.env.YATMO_KEY, country: 'BE', language: 'FR' });
const flat = { latitude: 50.8461, longitude: 4.3664 };

const summary = await yatmo.summary(flat);       // nearest places by category, with travel times
const scores = await yatmo.scores(flat);         // one 0 to 10 score per category
const enrichment = await yatmo.enrichment(flat); // nearest place of each category, for listing data

Neighbourhood text

The text comes back in every language of the country (summaryTextRaw, worth caching for a month) or resolved to one language with an English fallback (summaryText). renderSummaryText turns it into HTML headings and paragraphs to write into the page, so search engines index it; Markdown and plain text are available too.

import { createYatmoClient, renderSummaryText } from '@yatmo/sdk';

const text = await yatmo.summaryText(flat);
const html = renderSummaryText(text, {
  heading: 'h3',              // h2 to h6, or null
  titles: 'street-city',      // street in the first title, city in the second; 'city' for discreet listings; 'generic'
  paragraphs: ['education', 'shopping', 'publictransports', 'transports', 'tourism', 'cities'],
  strong: true,               // key places in <strong>
});
// <div class="yatmo-text"><h3>Commerces près de la Rue de la Loi</h3><p>Un <strong>Carrefour</strong> ...

All methods

Positions are { latitude, longitude }; mode is walking, bicycling, driving or transit. The models are the same as in the React Native SDK.

@yatmo/maps

Typed access to the browser plugins, which stay served by Yatmo so they are always current: iframeUrl, createIframe and mountIframe for the iframe plugin, mountMap, mountSummary and mountSummaryText for the JavaScript plugins.

import { mountIframe, mountMap, mountSummaryText } from '@yatmo/maps';

mountIframe('neighbourhood', { key: FRONTEND_KEY, country: 'BE', language: 'FR', latitude: 50.8461, longitude: 4.3664, mode: 'overlay', marker: 'circle', isochrone: 'right' });

await mountMap({ licenseKey: FRONTEND_KEY, country: 'BE', language: 'FR', container: 'map', center: [4.3664, 50.8461], zoom: 16 });

await mountSummaryText({ licenseKey: FRONTEND_KEY, country: 'BE', language: 'FR', latitude: 50.8461, longitude: 4.3664 }, { container: 'text' });

The map configuration is the yatmoConfig object of the JavaScript plugin, search features included; the plugin handles one map per page, so use iframes for several maps.

@yatmo/elements: one HTML element, no framework

Web components for sites without a build step (Webflow, Wix, Squarespace, Framer, Drupal, Laravel Blade, Rails, static HTML) and for any framework: load one script, declare the key once in <yatmo-config>, then place the elements with the property coordinates, or with its address alone (located by Yatmo once per page). They render plain HTML in the page, so your CSS applies. Step by step for no-code builders: Webflow tutorial.

<script type="module" src="https://cdn.jsdelivr.net/npm/@yatmo/elements@1/dist/yatmo-elements.js"></script>

<yatmo-config key="YOUR_FRONTEND_KEY" country="BE" language="FR"></yatmo-config>

<yatmo-map latitude="50.8461" longitude="4.3664" marker="circle" isochrone="right"></yatmo-map>
<yatmo-pois latitude="50.8461" longitude="4.3664" categories="education,shopping"></yatmo-pois>
<yatmo-text latitude="50.8461" longitude="4.3664"></yatmo-text>

<yatmo-map> takes every iframe plugin parameter as an attribute (mode, zoom, map-style, accent-color, marker, circle-radius, rounded, isochrone, route-from, height...) and follows attribute changes. <yatmo-pois> lists the nearest places by category (categories: education, transport, shopping, tourism; mode; limit). <yatmo-text> renders the neighbourhood text (paragraphs, heading, titles). Full reference in the package README; runnable page in yatmo-examples.

@yatmo/react: components for React, Next.js, Remix

import { YatmoMap, YatmoPois, YatmoNeighbourhoodText } from '@yatmo/react';

const yatmo = { key: FRONTEND_KEY, country: 'BE', language: 'FR', latitude: 50.8461, longitude: 4.3664 };

<YatmoMap licenseKey={FRONTEND_KEY} country="BE" language="FR" latitude={50.8461} longitude={4.3664} marker="circle" isochrone="right" />
<YatmoPois client={yatmo} categories={['education', 'shopping']} />
<YatmoNeighbourhoodText client={yatmo} />

YatmoMap is the iframe plugin with typed props and renders on the server; YatmoInteractiveMap is the JavaScript plugin (one per page, search features). YatmoPois and YatmoNeighbourhoodText fetch in the browser with client, or take summary and text fetched on the server with @yatmo/sdk: the text is then part of the HTML and indexed by search engines (Next.js server components, Remix loaders). Hooks useYatmoClient, useYatmoSummary and useYatmoText serve custom markup. Full reference in the package README; a complete listing page in yatmo-examples. For a whole site to start from, with server rendering, metadata and JSON-LD, clone the Next.js starter.

@yatmo/vue: components for Vue 3 and Nuxt

<script setup>
import { YatmoMap, YatmoPois, YatmoNeighbourhoodText } from '@yatmo/vue';
const yatmo = { key: FRONTEND_KEY, country: 'BE', language: 'FR', latitude: 50.8461, longitude: 4.3664 };
</script>

<template>
  <YatmoMap :license-key="yatmo.key" country="BE" language="FR" :latitude="50.8461" :longitude="4.3664" marker="circle" isochrone="right" />
  <YatmoPois :client="yatmo" :categories="['education', 'shopping']" />
  <YatmoNeighbourhoodText :client="yatmo" />
</template>

Same components as React: YatmoMap (iframe, server-renderable), YatmoInteractiveMap (JavaScript plugin), YatmoPois and YatmoNeighbourhoodText with client (fetched once mounted) or summary / text from @yatmo/sdk in a Nuxt useAsyncData (indexable), slots fallback, error and place; composables useYatmoClient, useYatmoSummary, useYatmoText. Full reference in the package README; a complete listing page in yatmo-examples.

@yatmo/astro: integration and components for Astro

// astro.config.mjs
import yatmo from '@yatmo/astro';
export default defineConfig({ integrations: [yatmo({ key: 'YOUR_FRONTEND_KEY', country: 'BE', language: 'FR' })] });

// src/pages/listings/[slug].astro
import { YatmoMap, YatmoPois, YatmoNeighbourhoodText } from '@yatmo/astro/components';
<YatmoMap latitude={50.8461} longitude={4.3664} marker="circle" isochrone="right" />
<YatmoPois address="Rue de la Loi 16, 1000 Bruxelles" categories="education,shopping" />
<YatmoNeighbourhoodText latitude={50.8461} longitude={4.3664} titles="city" />

The integration loads the web components once per page with your frontend key. YatmoMap, YatmoPois and YatmoText render in the browser; YatmoNeighbourhoodText fetches the text with the backend key (YATMO_KEY in .env) during astro build or per request in SSR, so it is part of the HTML search engines index. Reference in the package README.

@yatmo/nuxt: module for Nuxt 3 and 4

// nuxt.config.ts
export default defineNuxtConfig({ modules: ['@yatmo/nuxt'], yatmo: { country: 'BE', language: 'FR' } });
// .env: NUXT_PUBLIC_YATMO_KEY=frontend key, NUXT_YATMO_KEY=backend key

// pages/listings/[slug].vue
const { data } = await useYatmoNeighbourhoodText({ latitude, longitude }, { titles: 'city' });
<YatmoMap :latitude="latitude" :longitude="longitude" marker="circle" />
<YatmoPois :latitude="latitude" :longitude="longitude" />
<YatmoNeighbourhoodText v-if="data" :text="data.text" />

The module fills the key, country and language into the auto-imported @yatmo/vue components and adds useYatmoNeighbourhoodText, useYatmoSummary and useYatmo, which call Yatmo on the server with the backend key (indexable text) and in the browser with the frontend key. Reference in the package README.

gatsby-plugin-yatmo: plugin for Gatsby

// gatsby-config.js
plugins: [{ resolve: 'gatsby-plugin-yatmo', options: { key: 'YOUR_FRONTEND_KEY', country: 'BE', language: 'FR' } }]

// a listing template
import { YatmoMap, YatmoPois, YatmoNeighbourhoodText } from 'gatsby-plugin-yatmo';

The plugin injects the web components and your configuration in every page and re-exports the @yatmo/react components; fetch the text in gatsby-node.js with @yatmo/sdk and pass it to the template for an indexable page. Reference in the package README.

Which key where