=== Yatmo Neighbourhood Map ===
Contributors: yatmo
Tags: real estate, map, neighbourhood, seo, property
Requires at least: 6.3
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 2.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Neighbourhood of a property: map, points of interest, travel times, and a written description indexed by search engines. For Yatmo customers.

== Description ==

Yatmo gives real estate websites neighbourhood intelligence: schools, shops, public transport, healthcare and more around each property, with real travel times on foot, by bike, by car and by public transport, and a written summary of the area.

This plugin brings Yatmo to your property pages with two blocks, also available as shortcodes:

* **Yatmo Neighbourhood Map**: the interactive Yatmo widget (map, places, travel times, summary). You choose the layout and the look in the block sidebar; the plugin builds the embed, so there is no URL to write and no JavaScript to add to your theme.
* **Yatmo Neighbourhood Text**: a written description of the neighbourhood (schools, shops, public transport, roads, leisure, nearby cities), inserted in the page as ordinary headings and paragraphs, so search engines and AI assistants read it as part of your listing.

**A Yatmo licence key is required.** Yatmo is a paid service for real estate portals, agency networks and developers. [Contact us](https://yatmo.com) to get a key; the plugin displays nothing to visitors until a key is entered.

= Features =

* **Block editor**: "Yatmo Neighbourhood Map" and "Yatmo Neighbourhood Text" blocks with a live preview and all options in the sidebar.
* **Shortcodes** `[yatmo-map]` and `[yatmo-text]` for the classic editor, page builders and PHP templates.
* **Indexable text**: rendered on your server, cached, styled by your theme; choose the paragraphs and the heading level, and hide the street name for discreet listings.
* **Listing templates**: point the plugin to the custom fields where your theme or listing plugin stores the property coordinates, and one block in the template serves every property.
* **Six layouts**: map with summary, map with Yatmo scores, map above the summary, map only, summary only, summary in tabs.
* **Discreet location**: show a circle instead of a pin when the exact address must stay private.
* **Isochrones and routes**: areas reachable in 5, 10 and 20 minutes, and the route from the property to any place the visitor clicks.
* **Favourite addresses**: logged-in visitors save their home or office and see their own commute from every property.
* **Multilingual**: 23 languages; by default the widget follows the language of the page, including with WPML and Polylang.
* **Cookieless and lightweight**: one lazy-loaded iframe for the map, plain HTML for the text, no script or style added to your pages.

= Countries =

Albania, Australia, Austria, Belgium, Bosnia and Herzegovina, Bulgaria, Canada, Croatia, Cyprus, France, Germany, Greece, Ireland, Italy, Luxembourg, Malta, Montenegro, Morocco, the Netherlands, Portugal, Serbia, Slovenia, Spain, Switzerland and the United Kingdom.

= External services =

This plugin relies on Yatmo, a third-party service operated by Yatmo SRL, to display its content and to locate addresses.

* **Yatmo widget** (`https://map.yatmo.com/plugin.html`): every page with a Yatmo block or shortcode embeds this page in an iframe. The visitor's browser loads it, with your licence key, the country, the language, the display options and the property coordinates. The widget itself then loads the map, the points of interest and the travel times from Yatmo servers. When favourite addresses are enabled, it also receives an anonymous identifier of the logged-in visitor (a hash of the WordPress user id, which Yatmo cannot turn back into the user) and the addresses that visitor saves.
* **Yatmo neighbourhood text** (`https://<country>.yatmo.com/Summary/text`): for each property shown with the text block or shortcode, your server sends the property coordinates and your licence key, and stores the returned text for 30 days.
* **Yatmo geocoder** (`https://<country>.yatmo.com/Geolocation`, for example `https://be.yatmo.com/Geolocation`): when a block or shortcode is given an address instead of coordinates, your server sends that address, the country and your licence key once, and stores the result for 90 days.

Yatmo sets no cookies. [Terms of service](https://yatmo.com/terms), [privacy policy](https://yatmo.com/privacy).

== Installation ==

1. Install the plugin from Plugins > Add New, or upload the `yatmo-map` folder to `/wp-content/plugins/`, then activate it.
2. Go to Settings > Yatmo Map, enter your Yatmo licence key and choose your country and default look.
3. Add the "Yatmo Neighbourhood Map" block to a page, or the `[yatmo-map]` shortcode, and give it an address or coordinates.

For listing templates, fill in the latitude and longitude custom fields in Settings > Yatmo Map and leave the location of the block empty: each property then shows its own neighbourhood.

== Frequently Asked Questions ==

= Where do I get a licence key? =

From Yatmo: [yatmo.com](https://yatmo.com). Use your frontend key, the one locked to your domains, never your backend key.

= Which shortcode attributes are available? =

All are optional; anything left out uses the settings page.

* `address`, or `latitude` and `longitude`
* `country` (BE, FR, UK...), `language` (EN, FR, NL...)
* `mode`: `overlay`, `overlay-scores`, `map-top`, `map`, `summary`, `summary-tabs`
* `height` (`560` or `70vh`), `zoom` (7 to 20), `map_style` (1 to 7), `rounded` (0 to 15)
* `marker`: `pin`, `circle` (with `circle_radius` in metres, 50 to 2000) or `custom` (with `custom_marker_url`, `custom_marker_width`, `custom_marker_height`)
* `accent_color`, `summary_background_color`, `summary_line_color` (hex colours)
* `isochrone` and `route_from`: `left`, `right` or `off`; `route_from` also accepts `popup`
* `title`: accessible title of the embed

Example: `[yatmo-map address="Rue de la Loi 16, 1000 Bruxelles" mode="map-top" marker="circle" isochrone="right"]`

= And for the neighbourhood text? =

`[yatmo-text]` takes the same `address`, `latitude`, `longitude`, `country` and `language`, plus:

* `paragraphs`: comma-separated among `education`, `shopping`, `publictransports`, `transports`, `tourism`, `cities`
* `heading`: `h2` to `h6`
* `street_in_title`, `city_in_title`: `1` or `0`

Example: `[yatmo-text address="Rue de la Loi 16, 1000 Bruxelles" paragraphs="education,shopping,publictransports" heading="h3"]`

The text exists in the languages of the property's country (French, Dutch and English in Belgium, for example), otherwise in English.

= Can I use it in a theme template? =

Yes: `<?php echo do_shortcode( '[yatmo-map]' ); ?>` with the custom fields set in Settings > Yatmo Map. Developers can also supply the location with the `yatmo_map_location` filter and adjust the embed with the `yatmo_map_iframe_params` filter.

= Is the text indexed by search engines? =

The neighbourhood text is: it is part of your page's HTML. The summary panel inside the map widget is not, since the widget is an iframe; use both blocks together for the best of both.

= I used the yatmo-text plugin =

Its features are now in this plugin: deactivate and delete yatmo-text, keep your `[yatmo-text]` shortcodes. `lat`, `lng`, `visibleparagraphs`, `showstreetnameintitle` and `showplacenameintitle` still work; the `*nodetype` attributes are ignored (use `heading`, and your theme for the style).

= I used version 1.x with [yatmo-marker] =

Version 2 shows one property per embed. The `lat`, `lng`, `style` and `enable_isochrone` attributes still work on `[yatmo-map]`; `[yatmo-marker]` is ignored (it prints nothing), so give the location on `[yatmo-map]`.

== Screenshots ==

1. Map and neighbourhood summary on a property page.
2. The block and its settings in the block editor.
3. Summary in tabs, without the map.
4. Circle instead of a pin, with isochrones.
5. The settings page.
6. The neighbourhood text on a property page.

== Changelog ==

= 2.0.0 =
* Rebuilt around the Yatmo iframe widget: map, summary, scores, isochrones, routes and favourite addresses.
* New "Yatmo Neighbourhood Map" block for the block editor.
* Neighbourhood text (formerly the yatmo-text plugin): "Yatmo Neighbourhood Text" block and `[yatmo-text]` shortcode, rendered as indexable HTML.
* Property coordinates read from custom fields, for listing templates.
* Addresses located by the Yatmo geocoder instead of Nominatim.
* A Yatmo licence key is now required.
* Removed: multiple markers and marker popups.

= 1.0.0 =
* First version.

== Upgrade Notice ==

= 2.0.0 =
Major rewrite: a Yatmo licence key is now required and [yatmo-marker] is no longer displayed. Check your settings after updating.
