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

# Places API

> Full geographic detail — centroid, geometry and tags — for a known place ID.

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

Designed to be used in conjunction with the [Search API](/services/search) — the `placeId`
this endpoint requires is part of every search result.


## OpenAPI

````yaml services/openapi.yaml GET /places
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:
  /places:
    get:
      tags:
        - Geocoding
      summary: Get detailed information for a place
      description: >
        Returns detailed geographic information — centroid and geometry — for a
        known place.


        Designed to be used together with the [Search API](/services/search):
        the `placeId`

        required here is part of every search result.
      operationId: places
      parameters:
        - name: placeId
          in: query
          required: true
          description: |
            The ID for the place of interest, as returned by the
            [Search API](/services/search).
          schema:
            type: integer
          example: 102235
        - name: adminInfo
          in: query
          description: >
            Include admin level info (province, district, municipality) in the
            response.
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Detailed information for the requested place.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Envelope'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Place'
              example:
                timestamp: Thu May 14 07:36:15 NPT 2020
                status: 200
                message: Success
                data:
                  - placeId: 102235
                    license: 'N'
                    name: Shemrock School
                    address: >-
                      Kamal Pokhari, Kathmandu Metropolitan City, Kathmandu,
                      Nepal
                    type: amenity
                    centroid:
                      lat: 27.7108304
                      lon: 85.3265325
                    tags:
                      - opening_hours|08:00-16:00
                      - amenity|school
                    geometry:
                      type: Point
                      coordinates:
                        - 85.3265325
                        - 27.7108304
                    score: 1
        '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
    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'
    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
    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).

````