Core concepts

Baato’s endpoints are small and consistent, but a few conventions trip people up on the first integration. This page covers all of them.

The response envelope

Every endpoint except Map Styles returns the same wrapper. The payload you want is always under data.

{
  "timestamp": "Thu May 14 07:35:16 NPT 2020",
  "status": 200,
  "message": "Success",
  "data": []
}

string

Server time when the response was generated, in Nepal Time.

integer

The HTTP status, echoed into the body. It matches the real HTTP status code — check the transport-level status, not this field, when handling errors.

string

Success on a 2xx, or a human-readable explanation otherwise.

array

The results. Always an array, even for endpoints that return a single logical result — Places and Reverse Search both return a one-element array, so read data[0].

Map Styles is the exception: it returns a raw Mapbox Style Specification document with no envelope, because map renderers consume it directly.

Coordinate order

Baato takes latitude and longitude as separate lat and lon parameters, and Directions takes points as "lat,lon" strings. GeoJSON, MapLibre GL and Mapbox GL all take [lon, lat] arrays. Reversing them silently places your map in the wrong hemisphere rather than throwing an error.

Kathmandu is at latitude 27.7172, longitude 85.3240. The same point, three ways:

// Baato request parameters — named, order does not matter
{ lat: 27.7172, lon: 85.3240 }

// Baato Directions points[] — "lat,lon"
"27.7172,85.3240"

// MapLibre / Mapbox / GeoJSON — [lon, lat]
[85.3240, 27.7172]

Baato responses use named fields (centroid.lat, centroid.lon), so the risk is in the handoff to your map library:

const place = response.data[0];

// Correct — swap into [lon, lat] for the renderer
new maplibregl.Marker()
  .setLngLat([place.centroid.lon, place.centroid.lat])
  .addTo(map);

The one place Baato does emit renderer-order coordinates is the geometry field on a Place, which is GeoJSON and therefore already [lon, lat].

Identifying a place

Hide placeId, osmId and how they differ

integer

Baato’s own identifier. Returned by Search, Places, Reverse Search and Nearby Places. This is the ID you pass back to the Places API.

integer

The underlying OpenStreetMap object ID, returned only by Nearby Places. Useful for cross-referencing against OSM, not for querying Baato.

The two-step search flow exists because search responses are optimised for autocomplete UIs — they omit geometry to stay small and fast:

Search returns lightweight suggestions

GET /search?q=patan → name, address, type, placeId. No coordinates.

Places resolves one suggestion in full

GET /places?placeId=344470 → centroid, geometry and OpenStreetMap tags.

Call step two only when the user picks a result, not for every keystroke.

Encoded polylines

Directions returns route geometry as encodedPolyline — a compact string in Google’s encoded polyline format, rather than a large GeoJSON LineString. Decode it before handing it to a renderer.

// Baato.Routing() decodes for you — each result carries a ready-made .geojson
new Baato.Routing({ key: "YOUR_BAATO_ACCESS_TOKEN" })
  .addPoints(["27.6950,85.3078", "27.7067,85.3337"])
  .setVehicle("foot")
  .getBest()
  .doRequest()
  .then((routes) => {
    map.getSource("route").setData({
      type: "Feature",
      geometry: { type: "LineString", coordinates: routes[0].geojson.coordinates },
    });
  });

import polyline from "@mapbox/polyline";

const geojson = polyline.toGeoJSON(route.encodedPolyline);

// The Flutter client decodes for you
final route = await Baato.api.direction.getRoutes(
  startCoordinate: start,
  endCoordinate: end,
  mode: BaatoDirectionMode.car,
  decodePolyline: true,
);

Alongside the geometry, every route carries distanceInMeters, timeInMs (milliseconds, not seconds) and — when you request instructions=true — an instructionList. Without that parameter, instructionList is null rather than an empty array.

Place types

The type field is drawn from OpenStreetMap map features. Baato also defines a few merged types that combine related features, so type=eat returns cafes, restaurants and bakeries together. The full list is on the Nearby Places page.

Relevance scores

Search and Places results carry a score. Higher is more relevant, but the scale is not normalised — compare scores within a single response, never across responses.

Endpoints that do not compute a score return the string "NaN" rather than a number or null. Guard against it before doing arithmetic:

const score = typeof result.score === "number" ? result.score : 0;

Versioning

All endpoints live under https://api.baato.io/api/v1. See API versioning for how new versions are introduced.

Get started

Guides by platform

Server SDKs

Resources

The response envelope

Coordinate order

Identifying a place

Encoded polylines

Place types

Relevance scores

Versioning

​The response envelope

​Coordinate order

​Identifying a place

​Encoded polylines

​Place types

​Relevance scores

​Versioning

The response envelope

Coordinate order

Identifying a place

Encoded polylines

Place types

Relevance scores

Versioning