---
id: random-address
version: "2.1.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# random-address — Retrieve real random US addresses, with coordinates, for tests and fixtures

License: permissive · Maintenance: active · Downloads: 92.9K/mo

## What it is and what it does

Random-address retrieves real US addresses from the OpenAddresses public dataset, which aggregates address data published by government agencies. Each address includes latitude and longitude coordinates that resolve to actual map points without requiring a geocoding API call. The package is built specifically for testing: seeding test fixtures, exercising address form validation, and providing geolocation code with genuine data to work against.

The package offers both single and batch address retrieval with optional filtering by state, city, or postal code. Addresses can be made reproducible via a seed parameter, and the package provides inspection functions to explore what states, cities, and postal codes are available in the dataset. It includes both a Python API and a command-line interface for generating addresses in plain text, JSON, or CSV format.

Use it for:

- Seed test fixtures with real addresses to validate address form parsing and storage logic.
- Test geolocation and mapping code with genuine coordinates without hitting external geocoding services.
- Generate CSV files of test addresses for bulk testing address validation across multiple states.
- Reproduce test scenarios consistently by passing a seed to get the same address every time.
- Validate address filtering logic by narrowing results to specific states, cities, or postal codes.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Generates random real US addresses with coordinates from authoritative government sources, designed for testing address forms, geolocation code, and test fixtures.

Yes. The package solves a genuine testing need with zero dependencies, active maintenance, and a permissive MIT license. It is lightweight to install and use, requires only Python 3.10+, and has no known vulnerabilities. Install it if you need real address data for testing without external API calls.

## Install

pip install random-address
uv add random-address
poetry add random-address

## Installing random-address

Before you install: Low friction installation with no runtime dependencies. Actively maintained with a recent release; supports current Python versions (3.10+).

License in practice: MIT license permits unrestricted use, modification, and distribution in both open and proprietary projects with minimal restrictions.

Quickstart:

pip install random-address

from random_address import real_random_address
addr = real_random_address(state='CA')
print(addr['address1'], addr['city'], addr['postal_code'])

Requires Python 3.10 or newer.

Verify before relying:

- Whether the dataset of 3300 addresses is sufficient for large-scale testing scenarios.
- Performance characteristics when filtering by state, city, or postal code with large result sets.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 92.9K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

random address generator testing, fake address data fixtures, us address test data, address form testing, geolocation test addresses, real random addresses, address dataset for testing, test-fixtures, address-data, geolocation

[View on SkillFed](https://skillfed.io/packages/random-address) · [View on PyPI](https://pypi.org/project/random-address/)