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

> Call the Baato Search API from Kotlin.

<Steps>
  <Step title="Declare the Retrofit interface">
    ```kotlin theme={null}
     interface BaatoAPI {
        @GET("places/")
        suspend fun getPlaceDetailsResponse(@QueryMap parameters: Map<String, String>): Response<PlaceAPIResponse>;
    }
    ```

    * This defines an interface for making API calls using Retrofit.
    * @GET("places/") specifies that this method sends a GET request to the "places/" endpoint.
    * `@QueryMap parameters: Map<String, String>` allows passing multiple query parameters dynamically.
    * The response is wrapped in `Response<PlaceAPIResponse>`, meaning it will be an HTTP response containing `PlaceAPIResponse`.
  </Step>

  <Step title="Create the Retrofit instance">
    ```kotlin theme={null}
    object ApiCall {
      private val retrofit: Retrofit = Retrofit.Builder()
          .baseUrl("https://api.baato.io/api/v1/") // Base URL of your API
          .addConverterFactory(GsonConverterFactory.create())
          .build()

    private val baatoAPI: BaatoAPI = retrofit.create(BaatoAPI::class.java)
    suspend fun getPlaceDetails(params: Map<String, String>): PlaceAPIResponse {
       return baatoAPI.getPlaceDetailsResponse(params).body() ?: throw Exception("Null response")
    }
    }
    ```

    * Retrofit.Builder() initializes the Retrofit instance.
    * .baseUrl("[https://api.baato.io/api/v1/](https://api.baato.io/api/v1/)") sets the base URL for API calls.
    * .addConverterFactory(GsonConverterFactory.create()) allows automatic JSON parsing.
    * retrofit.create(BaatoAPI::class.java) generates an implementation of the BaatoAPI interface.
    * `suspend fun getPlaceDetails(params: Map<String, String>)` is a suspending function that calls the API.
      * It fetches a response and extracts the body (PlaceAPIResponse).
      * If the response is null, an exception is thrown.
  </Step>

  <Step title="Model the response envelope">
    ```kotlin theme={null}
    data class PlaceAPIResponse(
       val timestamp: String,
       val status: Int,
       val message: String,
       val data: List<Place>
    );
    ```

    * This defines the response structure:
    * timestamp: When the API responded.
    * status: HTTP status code.
    * message: API message.
    * data: A list of Place objects.
  </Step>

  <Step title="Model a place">
    ```kotlin theme={null}
    data class Place(
       val license: String?,
       val score: Any?, // Replace `Any` with a concrete type like Double
       var address: String,
       var centroid: LatLon,
       val placeId: Int,
       val osmId: Long,
       var name: String,
       val geometry: Geometry?,
       var type: String?,
       var tags: List<String>?
    ) : Parcelable
    ```

    * Represents a location retrieved from the API.
    * Key properties:
      * score: Ideally should be Double instead of Any.
      * centroid: Represents the center of the place (LatLon).
      * geometry: Represents spatial data (Geometry).
  </Step>

  <Step title="Make Place parcelable">
    ```kotlin theme={null}
    override fun writeToParcel(parcel: Parcel, flags: Int) {
        parcel.writeString(license)
        parcel.writeValue(score)
        parcel.writeString(address)
        parcel.writeParcelable(centroid, flags)
        parcel.writeInt(placeId)
        parcel.writeLong(osmId)
        parcel.writeString(name)
        parcel.writeParcelable(geometry, flags)
        parcel.writeString(type)
        parcel.writeStringList(tags)
    }
    ```

    * Implements Parcelable to pass Place objects between activities/fragments.
    * Uses Parcel to serialize and deserialize the data.
  </Step>

  <Step title="Model the geometry">
    ```kotlin theme={null}
    data class Geometry(
       val type: String,
       val coordinates: Any?
    ) : Parcelable
    ```

    * Represents the spatial structure of a place.
    * type: Type of geometry (e.g., Point, Polygon).
    * `coordinates`: Should ideally be a `List<Double>` instead of `Any`.
  </Step>

  <Step title="Model the coordinate pair">
    ```kotlin theme={null}
    data class LatLon(
       val lat: Double,
       val lon: Double
    ) : Parcelable
    ```

    * Represents latitude and longitude of a place.
  </Step>

  <Step title="Make the call">
    ```kotlin theme={null}
    private val apiService = ApiCall
    val queryMaps: MutableMap<String, String> = HashMap()
    queryMaps["key"] = Constants.token
    queryMaps["placeId"] = placeId

    val placeDetails = apiService.getPlaceDetails(queryMaps)
    ```

    * queryMaps holds the API query parameters (key and placeId).
    * apiService.getPlaceDetails(queryMaps) fetches the place details.
  </Step>
</Steps>