API conventions

Rules shared by most endpoints, with the exceptions named. Skim before writing your client.

Country subdomains

The base URL is https://<country>.yatmo.com, where <country> is the lowercased ISO code of the country whose data you’re querying. Examples:

• https://be.yatmo.com: Belgium
• https://fr.yatmo.com: France
• https://nl.yatmo.com: Netherlands
• https://lu.yatmo.com: Luxembourg
• https://ch.yatmo.com: Switzerland
• https://de.yatmo.com: Germany
• https://at.yatmo.com: Austria
• https://it.yatmo.com: Italy
• https://es.yatmo.com: Spain
• https://pt.yatmo.com: Portugal
• https://ie.yatmo.com: Ireland
• https://uk.yatmo.com: United Kingdom
• https://ca.yatmo.com: Canada
• https://gr.yatmo.com: Greece
• https://ma.yatmo.com: Morocco
• https://au.yatmo.com: Australia
• https://hr.yatmo.com: Croatia
• https://mt.yatmo.com: Malta
• https://si.yatmo.com: Slovenia
• https://rs.yatmo.com: Serbia
• https://cy.yatmo.com: Cyprus
• https://ba.yatmo.com: Bosnia and Herzegovina
• https://me.yatmo.com: Montenegro
• https://bg.yatmo.com: Bulgaria
• https://al.yatmo.com: Albania

Same endpoint paths on every subdomain. The full coverage list is on Countries & languages.

Latitude / longitude order

Most endpoints take a point as two named query parameters, which removes any doubt about the order:

?latitude=50.846714&longitude=4.352514

Three exceptions, each with its own order:

• /points takes two corners, bound1 (south-west) and bound2 (north-east), each as a single latitude,longitude string: bound1=50.8440,4.3482.
• The JavaScript map plugin takes center: [longitude, latitude], the MapLibre and GeoJSON order, while its routeFrom and isochrone objects take named latitude and longitude.
• GeoJSON responses (/isochrone, /route geometries) list positions as [longitude, latitude], as the GeoJSON specification requires.

Language parameter

Endpoints that return user-facing strings (place labels, travel labels, the structured summary) take a language query param: the two-letter ISO 639-1 code, uppercased: EN, FR, NL, DE, IT, ES, PT, CA, ZH, HI, AR, RU, JA, EL, HR, MT, SL, SR, TR, BS, SQ, BG. One exception: Montenegrin has no ISO 639-1 code, so it uses the three-letter ISO 639-2/3 code CNR.

Exception: /summary/text takes no language parameter. It returns every language the country supports in one response, each sentence keyed by its language code; pick the one you publish.

If you pass a language that is not supported in the country you queried, Yatmo falls back to EN. See Countries & languages for the matrix.

URL encoding

Standard query-string rules. The two things people forget:

• Hex color codes: # becomes %23. So pinColor=#af0014 goes on the wire as pinColor=%23af0014.
• Multiple values: when an endpoint accepts a list, join the values with literal commas, for example poiTypesIds=10030001000001,10020003000001 (supermarkets and bus stops in Belgium, from /simplifiedcategories). No bracket syntax.

JSON encoding

Responses are application/json; charset=utf-8. Property names use PascalCase (e.g. AvailableCategoriesAroundPosition) — matching the C# DTO field names directly. Some highly-traversed list endpoints (like /points) return short field names (n, la, ln, p) to keep payloads small — those are documented per-endpoint.

Dates and times are ISO 8601 in UTC.