> ## 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.

# Search API

> Keyword-based place suggestions, optimised for search and autocomplete UIs.

<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 response is deliberately small and leaves out geographic coordinates. To get coordinates
for a result, pass its `placeId` to the [Places API](/services/places).


## OpenAPI

````yaml services/openapi.yaml GET /search
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:
  /search:
    get:
      tags:
        - Search
      summary: Search for places by keyword
      description: >
        Returns suggestions for names of places in response to a keyword query,
        optionally

        biased towards a coordinate.


        The response is optimised to be small and is designed for UI elements
        such as search

        and suggestion boxes — geographic coordinates are deliberately left out.
        To get

        coordinates for a result, pass its `placeId` to the [Places
        API](/services/places).
      operationId: search
      parameters:
        - name: q
          in: query
          required: true
          description: The search keyword to look for results against.
          schema:
            type: string
          example: shemrock nepalgunj
        - name: lat
          in: query
          description: >
            Latitude to bias results towards. Useful in mobile applications for
            providing

            geographical context to the search. Must be sent together with
            `lon`.
          schema:
            type: number
            format: double
          example: 27.7172
        - name: lon
          in: query
          description: Longitude to bias results towards. Must be sent together with `lat`.
          schema:
            type: number
            format: double
          example: 85.324
        - name: type
          in: query
          description: >
            The type or category of results the request should return, for
            example

            `hospital` or `cafe`.
          schema:
            type: string
        - name: radius
          in: query
          description: >
            Radius in kilometres from the specified `lat`/`lon` pair within
            which to look for

            results. Only integer values are supported.
          schema:
            type: integer
            default: 10
        - name: limit
          in: query
          description: The number of results the request should return.
          schema:
            type: integer
            default: 5
          example: 4
      responses:
        '200':
          description: Matching place suggestions.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Envelope'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/SearchResult'
              example:
                timestamp: Thu May 14 07:35:16 NPT 2020
                status: 200
                message: Success
                data:
                  - placeId: 344470
                    name: Shemrock Kids Kingdom
                    address: Kurmi Tol, Nepalgunj Sub-Metropolitan, Banke, Nepal
                    type: kindergarten
                    score: 0.011614336
                  - placeId: 102235
                    name: Shemrock School
                    address: >-
                      Kamal Pokhari, Kathmandu Metropolitan City, Kathmandu,
                      Nepal
                    type: school
                    score: 0.008917106
        '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
    SearchResult:
      type: object
      description: A lightweight search suggestion, without geometry.
      properties:
        placeId:
          type: integer
          description: Pass this to the Places API to retrieve full geographic detail.
          example: 344470
        name:
          type: string
          example: Shemrock Kids Kingdom
        address:
          type: string
          example: Kurmi Tol, Nepalgunj Sub-Metropolitan, Banke, Nepal
        type:
          type: string
          example: kindergarten
        score:
          $ref: '#/components/schemas/Score'
    Score:
      description: >
        Relevance score. Endpoints that do not compute a score may return the
        string `"NaN"`

        rather than a number.
      oneOf:
        - type: number
          format: double
        - type: string
    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).

````