πWeb API Service
If you need to support more platforms other than Android/iOS, you can use a web based API service. Out of the box Compass supports Google Maps and .
Custom API
If you aren't using the provided services, you can create your own by implementing your own HttpApiPlatformGeocoder
.
Import the library
First you need to import the geocoding-web
artifact:
implementation(libs.compass.geocoding.web)
Create your endpoints
Now you need to implement a ForwardEndpoint
and ReverseEndpoint
which are defined as:
public typealias ForwardEndpoint = HttpApiEndpoint<String, List<Coordinates>>
public typealias ReverseEndpoint = HttpApiEndpoint<Coordinates, List<Place>>
Here is an example ForwardEndpoint
:
public class MyForwardEndpoint : ForwardEndpoint {
override fun url(param: String): String {
return "https://my-api.com/api/geocode?query=$param"
}
override suspend fun mapResponse(response: HttpResponse): List<Coordinates> {
val result = response.body<MyAPIResponse>().resultsOrThrow()
// Map the response to the Coordinates object
return result.toCoordinates()
}
}
Here you can use any API you want by creating the URL and mapping the response.
You can also use the helper extension function for more concise code:
val forwardEndpoint = ForwardEndpoint(
url = { param -> "https://my-api.com/api/geocode?query=$param" },
mapResponse = { response ->
response.body<MyAPIResponse>().resultsOrThrow().toCoordinates()
},
)
Now you can do the same for the ReverseEndpoint
as well.
Create the Geocoder
In order to create the Geocoder
object you need a PlatformGeocoder
that can make the requests. In this case we need to create a HttpApiPlatformGeocoder
this can be done like so:
val platformGeocoder = HttpApiPlatformGeocoder(
forwardEndpoint = forwardEndpoint, // created above
reverseEndpoint = reverseEndpoint,
)
Then you can finally create the Geocoder
:
val geocoder = Geocoder(platformGeocoder)
geocoder.forward("London UK")
You can skip the HttpApiPlatformGeocoder
step by using another extension function:
val geocoder = Geocoder(
forwardEndpoint = forwardEndpoint, // created above
reverseEndpoint = reverseEndpoint,
)
geocoder.forward("London UK")
Customizing the HTTP request
If you need to customize the HTTP request to your API then you can do so by passing a HttpClient
or Json
object to the above functions.
Here is the signature for the above Geocoder
function:
public fun Geocoder(
forwardEndpoint: ForwardEndpoint,
reverseEndpoint: ReverseEndpoint,
json: Json = HttpApiEndpoint.json(),
httpClient: HttpClient = HttpApiEndpoint.httpClient(json),
dispatcher: CoroutineDispatcher = Dispatchers.Default,
): Geocoder
Notice that a default HttpClient
is used, but you can pass your own in.
Last updated
Was this helpful?