# Compass

[![Maven Central Version](https://img.shields.io/maven-central/v/dev.jordond.compass/compass-core)](https://central.sonatype.com/namespace/dev.jordond.compass)

## Overview

Compass is a Kotlin Multiplatform library location toolkit. It provides a set of tools for working with location data, including geocoding, reverse geocoding, and more. The library is built with a focus on simplicity and ease of use, providing a straightforward API for geocoding operations.

### Features

* [geocoding](https://compass.jordond.dev/geocoding "mention")
  * Native support for Android and iOS
  * Support for other platforms by using web based APIs
    * Included support for [Google Maps ](https://developers.google.com/maps/documentation/geocoding)and [Mapbox](https://docs.mapbox.com/#search)
    * See [web-api-service](https://compass.jordond.dev/geocoding/web-api-service "mention")
* [geolocation](https://compass.jordond.dev/geolocation "mention")
  * Mobile support (Android/iOS)
  * Browser [Geolocation API](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API)
  * Built-in permission handling
* [autocomplete](https://compass.jordond.dev/autocomplete "mention")
  * Mobile support (Android/iOS) via Geocoder
  * Support for other platforms by using web based APIs
    * Included support for [Google Maps ](https://developers.google.com/maps/documentation/geocoding)and [Mapbox](https://docs.mapbox.com/#search) via the Decoder API
    * Google Places API support is planned

### Easy to use

Compass has a simple API:

```kotlin
suspend fun lookupCoordinates(latitude: Double, longitude: Double): Place? {
    val geocoder = Geocoder()
    val result: GeocoderResult<Place> = geocoder.reverse(latitude, longitude)
    return result.getOrNull()
}
```

The above `Geocoder()` function is one of many extension functions included to make your life easier. Behind the scenes a `PlatformGeocoder` is used to do all the heavy lifting, and can be created and provided on a per-platform basis.

You can learn more about geocoding here: [overview](https://compass.jordond.dev/geocoding/overview "mention")

{% hint style="info" %}
The above `Geocoder()`extension function is from the Android/iOS only artifact. If you plan on supporting other platforms, check out [mixed-platforms](https://compass.jordond.dev/setup/mixed-platforms "mention").
{% endhint %}

### Get Started

Here is a few good starting points to start using Compass!

{% content-ref url="setup" %}
[setup](https://compass.jordond.dev/setup)
{% endcontent-ref %}

{% content-ref url="supported-platforms" %}
[supported-platforms](https://compass.jordond.dev/supported-platforms)
{% endcontent-ref %}

{% content-ref url="setup/add-dependencies" %}
[add-dependencies](https://compass.jordond.dev/setup/add-dependencies)
{% endcontent-ref %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://compass.jordond.dev/readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.