gridpin

Test addresses for your integration tests

Tests of a checkout form or an address import need addresses that exist, and the same ones each time. Made-up addresses test the wrong path; production data should not be in a test fixture.

New Use the data itself Command line

What you have

The country file. Nothing else.

Steps

1. Draw four Chicago addresses with a fixed seed:

terminalCLI
$ gridpin sample usa.bin --city Chicago --n 4 --seed 7 -o sample.csv
4 addresses out of 590544
terminalCLI
$ cat sample.csv
# license: mixed permissive: U.S. Government work (17 U.S.C. §105), NYC Open Data (Admin Code §23-502), CC0 1.0, PDDL 1.0, CC BY 4.0, open data terms of Los Angeles County, Oakland County, MassGIS, MnGeo, Oregon GEOHub
# attribution: National Address Database (USDOT) and state and county open data, datasets: NAD, us/ma/statewide, us/ca/los_angeles, us/mn/statewide, us/or/statewide, us/ny/city_of_new_york, us/fl/hillsborough, us/ca/sacramento, us/mi/oakland, us/ca/fresno, us/ga/dekalb, us/ca/san_francisco, us/fl/manatee, us/id/ada, us/la/city_of_new_orleans, us/pa/lackawanna, us/ga/clarke, us/ca/napa, us/ca/nevada, us/wi/waupaca; via Overture Maps / OpenAddresses, release 2026-09-23.1; address normalization applied; partial coverage (sources with an explicit right to redistribute); settlement names © GeoNames (CC BY 4.0)
lat,lon,street,housenumber,postcode,commune,region
42.0176091,-87.68146,North SEELEY Avenue,7461,60645,Chicago,
41.9077607,-87.7679619,North WALLER Avenue,1505,60651,Chicago,
41.7705737,-87.6066438,South EVANS Avenue,6823,60637,Chicago,
41.9214079,-87.7239654,North SPRINGFIELD Avenue,2217,60647,Chicago,

2. The same seed gives the same file:

terminalCLI
$ gridpin sample usa.bin --city Chicago --n 4 --seed 7 -o again.csv
4 addresses out of 590544
terminalCLI
$ cmp sample.csv again.csv && echo same
same

What you get

A CSV with the point, street, number, postcode and town of each address, after two comment lines with the licence and attribution of the data. --format also gives JSONL, GeoJSON or GPX; --near, --bbox, --polygon and --postcode choose the area.

Why it works

The sample is drawn from the addresses of the file with a random generator started from --seed; without it, the seed comes from the clock and a run differs. The file itself does not change within a release, so a seed and a release name a fixed set.

Limits

  • Real addresses are real homes: keep test data in test systems, and do not mail them.
  • The licence lines travel with the data; keep them with any fixture you commit.
  • A new release of the country file can give different addresses for the same seed.

All its keys: command reference. The function: the sheet as a table.

More