How to Build a US Address Generator for Android in Kotlin
Introduction
Imagine an Android developer preparing to launch a new shopping application. The product pages are working, customers can add items to their carts, and the payment screen looks ready. However, the checkout form still needs testing. The developer needs different American address records to check field validation, apartment numbers, state selection, and ZIP code formatting.
Using real customers’ addresses would introduce unnecessary privacy risks. Manually creating hundreds of examples would also take valuable time. A better solution is to build a US address generator for Android in Kotlin.
A US address generator creates sample address records that developers can use to test mobile applications, populate development databases, and evaluate address forms. With Kotlin, Android Studio, and Jetpack Compose, it is possible to build an application that generates, displays, copies, and exports fictional address records.
This project is useful for beginners learning Android development and experienced programmers who want a lightweight testing utility. The most important principle is to distinguish between a realistic-looking address and a verified mailing address. A randomly generated record should never be assumed to represent a real property.
Understanding How a US Address Generator Works
Before opening Android Studio, it helps to understand the purpose of the application. A typical US address contains a street number, street name, optional apartment or unit number, city, state abbreviation, and ZIP code.
A sample record might look like this:
Fictional address for software testing
4827 Example Creek Drive
Sampletown, TX 00000
This example uses a fictional street and placeholder ZIP code. It demonstrates the layout of an address without claiming that the record is a genuine delivery destination.
A US address generator can create records from predefined test data, select from approved sample datasets, or combine components according to rules. For a beginner project, predefined fictional data is the easiest option because it gives the developer complete control over the generated output.
The application can begin with a single Generate Address button. Later, it can include state filters, batch generation, clipboard support, and CSV or JSON export.
Setting Up Android Studio and Kotlin
Every Android project begins with a development environment. Android Studio provides the editor, emulator, debugging tools, and build system needed to create and test an Android application.
Google LLC, the company behind Android and Android Studio, has its headquarters at 1600 Amphitheatre Parkway, Mountain View, CA 94043, USA. Developers can find installation instructions and official Android development guides at https://developer.android.com/.
Install Android Studio, create a new project, and select a template that supports Jetpack Compose. Choose Kotlin as the programming language and name the project USAddressGenerator.
Jetpack Compose is useful because it lets developers build interfaces directly in Kotlin using composable functions. Instead of maintaining separate layout files for every screen, developers can describe the interface using code that responds to changes in application state.
For this project, the first screen needs a title, a display area for the generated address, and a button that generates another record. Keeping the initial interface small makes the application easier to understand and troubleshoot.
Creating the Address Data Model
The first programming task is to define what an address record contains. Kotlin data classes are well suited to this because they group related information into a single object.
Create a file named Address.kt and add the following code:
data class Address(
val street: String,
val unit: String?,
val city: String,
val state: String,
val zipCode: String
) {
fun formattedAddress(): String {
val unitLine = unit?.let { "\n$it" } ?: ""
return "$street$unitLine\n$city, $state $zipCode"
}
}The class stores the street, optional unit, city, state, and ZIP code. The formattedAddress() function combines these fields into a readable format.
The unit field is nullable because some addresses do not include apartments or suites. If a unit exists, the function displays it on a separate line. Otherwise, it leaves that line out.
Separating the address model from the rest of the application is a useful programming habit. The same class can be reused when displaying addresses, copying them to the clipboard, or exporting them to a file.
Building the Address Generator Logic
With the data model in place, the application needs a function that creates new records. A straightforward approach is to define a collection of fictional street names and sample locations, then select an entry at random.
Create a new file called AddressGenerator.kt:
import kotlin.random.Random
object AddressGenerator {
private val sampleLocations = listOf(
Triple("Austin", "TX", "TEST-TX-001"),
Triple("Denver", "CO", "TEST-CO-001"),
Triple("Phoenix", "AZ", "TEST-AZ-001"),
Triple("Raleigh", "NC", "TEST-NC-001"),
Triple("Columbus", "OH", "TEST-OH-001")
)
private val streetNames = listOf(
"Example Creek Drive",
"Sample Meadow Lane",
"Fictional Oak Street",
"Demo Valley Road",
"Test Garden Avenue"
)
fun generate(): Address {
val location = sampleLocations.random()
val streetNumber = Random.nextInt(100, 9999)
val unit = if (Random.nextBoolean()) {
"Unit ${Random.nextInt(1, 50)}"
} else {
null
}
return Address(
street = "$streetNumber ${streetNames.random()}",
unit = unit,
city = location.first,
state = location.second,
zipCode = location.third
)
}
}This example demonstrates random selection and keeps each city associated with its intended state. The ZIP code field deliberately contains a clearly labelled test identifier rather than a plausible but potentially incorrect postal code.
That choice matters. A random five-digit number may look like a ZIP code without being associated with the selected city. Even if a number is a genuine ZIP code, that does not establish that the street address exists.
For a production testing tool, use a properly licensed dataset or a documented test-data scheme. Keep synthetic identifiers visibly separate from real postal information.
Designing the Android Interface with Jetpack Compose
The generator can now create records, but users need a way to see them. The next step is building a screen with a title, an address display, and a button.
Open MainActivity.kt and use the following example:
import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.layout.*
import androidx.compose.material3.*
import androidx.compose.runtime.*
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
class MainActivity : ComponentActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContent {
AddressGeneratorScreen()
}
}
}
@Composable
fun AddressGeneratorScreen() {
var address by remember {
mutableStateOf(AddressGenerator.generate())
}
MaterialTheme {
Column(
modifier = Modifier
.fillMaxSize()
.padding(24.dp),
verticalArrangement = Arrangement.spacedBy(16.dp)
) {
Text(
text = "US Address Generator",
style = MaterialTheme.typography.headlineSmall
)
Text(
text = "Fictional test data",
style = MaterialTheme.typography.labelMedium
)
Text(
text = address.formattedAddress(),
style = MaterialTheme.typography.bodyLarge
)
Button(
onClick = {
address = AddressGenerator.generate()
}
) {
Text("Generate New Address")
}
}
}
}When the screen opens, the app generates a sample record. Every time the user taps the button, the address state changes and Compose redraws the relevant content.
The remember function retains the current value during ordinary recompositions, while mutableStateOf allows Compose to observe changes. For a larger application, developers may move this state into a ViewModel so that it is easier to manage and test.
Official Jetpack Compose documentation is available at https://developer.android.com/jetpack/compose.
Adding State Selection and Batch Generation
Once the basic screen works, consider how a developer might use it in a real testing session. Someone testing a regional delivery form may need only Texas records, while another developer may need examples for several states.
Add a dropdown menu that lets the user choose a state. The generator can then filter its sample data and produce records for the selected location. Keep city, state, and any postal test values in the same structured record to prevent unrelated components from being combined accidentally.
Batch generation is another valuable feature. Instead of creating one address at a time, allow users to request a set of ten, twenty, or fifty fictional records.
A function could return a list of addresses:
fun generateMany(count: Int): List<Address> {
return List(count) {
AddressGenerator.generate()
}
}Before using this function, validate the requested count and impose a sensible maximum. This prevents an accidental request for an enormous dataset from slowing down the application.
The interface can display generated records in a scrollable list, with each record presented in its own card. A clear label such as “Synthetic test data” should remain visible so that users do not mistake the records for verified addresses.
Adding Copy and Export Features
After generating an address, a developer will often want to use it in another application. A Copy Address button can make this process much faster.
Android supports clipboard operations through its platform clipboard services. In a Compose application, use the clipboard API appropriate to the Compose version in the project. When the user taps Copy, place the formatted address on the clipboard and display a brief confirmation.
For larger testing sessions, CSV and JSON exports can be even more useful. CSV files work well with spreadsheets, while JSON is convenient for API testing and development databases.
For example, a JSON record could contain fields for street, unit, city, state, and zipCode. Make sure the export preserves the distinction between placeholder values and verified postal data.
Use Android’s supported file-creation and sharing mechanisms to let users choose where exported files go. Avoid silently writing test data into unrelated folders or sending it to external services without a clear reason.
Distinguishing Address Generation from Address Verification
One of the most important lessons in this project is that address generation and address verification are different tasks.
A generator creates sample records according to its rules. A verification service checks supplied address information against relevant reference data and may return corrections, standardized components, or information about address quality.
The United States Postal Service provides official address tools and developer resources. USPS is located at 475 L’Enfant Plaza SW, Washington, DC 20260, USA. Its website is https://www.usps.com/, and its developer portal is https://developers.usps.com/.
Google also provides an Address Validation API that can standardize addresses and assess address components. Its documentation is available at https://developers.google.com/maps/documentation/address-validation/overview.
However, developers should not assume that any verification service can be used to check artificially generated addresses. Google’s documentation specifically describes USPS requirements concerning artificially created addresses. Review the provider’s rules before submitting generated data to a live validation service.
For a basic offline generator, verification is unnecessary. If the application must support real deliveries, use a suitable, permitted address verification workflow and clearly separate that functionality from fictional test-data generation.
Testing the Android Address Generator
A reliable application needs more than a screen that appears to work. Begin by launching the app in an Android emulator or on a test device. Check that an address appears immediately and that the Generate New Address button updates the displayed record.
Next, test the data model. Confirm that the formatted output includes the street, city, state, and test identifier. Check that records without apartment information do not display an unwanted blank line.
Test the state selection feature if you have added it. Every generated record should use a location from the selected state’s dataset. For batch generation, verify that the requested number of records is returned and that the application remains responsive.
Finally, test clipboard and export features. Confirm that copied text contains the expected line breaks and that exported files contain the correct field names and values.
You should also check the layout on different screen sizes and with larger accessibility font settings. Buttons need clear labels, and long street names should not make the screen difficult to use.
Common Mistakes to Avoid
A frequent mistake is generating a plausible ZIP code and treating it as valid. Another is choosing city and state values independently, which can create inconsistent records.
Avoid putting all the logic inside MainActivity.kt. Keeping the model, generator, and interface separate makes the application easier to maintain. It also allows the generator to be tested without launching the user interface.
Do not use real residents’ addresses as convenient sample data when synthetic records are sufficient. Keep generated records out of production customer databases, and clearly mark them as fictional.
Finally, do not add external services before they are necessary. An offline generator is easier to build, can work without a network connection, and avoids sending data to third parties.
Future Improvements for the Application
Once the basic project is complete, several improvements are possible. You could add filters for states, a batch-size selector, saved test collections, and a choice between CSV and JSON exports.
A View Model could make the app’s state easier to manage, while unit tests could check the generator’s output independently. If a legitimate use case requires postal accuracy, a separate verification module can be introduced with careful attention to service terms, costs, privacy, and data licensing.
You could also add a history screen that stores generated test records locally. Include a clear option to delete the history and avoid collecting personal information that the app does not need.
Conclusion
Building a US address generator for Android in Kotlin is a practical way to learn mobile development while creating a useful testing tool. The project brings together Kotlin data classes, random selection, Jetpack Compose, clipboard functionality, and file export.
Start with a small collection of fictional records, then add state selection and batch generation as your skills improve. Keep test identifiers clearly labelled, maintain consistent location data, and never assume that a generated record is a real or deliverable address.
With a clear structure and responsible use of synthetic data, your Android address generator can become a dependable utility for development, quality assurance, and learning.