API conventions

Once-and-done rules that apply across every endpoint. 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

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

Latitude / longitude order

Yatmo accepts coordinates as two separate query parameters — not as a single “lng,lat” or “lat,lng” string. Pass them by name:

?latitude=50.8520525&longitude=4.3442926

The named parameters remove the “is it (lat,lng) or (lng,lat)?” ambiguity that GeoJSON / Mapbox / Google APIs all disagree about. Just write them out.

Language parameter

Every endpoint that returns user-facing strings (POI names, neighbourhood descriptions, generated summaries) accepts a language query param — the two-letter ISO 639-1 code, uppercased: EN, FR, NL, DE, IT, ES, PT, CA.

If you pass a language that isn’t 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 comma-separated list (POI type IDs, language fallbacks), just join them with literal commas — poiTypesIds=1,2,3. 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.