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

# Nearby Places API

> Find places of a given type around a coordinate.

## Supported place types

The `type` field supports almost all feature types available in
[OpenStreetMap](https://wiki.openstreetmap.org/wiki/Map_features). A few feature types have
been merged to give better results — sending `type=eat`, for example, returns combined results
for cafes, restaurants and bakeries. If you want just one of them, send that type directly
(`type=cafe`).

| Merged type     | Returns results for                                                                         |
| --------------- | ------------------------------------------------------------------------------------------- |
| `eat`           | `cafe`, `restaurant`, `bakery`                                                              |
| `grocery`       | `department_store`, `supermarket`                                                           |
| `tourism`       | `attraction`, `artwork`, `museum`, `park`                                                   |
| `transport`     | `bus_stop`, `bus_station`                                                                   |
| `parking`       | `parking`, `bicycle_parking`, `underground`, `multi-storey`, `parking_space`, `car_parking` |
| `shopping`      | `jewelry`, `sports`, `gift`, `mall`, `department_store`, `hardware`, `kitchen`, `furniture` |
| `children`      | `swimming_pool`, `playground`, `recreation_ground`, `park`, `water_park`, `disneyland`      |
| `night_life`    | `pub`, `bar`, `nightclub`                                                                   |
| `entertainment` | `cinema`, `theatre`, `casino`, `nightclub`                                                  |
| `clinic`        | `clinic`, `dentist`, `veterinary`, `herbalist`, `ayurvedic`                                 |
| `workshop`      | `metal`, `bicycle`, `aluminium`, `car_repair`, `tyres`, `car_parts`                         |

<Note>
  Apart from these, you can fetch other OSM feature types such as `toilets` or `post_office`.
  Further information on supported types is available in the
  [OpenStreetMap map features documentation](https://wiki.openstreetmap.org/wiki/Map_features).
</Note>


## OpenAPI

````yaml services/openapi.yaml GET /search/nearby
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/nearby:
    get:
      tags:
        - Search
      summary: Find nearby places of a given type
      description: >
        Returns places of a particular type around a coordinate. Designed for UI
        elements

        such as category lists (schools, hospitals, and so on).


        The `type` field supports almost all feature types available in

        [OpenStreetMap](https://wiki.openstreetmap.org/wiki/Map_features). A few
        types are

        merged to give better results — see [Nearby
        Places](/services/nearby-places) for the

        full list of merged types.
      operationId: nearbyPlaces
      parameters:
        - name: type
          in: query
          required: true
          description: >
            The type or category of results the request should return, for
            example

            `hospital`, `cafe`, or a merged type such as `eat`.
          schema:
            type: string
          example: school
        - name: lat
          in: query
          required: true
          description: Latitude around which to retrieve place information.
          schema:
            type: number
            format: double
          example: 27.71765
        - name: lon
          in: query
          required: true
          description: Longitude around which to retrieve place information.
          schema:
            type: number
            format: double
          example: 85.32691
        - 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: 20
        - name: sortBy
          in: query
          description: >
            Sort results in ascending order by their distance from the specified
            location, so

            the nearest result is first.
          schema:
            type: boolean
        - name: isOpen
          in: query
          description: >
            Return only places that are open for business at the time of the
            query. Places

            that do not specify opening hours in the Baato database are excluded
            when this

            parameter is set.
          schema:
            type: boolean
      responses:
        '200':
          description: Nearby places of the requested type.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Envelope'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/NearbyPlace'
              example:
                timestamp: Thu May 14 07:35:16 NPT 2020
                status: 200
                message: Success
                data:
                  - placeId: 274918
                    osmId: 4027146021
                    name: Parkland Hospital
                    address: Amar Singh Chowk, Pokhara Metropolitan, Kaski, Nepal
                    type: hospital
                    centroid:
                      lat: 28.204451249999998
                      lon: 84.00134361230909
                    tags:
                      - phone|061-431830/ 431930
                      - opening_hours|24/7
                      - email|parklandhospital@gmail.com
                      - amenity|hospital
                    geometry:
                      type: Polygon
                      coordinates:
                        - - - 84.0012308
                            - 28.2046362
                          - - 84.0012952
                            - 28.2042237
                          - - 84.0014963
                            - 28.2042421
                          - - 84.0012308
                            - 28.2046362
                    score: 0.4886951
                    radialDistanceInKm: 140.99
                    open: true
        '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
    NearbyPlace:
      allOf:
        - $ref: '#/components/schemas/Place'
        - type: object
          properties:
            osmId:
              type: integer
              format: int64
              description: The underlying OpenStreetMap object ID.
              example: 4027146021
            radialDistanceInKm:
              type: number
              format: double
              description: Straight-line distance from the queried coordinate.
              example: 140.99
            open:
              type: boolean
              description: >
                Whether the place is currently open, derived from its
                `opening_hours` tag.
    Place:
      type: object
      description: A place with full geographic detail.
      properties:
        placeId:
          type: integer
          example: 102235
        license:
          type: string
          description: Attribution string for the underlying data.
        name:
          type: string
          example: Shemrock School
        address:
          type: string
        type:
          type: string
          example: amenity
        centroid:
          $ref: '#/components/schemas/Centroid'
        tags:
          type: array
          description: OpenStreetMap tags as `key|value` strings.
          items:
            type: string
          example:
            - opening_hours|08:00-16:00
            - amenity|school
        geometry:
          $ref: '#/components/schemas/Geometry'
        score:
          $ref: '#/components/schemas/Score'
    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: {}
    Centroid:
      type: object
      description: The centre point of a place.
      properties:
        lat:
          type: number
          format: double
        lon:
          type: number
          format: double
    Geometry:
      type: object
      description: >
        GeoJSON-style geometry. Point results carry a `[lon, lat]` pair; area
        results carry

        nested coordinate rings.
      properties:
        type:
          type: string
          examples:
            - Point
            - Polygon
            - MultiPolygon
            - LineString
        coordinates:
          description: Coordinates, nested according to `type`.
      required:
        - type
        - coordinates
    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
  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).

````