This is a pure Kotlin Multiplatform (KMP) port of Google's Open Location Code, also known as Plus Codes.

Open Location Code is a technology that gives a way of encoding location into a format that is easier to use than latitude and longitude.

Attribution: This library is a direct Kotlin port of the original Java implementation maintained by Google. The core logic, constants, and math were derived from the official Google open-location-code repository.

• 100% Pure Kotlin: Built entirely in the commonMain source set. No expect/actual platform wrappers required.
• Idiomatic APIs: Utilizes Kotlin value class to represent the PlusCode string, providing strong type-safety without memory overhead.
• Fully Compliant: Passes all official Google test vectors for validity, encoding, decoding, and short codes with a 5% float tolerance for platform-specific math variance.
• Multiplatform Support: Supports JVM, Android, iOS, macOS, tvOS, watchOS, Linux, MingW, JS, and WasmJS.

You can add this library to your KMP, Android, or JVM project by declaring the dependency in your build.gradle.kts:

dependencies {
    implementation("io.github.aughtone:openlocationcode:0.0.1-alpha1")
}

For native Swift development, this library is distributed as a precompiled XCFramework.

1. Open your Xcode project.
2. Go to File > Add Package Dependencies.
3. Enter the repository URL: https://github.com/aughtone/aughtone-openlocationcode
4. Select the Up to Next Major Version rule. (Note: If you are using a prerelease tag like -alpha1, you must select Exact Version).
5. Add the OpenLocationCode product to your target.

The API is intentionally similar to the original Google library, modernized for Kotlin.

To encode a latitude and longitude into a Plus Code:

import io.github.aughtone.openlocationcode.OpenLocationCode

// Encode with default precision (10 digits)
val code = OpenLocationCode.encode(47.365590, 8.524997)
println(code.value) // Output: 8FVC9G8F+6X

// Encode with specified code length
val preciseCode = OpenLocationCode.encode(47.365590, 8.524997, 11)
println(preciseCode.value) // Output: 8FVC9G8F+6XW

To decode a Plus Code back into a bounding box (CodeArea):

import io.github.aughtone.openlocationcode.OpenLocationCode
import io.github.aughtone.openlocationcode.PlusCode

val plusCode = PlusCode("8FVC9G8F+6X")
val area = OpenLocationCode.decode(plusCode)

println("Center Latitude: ${area.centerLatitude}")
println("Center Longitude: ${area.centerLongitude}")
println("Southwest Corner: ${area.southLatitude}, ${area.westLongitude}")

If you know the user's current location, you can shorten a Plus Code by dropping the region characters:

val fullCode = PlusCode("8FVC9G8F+6X")
val referenceLat = 47.365590
val referenceLng = 8.524997

val shortCode = OpenLocationCode.shorten(fullCode, referenceLat, referenceLng)
println(shortCode.value) // Output: 9G8F+6X

To expand a short code back to a full code using a reference location:

val shortCode = PlusCode("9G8F+6X")
val referenceLat = 47.365590
val referenceLng = 8.524997

val recoveredCode = OpenLocationCode.recoverNearest(shortCode, referenceLat, referenceLng)
println(recoveredCode.value) // Output: 8FVC9G8F+6X

You can validate strings to see if they are structurally sound Plus Codes:

val isValid = OpenLocationCode.isValidCode("8FVC9G8F+6X") // true
val isFull = OpenLocationCode.isFullCode("8FVC9G8F+6X") // true
val isShort = OpenLocationCode.isShortCode("9G8F+6X") // true

This repository is optimized for AI-Assisted Development. If you are an AI agent, you must read the Agent Onboarding Guide before contributing to this codebase.

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for details.