random-address

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 on this page — 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

random-address on PyPI

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

Evidence: random_address-2.1.0-py3-none-any.whl

Keywords: address, random, fake-data, test-data, fixtures, geocoding, openaddresses

Tags

More Python Modules packages