Summary endpoint

Get neighbourhood intelligence for a coordinate — nearest POIs grouped by category, closest cities, and travel times. The single most useful endpoint for real-estate use cases.

Request

Required parameters

Examples

curl -H 'LicenseKey: YOUR_KEY' \
  'https://be.yatmo.com/summary?latitude=50.8520525&longitude=4.3442926&language=EN'

const res = await fetch(
  'https://be.yatmo.com/summary?latitude=50.8520525&longitude=4.3442926&language=EN',
  { headers: { LicenseKey: 'YOUR_KEY' } }
);
const summary = await res.json();
console.log(summary.CloseCities);

$ch = curl_init('https://be.yatmo.com/summary?latitude=50.8520525&longitude=4.3442926&language=EN');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['LicenseKey: YOUR_KEY']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$body = curl_exec($ch);
curl_close($ch);
$summary = json_decode($body, true);

using var http = new HttpClient();
http.DefaultRequestHeaders.Add("LicenseKey", "YOUR_KEY");
var url = "https://be.yatmo.com/summary?latitude=50.8520525&longitude=4.3442926&language=EN";
var json = await http.GetStringAsync(url);
// Deserialize into your own DTO matching CustomerItemSummary

Response shape

The response is a CustomerItemSummary object. The most important fields:

Each POI nested in AvailableCategoriesAroundPosition[*].SubCategories[*].Data[*] carries a TravelDataElements array with one entry per travel mode (driving, walking, cycling, transit) — each with both raw values (PreciseTravelDistanceData in meters, TravelTime in seconds) and pre-formatted labels (PreciseTravelDistanceLongLabel, TravelTimeShortLabel, etc.) in the requested language.

Narrative text variants

Alongside the raw structured payload above, two sibling endpoints return ready-to-publish neighbourhood paragraphs — the same human-readable text that powers the Summary-text plugin. Use these when you want descriptive copy for a listing page rather than wiring up the structured fields yourself.

Text only — GET /summary/text

Note there is no language parameter: a single call returns every paragraph in all languages supported for that country (for France: FR, EN, PT, DE, ZH), so you can cache one response and render any locale. The body is a MultiLanguagesText object — an ordered list of Paragraphs, each with an IconId (e.g. transport, school), and language-keyed maps for the text.

Each paragraph carries up to three heading variants at increasing geographic scope: Title is the bare category (e.g. Transports), TitleBis qualifies it with the immediate area (Transports around Cours Vitton), and TitleTer qualifies it with the city (Transports in Lyon). Only Title is always present; TitleBis and TitleTer are omitted when not available. Below the headings come an array of language-keyed Sentences and an optional language-keyed bullet List.

{
  "Paragraphs": [
    {
      "IconId":   "transport",
      "Title":    { "FR": "Transports", "EN": "Transports", "PT": "Transportes", "DE": "Transporte", "ZH": "交通工具" },
      "TitleBis": { "FR": "Transports autour de la Cours Vitton", "EN": "Transports around Cours Vitton", "PT": "Transporte perto de Cours Vitton", "DE": "Transporte in der Nähe von Cours Vitton", "ZH": "Cours Vitton 周围的交通工具" },
      "TitleTer": { "FR": "Transports à Lyon", "EN": "Transports in Lyon", "PT": "Transportes no Lyon", "DE": "Transporte in Lyon", "ZH": "Lyon 的交通工具" },
      "Sentences": [
        { "FR": "Ce bien profite d’un cadre de vie connecté aux transports du quartier …", "EN": "This property enjoys a setting well connected to the area’s transport …" }
      ],
      "List": []
    },
    {
      "IconId": "school",
      "Title":  { "FR": "Écoles", "EN": "Schools" },
      "Sentences": [ { "FR": "…", "EN": "…" } ],
      "List": [ { "FR": "Groupe scolaire … — 320 m", "EN": "…" } ]
    }
  ]
}

The example above is shown decoded for readability. On the wire, values are serialised with non-ASCII escaping: every accented or non-Latin character is emitted as a \uXXXX escape — à → \u00e0, … → \u2026, the curly apostrophe ’ → \u2019, and CJK such as 交通工具 → \u4ea4\u901a\u5de5\u5177. Any standard JSON parser turns the escapes back into these characters, so no special handling is needed. The Sentences and List maps above are abridged to FR/EN for brevity; a live response repeats every one of the country’s language keys in each map, exactly as the three Title maps show.

Text and data — GET /summary/text-and-data

The response wraps both payloads under two top-level keys: Data is the exact same CustomerItemSummary object as GET /summary (see Response shape above), localised to the requested language; and Text is the identical MultiLanguagesText structure returned by /summary/text. One round-trip when you want both the machine-readable fields and the prose.

{
  "Data": { "AvailableCategoriesAroundPosition": [ "…" ], "CloseCities": [ "…" ], "PlaceInformation": { "…": "…" } },
  "Text": { "Paragraphs": [ "…" ] }
}

Notes

• First call for a new lat/lng is ~1s. Subsequent calls hit the server cache (7-day TTL) and return in tens of milliseconds.
• Coordinates outside the country’s borders return 400 with the message Geolocation outside <COUNTRY>. Use the right country subdomain.
• Need narrative text? See Narrative text variants for GET /summary/text and GET /summary/text-and-data.
• See related: Points, Categories, Recipe: replicate the Summary plugin.