> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baato.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Directions API

> Navigation routes between points, with distance and time estimates.

<Note>
  For easy integration with web and Android projects, this service is also available through
  our [JavaScript](/libraries/javascript) and [Java](/libraries/java) libraries.
</Note>

The `encodedPolyline` field contains geographic data which is decoded into web-friendly
GeoJSON format using our [JavaScript](/libraries/javascript) library.


## OpenAPI

````yaml services/openapi.yaml GET /directions
openapi: 3.1.0
info:
  title: Baato API
  version: 1.0.0
  description: >
    Cloud-based geospatial services for Nepal: keyword search, reverse
    geocoding, place

    lookup, nearby search, routing, and vector map styles.


    Every endpoint requires a Baato access token, passed as the `key` query
    parameter.

    See [Authentication](/about/authentication).


    Error responses follow the same envelope as successful ones. See

    [Errors and status codes](/services/errors).


    TODO: the 4xx/5xx responses below are inferred from Baato's documented
    authentication

    and quota rules, not observed against the live API. Confirm the exact codes
    and

    messages with the API team before treating them as contractual.
  contact:
    name: Baato support
    email: support@baato.io
    url: https://baato.io
servers:
  - url: https://api.baato.io/api/v1
    description: Production
security:
  - baatoAccessToken: []
tags:
  - name: Search
    description: Find places by keyword or proximity.
  - name: Geocoding
    description: Convert between coordinates and place information.
  - name: Routing
    description: Navigation routes between points.
  - name: Maps
    description: Vector map styles.
paths:
  /directions:
    get:
      tags:
        - Routing
      summary: Get a navigation route
      description: >
        Returns navigation routes between two or more points, along with
        distance and time

        estimates.


        The `encodedPolyline` field contains geographic data which can be
        decoded into

        web-friendly GeoJSON using our [JavaScript
        library](/libraries/javascript).
      operationId: directions
      parameters:
        - name: points[]
          in: query
          required: true
          description: >
            Start and end destinations in `lat,lon` form. Repeat the parameter
            for each

            point; at least two are required. Intermediate points are supported.
          style: form
          explode: true
          schema:
            type: array
            minItems: 2
            items:
              type: string
          example:
            - 27.717728723291803,85.32784938812257
            - 27.73449858986537,85.33714056015016
        - name: mode
          in: query
          required: true
          description: Mode of travel.
          schema:
            type: string
            enum:
              - car
              - bike
              - foot
          example: car
        - name: alternatives
          in: query
          description: Return alternative routes in addition to the best one.
          schema:
            type: boolean
            default: false
        - name: instructions
          in: query
          description: Include a turn-by-turn instruction list with each route.
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: One or more routes between the given points.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Envelope'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Route'
              example:
                timestamp: Tue Mar 24 13:50:44 NPT 2020
                status: 200
                message: Success
                data:
                  - encodedPolyline: >-
                      wrdhDerxgOe@AsBYcGgAs@@KBa@Nq@^SPODe@AqDLsBEgE@MGQQ}AcBKMCU?eCRuBVqEa@I{@Bi@XqAaAMAmAMs@u@KcAFy@_AU_CeBGi@u@e@b@cCaAWJ}@wAq@GO_@HGOs@c@oAWU[y@Uu@e@QWSk@MMo@MaAKe@S_Bq@cAi@iAMw@`@yAf@s@d@SHQAyAi@eAUoAa@u@Qe@M]Uc@a@IOCM
                    distanceInMeters: 2542.2360808268404
                    timeInMs: 546077
                    instructionList: null
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  schemas:
    Envelope:
      type: object
      properties:
        timestamp:
          type: string
          description: Server time when the response was generated.
          example: Thu May 14 07:35:16 NPT 2020
        status:
          type: integer
          description: HTTP-style status code echoed in the response body.
          example: 200
        message:
          type: string
          example: Success
    Route:
      type: object
      properties:
        encodedPolyline:
          type: string
          description: >
            The route geometry, encoded as a polyline. Decode it with

            `Baato.Util().getGeoJsonFromEncodedPolyline()` in the JavaScript
            library.
        distanceInMeters:
          type: number
          format: double
          example: 2542.2360808268404
        timeInMs:
          type: integer
          format: int64
          description: Estimated travel time in milliseconds.
          example: 546077
        instructionList:
          type:
            - array
            - 'null'
          description: >
            Turn-by-turn instructions. `null` unless `instructions=true` was
            requested.
          items:
            type: object
            additionalProperties: true
    Error:
      type: object
      description: >
        The standard envelope, returned with an explanatory `message` and an
        empty `data`

        array when a request fails.
      properties:
        timestamp:
          type: string
          example: Thu May 14 07:35:16 NPT 2020
        status:
          type: integer
          description: The HTTP status, echoed into the body.
          example: 401
        message:
          type: string
          description: A human-readable explanation of the failure.
          example: Invalid access token
        data:
          type: array
          description: Always empty on an error response.
          items: {}
  responses:
    BadRequest:
      description: A required parameter is missing or malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            timestamp: Thu May 14 07:35:16 NPT 2020
            status: 400
            message: Missing required parameter
            data: []
    Unauthorized:
      description: >
        The `key` parameter is missing or malformed, or the token has been
        deleted.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            timestamp: Thu May 14 07:35:16 NPT 2020
            status: 401
            message: Invalid access token
            data: []
    Forbidden:
      description: >
        The token is valid, but the request origin is not in its allowed origins
        list.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            timestamp: Thu May 14 07:35:16 NPT 2020
            status: 403
            message: Origin not allowed for this token
            data: []
    RateLimited:
      description: >
        The token's request quota is exhausted. Retry with exponential backoff —
        see

        [Errors and status codes](/services/errors#rate-limiting).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            timestamp: Thu May 14 07:35:16 NPT 2020
            status: 429
            message: Rate limit exceeded
            data: []
    ServerError:
      description: A fault on Baato's side. Safe to retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            timestamp: Thu May 14 07:35:16 NPT 2020
            status: 500
            message: Internal server error
            data: []
  securitySchemes:
    baatoAccessToken:
      type: apiKey
      in: query
      name: key
      description: |
        Your Baato access token. See [Authentication](/about/authentication).

````