How to Build a US Address Generator in Go

Author:

How to Build a US Address Generator in Go: A Step-by-Step Guide

Introduction: The Developer Who Needed Better Test Addresses

Imagine you are a developer working on an online shopping platform. Your team is preparing to launch a new checkout system, and everything appears ready. Customers can select products, enter payment details, and choose shipping options. However, when the testing team starts checking different delivery scenarios, problems begin to appear.

Some addresses are missing ZIP Codes. Others contain incorrectly formatted state abbreviations. A few tests fail because the application cannot handle apartment numbers or different address formats.

You soon discover that repeatedly typing sample addresses is wasting valuable development time. Your team needs a reliable way to generate test data quickly.

This is where a US address generator in Go becomes useful.

Go, also known as Golang, is a programming language valued for its straightforward syntax, efficient performance, and strong support for building backend services. By using Go to build a random US address generator, you can create realistic-looking test records for applications, databases, websites, and software testing environments.

In this guide, we will walk through the process of building a simple address generator in Go, improving its output, exporting generated addresses, and understanding the difference between synthetic test data and real, deliverable addresses.

What Is a US Address Generator?

A US address generator is a software tool that creates address records following the general structure used for addresses in the United States.

A typical US mailing address contains several components:

  • Street number and street name
  • Apartment, unit, or suite number when applicable
  • City
  • State abbreviation
  • Five-digit ZIP Code, or a ZIP+4 Code when appropriate

A generated record might look like this:

742 Example Avenue
Apartment 5B
Austin, TX 00000
United States

This example is deliberately synthetic. The street details are illustrative, and 00000 is a placeholder rather than a valid ZIP Code for Austin.

That distinction matters. A program can generate information that looks like an address without confirming that the street exists or that mail can be delivered there.

For developers, synthetic addresses are often enough for testing form layouts, database operations, checkout workflows, and error handling. When a project requires verified mailing addresses, the generator needs a separate validation process.

Why Use Go to Build an Address Generator?

Go is a practical choice for building a US address generator because it combines readable code with useful standard-library features.

First, Go makes it straightforward to represent address components using structs. Instead of keeping street names, cities, and ZIP Codes in unrelated variables, you can organize them into a single address record.

Second, its standard library supports random number generation, file handling, CSV output, and testing. You can build an initial generator without installing a large collection of external packages.

Third, Go works well for command-line utilities and backend applications. You can begin with a small program that generates ten addresses and later adapt it into a web service or an internal testing tool.

Consider a developer named Marcus who is building a delivery application. Rather than manually creating hundreds of test records, Marcus decides to build a small Go program that selects address components from predefined lists. The first version is simple, but it gives him a foundation he can improve as his application’s requirements grow.

Step 1: Install Go and Create Your Project

Before writing the generator, make sure Go is installed on your computer.

Visit the official Go programming language website at https://go.dev/dl/ to find the appropriate installation package for your operating system. After installation, open a terminal and check your version:

go version

Next, create a project directory and initialize a Go module:

mkdir us-address-generator
cd us-address-generator
go mod init example.com/us-address-generator

Create a file named main.go inside the directory.

You now have a basic project structure. As the project develops, you can add tests, sample output files, and additional packages without changing the basic setup.

Step 2: Decide Which Address Components to Generate

A common beginner’s mistake is to generate a complete address as one long string. That approach can work for a demonstration, but it makes the program harder to maintain.

A better approach is to store each component separately.

For this example, we will use predefined lists of street names, cities, and state abbreviations. We will also use ZIP Code-shaped placeholders to demonstrate how the generator works.

The lists below are illustrative rather than a verified postal database. The program will produce synthetic test records, not confirmed residential or business locations.

Start by defining an address structure:

type Address struct {
    Street string
    City   string
    State  string
    ZIP    string
}

This structure represents one generated address. Each field has a clear purpose, making the data easier to print, save, test, or send to another part of an application.

For example, a checkout test could inspect the State field independently rather than trying to extract the state abbreviation from a completed address string.

Step 3: Write the Address Generator

Now it is time to bring the components together.

The program will randomly select a street name, city, and state from small sample lists. It will also generate a five-digit numeric string for the ZIP field.

Remember that a five-digit string is not necessarily a valid ZIP Code. This version is intended for testing software behavior, not creating deliverable addresses.

Replace the contents of main.go with the following code:

package main

import (
    "fmt"
    "math/rand"
    "time"
)

type Address struct {
    Street string
    City   string
    State  string
    ZIP    string
}

var streets = []string{
    "Example Avenue",
    "Sample Street",
    "Demo Road",
    "Testing Lane",
    "Prototype Drive",
}

var cities = []string{
    "Austin",
    "Denver",
    "Columbus",
    "Phoenix",
    "Raleigh",
}

var states = []string{
    "TX",
    "CO",
    "OH",
    "AZ",
    "NC",
}

func randomItem(items []string) string {
    return items[rand.Intn(len(items))]
}

func generateAddress() Address {
    return Address{
        Street: fmt.Sprintf(
            "%d %s",
            rand.Intn(9000)+1000,
            randomItem(streets),
        ),
        City:  randomItem(cities),
        State: randomItem(states),
        ZIP: fmt.Sprintf("%05d", rand.Intn(100000)),
    }
}

func main() {
    rand.Seed(time.Now().UnixNano())

    for i := 0; i < 10; i++ {
        address := generateAddress()

        fmt.Printf(
            "%s, %s, %s %s\n",
            address.Street,
            address.City,
            address.State,
            address.ZIP,
        )
    }
}

This program demonstrates the core idea behind a random US address generator in Go.

The Address struct holds the generated data. The slices store possible values, and the randomItem function chooses one item from a list. The generateAddress function combines those selections into a single record.

The street number is generated between 1000 and 9999, while the ZIP field is formatted as five digits, including leading zeros when necessary.

One important detail is that the city, state, and ZIP Code are selected independently. As a result, the program may produce combinations that do not correspond to real locations. That is acceptable for certain interface tests, but it is not suitable for validating real shipping destinations.

Step 4: Run the Program

Save the file and run the following command:

go run main.go

The program prints ten generated records to your terminal.

Your output will change between runs because the program makes random selections. A fictional result could look like this:

2841 Demo Road, Denver, CO 08321
6194 Sample Street, Austin, TX 00472
7510 Testing Lane, Phoenix, AZ 63840

These examples illustrate the output format only. The ZIP Codes and street combinations have not been verified.

If you want to generate more addresses, change the loop limit from 10 to 100, 500, or another suitable number. For larger datasets, you should also consider saving the results to a file rather than displaying every record in the terminal.

Step 5: Improve the Generator with Better Data Organization

Once Marcus has a working prototype, he notices an important limitation. The generator can produce a street from one state and a city from another. A record might claim to be in Denver, Texas, even though Denver is associated with Colorado.

The next improvement is to group cities and states together.

Instead of maintaining independent city and state lists, define a location structure:

type Location struct {
    City  string
    State string
}

var locations = []Location{
    {City: "Austin", State: "TX"},
    {City: "Denver", State: "CO"},
    {City: "Columbus", State: "OH"},
    {City: "Phoenix", State: "AZ"},
    {City: "Raleigh", State: "NC"},
}

Your generator can then select one location and use both fields from that same record.

This reduces mismatched city and state combinations. However, it does not solve every address-quality problem. The street may still be fictional, and the ZIP Code may not belong to the selected city.

For better test data, you can store verified city, state, and ZIP Code combinations together. For a production application, you should use an appropriate validation service rather than assuming that a generated record is deliverable.

Step 6: Generate Multiple Addresses and Export Them to CSV

A terminal demonstration is useful while developing, but CSV export makes the tool more practical.

CSV files can be opened in spreadsheet applications, imported into test databases, or processed by other scripts. Go’s standard encoding/csv package provides the functionality you need.

Add these imports to your program:

import (
    "encoding/csv"
    "fmt"
    "math/rand"
    "os"
    "time"
)

Then create a function that writes generated addresses to a file:

func exportCSV(filename string, count int) error {
    file, err := os.Create(filename)
    if err != nil {
        return err
    }
    defer file.Close()

    writer := csv.NewWriter(file)
    defer writer.Flush()

    if err := writer.Write(
        []string{"Street", "City", "State", "ZIP"},
    ); err != nil {
        return err
    }

    for i := 0; i < count; i++ {
        address := generateAddress()

        record := []string{
            address.Street,
            address.City,
            address.State,
            address.ZIP,
        }

        if err := writer.Write(record); err != nil {
            return err
        }
    }

    return writer.Error()
}

You can call this function from main:

if err := exportCSV("addresses.csv", 100); err != nil {
    fmt.Println("Export failed:", err)
    return
}

fmt.Println("Generated 100 synthetic test addresses.")

Make sure the relevant imports and functions are included in the same Go file. If you keep the original terminal loop, the program will both print records and export a separate dataset.

The result is an addresses.csv file containing a header row and 100 generated records. Label such files clearly as synthetic test data so they are not mistaken for customer records or valid mailing lists.

Step 7: Add Tests Before Using the Generator

A working program is not necessarily a reliable program. Before using your generator in a testing workflow, write tests that check its expected behavior.

For example, you can verify that a generated address contains nonempty street, city, state, and ZIP fields. You can also check that the ZIP string contains exactly five numeric characters.

Create a file named main_test.go:

package main

import (
    "regexp"
    "testing"
)

func TestGenerateAddress(t *testing.T) {
    address := generateAddress()

    if address.Street == "" ||
        address.City == "" ||
        address.State == "" {
        t.Fatal("address fields must not be empty")
    }

    matched, err := regexp.MatchString(
        `^[0-9]{5}$`,
        address.ZIP,
    )
    if err != nil {
        t.Fatal(err)
    }

    if !matched {
        t.Fatalf("invalid ZIP format: %q", address.ZIP)
    }
}

Run the test with:

go test ./...

This test checks formatting, not postal validity. A five-digit string may still be unassigned, incorrect for a city, or unsuitable for delivery.

You can extend the test suite to check the number range, required fields, CSV export errors, and any rules specific to your application. If you need repeatable test results, use a controlled random source or pass a seeded random generator into your address-generation functions.

Step 8: Understand Synthetic Addresses and Real Address Validation

At this point, your Go address generator can create sample records and export them. The next question is whether those records need to represent real locations.

For user-interface testing, randomly generated components may be enough. You can test whether a form accepts a street address, displays a state abbreviation, and handles a ZIP field without using anyone’s personal information.

For shipping, billing, and delivery workflows, however, format alone is insufficient.

The United States Postal Service provides an official developer portal and an Addresses API for validating and standardizing US addresses. Its current documentation describes address standardization, city and state lookup, and ZIP Code lookup. You can explore the official documentation at https://developers.usps.com/addressesv3. <Cite refs={[“turn981566search2″,”turn981566search4”]} />

Google Maps Platform also offers an Address Validation API that checks address components and can standardize addresses. Its documentation explains that US and Puerto Rico requests can use CASS support when appropriately enabled. Review the requirements, coverage, terms, and costs before integrating it. <Cite refs={[“turn981566search0″,”turn981566search10”]} />

One crucial limitation deserves attention: do not use a postal validation API as a source for harvesting or inventing addresses. The USPS documentation states that its address API is intended to validate, complete, and correct address information captured through your own processes, rather than to source addresses for a database. <Cite refs={[“turn981566search12″,”turn981566search8”]} />

A responsible design keeps synthetic data generation separate from address verification. Generate artificial records for software tests, and validate genuine user-provided addresses only where your application has a legitimate need and the relevant service permits that use.

Step 9: Make the Generator Safer and Easier to Maintain

Before expanding the project, consider a few practical improvements.

First, avoid hard-coding every value directly into the generator. Store test fixtures in a JSON or CSV file if the dataset becomes large. This makes it easier to review and update the sample records.

Second, make the number of generated records configurable through command-line flags. A developer should be able to request 20 records for a quick test or 5,000 records for a database-loading exercise without editing the source code each time.

Third, separate address generation, formatting, and export into distinct functions. This makes the project easier to test and maintain.

Fourth, label all generated data clearly. If your test records could accidentally be used for real shipments, introduce safeguards that prevent synthetic addresses from reaching production workflows.

Finally, avoid using real people’s home addresses as convenient examples. Synthetic fixtures reduce privacy risks and make it easier to share test datasets with teammates.

Common Mistakes to Avoid When Building a Go Address Generator

Several mistakes can make an address generator less useful than it first appears.

Assuming every generated address is real: Randomly combining street names, cities, states, and ZIP Codes creates plausible-looking text, not verified locations.

Ignoring ZIP Code formatting: ZIP Codes should generally be stored as strings rather than integers. A numeric type can remove leading zeros.

Mixing city and state values: Selecting these components independently can produce contradictory records. Grouping known combinations together is a better approach.

Skipping tests: Without automated tests, changes to the generator can introduce missing fields, malformed output, or broken CSV exports.

Using synthetic data in production: Test addresses should not accidentally enter customer databases, shipping labels, or billing workflows. Separate test environments and clear data labels help prevent this.

Depending on outdated API instructions: Before integrating an external address service, check its current developer portal, authentication requirements, terms of use, and supported endpoints.

Conclusion: Build a Useful Tool, Not Just Random Text

Building a US address generator in Go is a manageable project that teaches several valuable programming skills. You learn how to structure data with structs, select values from slices, generate random components, write CSV files, and test your functions.

The first version can be small. Start with a few sample locations, generate records, and confirm that the output follows your application’s expected format. Then improve the program with grouped location data, configurable record counts, automated tests, and file export.

Most importantly, understand what your tool actually produces. A synthetic US address generator is excellent for testing forms, checkout flows, and database logic, but it does not automatically create valid mailing addresses.

By keeping test-data generation separate from real address validation, you can build a Go utility that is practical, maintainable, and safer to use as your software grows.

Categories: US Address Generator

Leave a Reply