[Kotlin][Android] 안드로이드 카카오맵 API 사용하기 - POI정보 활용하여 맵에 PIN 생성하기

안녕하세요 👋

오늘은 저번 포스트에 이어서 

카카오 맵 API를 활용하여 지도에 PIN을 찍는 법을 포스팅해보려 합니다!

 

카카오 맵 API의 기본 설정 및 API를 활용하여 지도를 띄우는 방법은

이전 포스팅을 참고해주세요 😎

[Kotlin][Android] 안드로이드 카카오맵 API 사용하기 - 카카오맵 화면에 띄우기

 

카카오 맵 API에서는 키워드에 따른 위치 정보를 전달해주는 API가 존재합니다.

 

자세한 문서는 

https://apis.map.kakao.com/android/guide/#urlscheme_search

위 링크를 통해 확인이 가능합니다.

오늘 포스팅에서 사용할 API는 아래와 같습니다.

카카오맵 검색하기 URL

또한 현재 포스팅에서 사용할 지도는 카카오 맵(다음 지도)으로 해당 지도는 내부적으로 WCONGNAMUL형식으로

좌표를 표시한다고 합니다. 위 API를 통해 좌표를 전달받을 시 WGS84 형식의 좌표값을 전달받으므로

위 좌표값을 변환해줄 API도 함께 사용하려 합니다.

자세한 문서는 아래 링크를 통해 확인 가능합니다 🤩

Kakao Developers

---

그럼 이제 본격적으로 코드를 어떻게 짜야하는지 보도록 하겠습니다!

1. REST API와 호출하기 위한 모델 생성하기

 

위치 검색 결과 JSON 및 그에 따른 Model class

{
    "documents": [
        {
            "address_name": "서울 중구 태평로1가 31",
            "category_group_code": "PO3",
            "category_group_name": "공공기관",
            "category_name": "사회,공공기관 > 지방행정기관 > 시청 > 특별시청",
            "distance": "",
            "id": "8430129",
            "phone": "02-120",
            "place_name": "서울특별시청",
            "place_url": "http://place.map.kakao.com/8430129",
            "road_address_name": "서울 중구 세종대로 110",
            "x": "126.978652258823",
            "y": "37.56682420267543"
        }, ... // 생략
    ],
    "meta": {
        "is_end": false,
        "pageable_count": 45,
        "same_name": {
            "keyword": "서울시청",
            "region": [],
            "selected_region": ""
        },
        "total_count": 342
    }
}

data class KakaoPoiModel(
    val documents : MutableList<Documents> ,
    val meta : Meta
)

data class Documents(
    @SerializedName("address_name")
    val addressName : String ,
    @SerializedName("category_group_code")
    val categoryGroupCode : String ,
    @SerializedName("category_group_name")
    val categoryGroupName : String ,
    @SerializedName("category_name")
    val categoryName : String ,
    val distance : String ,
    val id : String ,
    val phone : String ,
    @SerializedName("place_name")
    val placeName : String ,
    @SerializedName("place_url")
    val placeURL : String ,
    @SerializedName("road_address_name")
    val roadAddressName : String ,
    @SerializedName("x")
    var longitude : String? ,
    @SerializedName("y")
    var latitude : String?
)

data class Meta(
    @SerializedName("is_end")
    val isEnd : Boolean ,
    @SerializedName("pageable_count")
    val pageableCount : Int ,
    @SerializedName("same_name")
    val sameName : SameName ,
    @SerializedName("total_count")
    val totalCount : Int
)

 

좌표계 변환 결과 JSON 및 그에 따른 Model Class

{
    "meta": {
        "total_count": 1
    },
    "documents": [
        {
            "x": 922606.0,
            "y": 1197404.0
        }
    ]
}

data class WcongModel(
    val meta : WcongMeta ,
    val documents : MutableList<WcongDocuments>
)

data class WcongMeta(
    @SerializedName("total_count")
    val totalCount : String
)

data class WcongDocuments(
    @SerializedName("x")
    val longitude: String ,
    @SerializedName("y")
    val latitude: String
)

 

REST Interface

import com.lee.beachcongetion.common.*
import com.lee.beachcongetion.data.retrofit.model.kakao.KakaoPoiModel
import com.lee.beachcongetion.data.retrofit.model.kakao.WcongModel
import retrofit2.Response
import retrofit2.Retrofit
import retrofit2.converter.gson.GsonConverterFactory
import retrofit2.http.GET
import retrofit2.http.Header
import retrofit2.http.Query

private const val KAKAO_BASE_URL = "https://dapi.kakao.com/"
private const val KAKAO_POI_URL = "v2/local/search/keyword.json"
private const val KAKAO_CONVERT_WCONG = "v2/local/geo/transcoord.json?&output_coord=WCONGNAMUL"
private const val AUTHORIZATION = "Authorization"

interface KakaoPoiService {
    @GET(KAKAO_POI_URL) // 검색 정보를 받아오는 Rest 함수
    suspend fun getPOIList(
        @Header(AUTHORIZATION) key : String ,
        @Query("query") keyword : String ,
    ) : Response<KakaoPoiModel>

    @GET(KAKAO_CONVERT_WCONG) // 좌표계를 변경하는 Rest 함수
    suspend fun getWcongPoint(
        @Header(AUTHORIZATION) key : String ,
        @Query("x") longitude : String ,
        @Query("y") latitude : String
    ) : Response<WcongModel>
}

class KakaoPoiInstance {
    companion object{
        private lateinit var instance : KakaoPoiService
        fun getInstance() : KakaoPoiService {
            if(!::instance.isInitialized){
                val retrofit = Retrofit.Builder()
                    .baseUrl(KAKAO_BASE_URL)
                    .addConverterFactory(GsonConverterFactory.create())
                    .build()
                instance = retrofit.create(KakaoPoiService::class.java)
            }
            return instance
        }
    }
}

 

2. Acitivy에서 사용하기

package com.lee.beachcongetion.ui

import android.os.Bundle
import android.view.View
import android.widget.Toast
import androidx.appcompat.app.AppCompatActivity
import com.lee.beachcongetion.R
import com.lee.beachcongetion.data.retrofit.KakaoPoiInstance
import com.lee.beachcongetion.databinding.ActivityTestBinding
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch
import net.daum.mf.map.api.MapPOIItem
import net.daum.mf.map.api.MapPoint
import net.daum.mf.map.api.MapView

class TestActivity : AppCompatActivity(){
    private lateinit var binding : ActivityTestBinding
    private lateinit var mMap : MapView

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        binding = ActivityTestBinding.inflate(layoutInflater).also {
            setContentView(it.root)
        }
        mMap = MapView(this@TestActivity)
        binding.mapView.addView(mMap)// Map 표시

        addListeners()
    }
    
    /**
    	리스너 등록 함수
    **/

    private fun addListeners() {
        with(binding){
            searchButton.setOnClickListener {
                mMap.removeAllPOIItems() // 이전에 POI Item이 존재한다면 모두 지운다.
               if(searchEditText.text.isNotEmpty()){ // 검색창이 비어있지 않다면 함수 실행
                   CoroutineScope(Dispatchers.IO).launch { // 함수가 suspend이기 때문에 coroutine을 통해 처리
                       val response = KakaoPoiInstance.getInstance().getPOIList(getString(R.string.kakao_api_key) , searchEditText.text.toString())
                       if(response.isSuccessful){ // 키워드를 통한 POI정보 검색 성공시
                           val poiList = response.body()?.documents
                           if(poiList!!.isEmpty()){ // 성공했으나 해당하는 위치정보가 하나도 없을때에 대한 예외 처리
                               CoroutineScope(Dispatchers.Main).launch {
                                   Toast.makeText(this@TestActivity , "해당하는 위치가 존재하지 않습니다!" , Toast.LENGTH_SHORT).show()
                               }
                           } else { // 리스트 받기 성공 
                               val mapPoiItems = ArrayList<MapPOIItem>() // Marker를 저장하기 위한 ArrayList
                               poiList.forEach { // 키워드에 관련된 정보를 리스트에 전달받아 모두 마커로 표시하기 위한 부분
                                   val marker = MapPOIItem()
                                   val wcongResponse = KakaoPoiInstance.getInstance().getWcongPoint(getString(R.string.kakao_api_key) ,it.longitude!! , it.latitude!!)
                                   if(wcongResponse.isSuccessful){ // WCONG좌표계로 변환 성공시
                                       val wcongModel = wcongResponse.body()?.documents
                                       /** 
                                       	 전달받은 좌표계는 WSG84좌표계로 변환된 좌표 값으로 data model의 값을 변경해줌
                                         변환된 좌표계 값은 List형식으로 전달되지만 값은 하나밖에 존재하지 않음
                                       **/
                                       it.longitude = wcongModel?.get(0)?.longitude
                                       it.latitude = wcongModel?.get(0)?.latitude

                                       with(marker){ // marker (POI Item)을 성정해주는 부분
                                           itemName = it.placeName
                                           tag = 0
                                           mapPoint = MapPoint.mapPointWithWCONGCoord(it.longitude?.toDouble()!! , it.latitude?.toDouble()!!)
                                           markerType = MapPOIItem.MarkerType.BluePin
                                           selectedMarkerType = MapPOIItem.MarkerType.RedPin
                                       }
                                       mapPoiItems.add(marker) // 설정된 marker를 List에 저장
                                   } else { // 좌표 변경에 실패했을때에 대한 예외처리
                                       Toast.makeText(this@TestActivity , "정상적으로 좌표를 변경하지 못했습니다!" , Toast.LENGTH_SHORT).show()
                                       return@launch
                                   }
                               }
                               CoroutineScope(Dispatchers.Main).launch { 
                               // 모든 과정이 성공시 coroutine을 통해 map에 배열에 추가된 marker를 추가해준다.
                                   mapPoiItems.forEach {
                                       mMap.addPOIItem(it)
                                   }
                                   mMap.setZoomLevel(17 , true) // marker추가 후 지도 Zoom
                               }
                           }
                       } else { // 키워드 검색에 따른 위치정보를 정상적으로 불러오지 못했을때
                           Toast.makeText(this@TestActivity , "서버에서 정상적으로 정보를 가져오지 못했습니다!" , Toast.LENGTH_SHORT).show()
                       }
                   }

               }
            }
        }
    }
}

코드는 위와 같으며 동작은 키워드 검색 시에 해당하는 모든 pin을 지도에 표시하는 샘플 코드입니다.

키워드 검색으로 받아오는 정보는 해당 키워드의 정확도에 따라 배열로 전달받습니다.

(즉 , 가장 첫 번째 배열 값이 가장 가깝고 정확한 정보)

위 샘플 코드에서 사용한 map관련 함수 외에 추가적인 함수는

카카오 맵 api 공식문서에 자세하게 설명되어 있으니 확인 부탁드립니다. 🤔

 

마지막으로 실행화면과 함께 오늘의 포스팅을 마치겠습니다.

 

오늘도 즐코하세요 :)