Formats addresses using OpenCage templates, allowing customization of address formats per country. Supports abbreviation and appending country names with minimal dependencies.
A Kotlin library for formatting address components into human-readable address strings. It uses the address templates from OpenCage to produce correctly formatted addresses for countries worldwide.
Key features:
This library has only the Kotlin standard library as a runtime dependency.
Add the library to your dependencies.
Gradle (Kotlin)
dependencies {
implementation("com.bettermile:address-formatter-kotlin:0.4.7")
}
Gradle (Groovy)
dependencies {
implementation 'com.bettermile:address-formatter-kotlin:0.4.7'
}
Maven
<dependency>
<groupId>com.bettermile</groupId>
<artifactId>address-formatter-kotlin</artifactId>
<version>0.4.7</version>
</dependency>
If you like to overwrite some default address templates, but still want to keep the component cleanup done by the
formatter, you can overwrite the address template for specific countries in the AddressFormatter constructor.
Gradle (Kotlin) additions
plugins {
id("com.google.devtools.ksp") version "<CURRENT_KSP_VERSION>"
}
dependencies {
ksp("com.bettermile:address-template-processor:0.4.7")
}
Gradle (Groovy) additions
plugins {
id 'com.google.devtools.ksp' version '<CURRENT_KSP_VERSION>'
}
dependencies {
ksp 'com.bettermile:address-template-processor:0.4.7'
}
The supported format is a small subset of the Mustache specification. You can find more
information in the @AddressTemplateDefinition documentation.
Prerequisites: Java 11+
Clone the repository including its submodule (the OpenCage address-formatting templates):
git clone --recurse-submodules https://github.com/bettermile/address-formatter-kotlin.git
cd address-formatter-kotlin
Build and run all tests:
./gradlew build
Publish to your local Maven repository (useful for testing the library in another project):
./gradlew publishToMavenLocal
To regenerate the address templates from the OpenCage submodule (e.g. after updating the submodule):
./gradlew :YamlConverter:run
Releases are published to Maven Central. The full release process is documented in docs/release.md. In summary:
README.md (Installation and Overwrite formats sections) and in the publishing
configuration of formatter/build.gradle.kts, template/build.gradle.kts, and
template-processor/build.gradle.kts.This project is licensed under the Apache 2.0. See the LICENSE for details.
val formatter = AddressFormatter(abbreviate = false, appendCountry = false)
val components = mapOf(
"country_code" to "US",
"house_number" to "301",
"road" to "Hamilton Avenue",
"neighbourhood" to "Crescent Park",
"city" to "Palo Alto",
"postcode" to "94303",
"county" to "Santa Clara County",
"state" to "California",
"country" to "United States",
)
println(formatter.format(components))
/*
301 Hamilton Avenue
Palo Alto, CA 94303
United States of America
*/
val abbreviateFormatter = AddressFormatter(abbreviate = true, appendCountry = false)
println(abbreviateFormatter.format(json))
/*
301 Hamilton Ave
Palo Alto, CA 94303
United States of America
*/
val appendCountryFormatter = AddressFormatter(abbreviate = false, appendCountry = true)
println(appendCountryFormatter.format(json))
/*
301 Hamilton Avenue
Palo Alto, CA 94303
United States of America
*/
val formatter = AddressFormatter(abbreviate = false, appendCountry = false, mapOf("US" to AddressTemplates.customUSFormat))
val components = mapOf(
"country_code" to "US",
"house_number" to "301",
"road" to "Hamilton Avenue",
"neighbourhood" to "Crescent Park",
"city" to "Palo Alto",
"postcode" to "94303",
"county" to "Santa Clara County",
"state" to "California",
"country" to "United States",
)
println(formatter.format(components))
/*
Hamilton Avenue 301
94303 Palo Alto
*/
Surfaced from shared tags and platforms — no rankings paid for.