Address Formatter

March 17, 2026 · View on GitHub

Overview

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:

Formats address component maps (road, city, postcode, country, etc.) into locale-aware address strings
Supports abbreviation of common terms (e.g. "Avenue" → "Ave")
Optionally appends the country name to the formatted address
Allows overriding address templates for specific countries via a KSP annotation processor
Ships as a multiplatform library (JVM and iOS)

This library has only the Kotlin standard library as a runtime dependency.

Requirements

Java 11 or above
Gradle 9.4+ (a wrapper is included; no separate installation needed)
Kotlin 2.3+ (provided transitively via the library)

Installation

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>

Usage

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
*/

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.

Install

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'
}

Usage

@AddressTemplateDefinition("""
{{{road}}} {{{house_number}}}
{{{postcode}}} {{{city}}}
""",
propertyName = "customUSFormat")
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
*/

The supported format is a small subset of the Mustache specification. You can find more information in the @AddressTemplateDefinition documentation.

How to Run Locally

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

How to Deploy

Releases are published to Maven Central. The full release process is documented in docs/release.md. In summary:

Bump the version number in 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.
Commit the changes, create a Git tag with the new version name, and push both.
Create a GitHub release from the new tag.
The Publishing workflow is triggered automatically by the tag push and publishes the artifacts to Maven Central.

License

This project is licensed under the Apache 2.0. See the LICENSE for details.