Documentation ¶
Overview ¶
Package ziptools provides functionality to search through USA zip codes and cities in extremely fast way. Internally it uses the Bolt — blazing fast key-value storage that allows to cache the codes and city names with efficiency. LOCODE searches supported.
$ go test -bench=. PASS BenchmarkGetCity 500000 2408 ns/op BenchmarkGetLocation 500000 6582 ns/op BenchmarkGetZips 200000 11863 ns/op BenchmarkGetLocodes 500000 3775 ns/op BenchmarkFindZips 500000 6958 ns/op BenchmarkFindCities 5000 360797 ns/op BenchmarkFindLocodes 200000 10354 ns/op ok github.com/xlab/ziptools 16.792s
Database should be created using a CSV file located at http://www.unitedstateszipcodes.org/zip_code_database.csv. The gzipped version of that file with stripped CSV header is included within this package.
The zipimport tool is suited for Bolt DB creation from that gzipped CSV.
$ zipimport -h Usage of zipimport: -zips="zip_code_database.csv.gz": gzipped .csv file with zip codes. -locodes="us_locode_database.csv.gz": gzipped .csv file with locodes. -db="zipcodes.db": file to store a newly created zip codes database.
Installation and Examples ¶
After the Bolt database is created, you may remove zip_code_database.csv.gz.
go get https://github.com/xlab/ziptools/zipimport go get https://github.com/xlab/ziptools/zipsearch zipimport du -csh zipcodes.db
The zipsearch tool leverages the ziptools package and provides a simple cli interface for searching zip codes and cities within a console window (for testing purposes).
$ zipsearch -h Usage of zipsearch: -city=false: given string is a city name or its part -db="zipcodes.db": specify zip codes database. -exact=false: look for exact match
List all zipcodes in city:
$ zipsearch -exact -city Richardson Zip codes in Richardson: [75080 75081 75082 75083 75085]
Get the city that has the specified zip:
$ zipsearch -exact 10106 Zip 10106 belongs to New York.
List all cities that match the given substring:
$ zipsearch -city english Cities that match english: ziptools.CityList{"Englishtown", "English", "North English", "South English"}
List all zips that match the given substring:
$ zipsearch 1337 Zip codes that match 1337: [01337 61337 91337]
Index ¶
- Constants
- type CityList
- type DB
- func (d *DB) Close()
- func (d *DB) FindCities(citypart string) (cities CityList, err error)
- func (d *DB) FindLocodes(citypart string) (locodes LocodeList, err error)
- func (d *DB) FindZips(zippart string) (zips ZipList, err error)
- func (d *DB) GetCity(z Zip) (city string, err error)
- func (d *DB) GetLocation(l Locode) (loc *Location, err error)
- func (d *DB) GetLocodes(city string) (locodes LocodeList, err error)
- func (d *DB) GetZips(city string) (zips ZipList, err error)
- type Location
- type Locode
- type LocodeList
- type Zip
- type ZipList
Constants ¶
const ( // ZipLen is the default length of Zip ZipLen = 5 // LocodeLen is the default length of Locode LocodeLen = 3 )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DB ¶
type DB struct {
// contains filtered or unexported fields
}
DB abstracts database access.
func (*DB) FindCities ¶
Find all cities that match the given substring.
func (*DB) FindLocodes ¶
func (d *DB) FindLocodes(citypart string) (locodes LocodeList, err error)
Find all locodes by a given substring of a city name.
func (*DB) GetCity ¶
GetCity gets a city that is assigned to the specified zip code. This methods looks for an exact match.
func (*DB) GetLocation ¶
GetLocation gets a location that is assigned to the specified locode. This methods looks for an exact match.
func (*DB) GetLocodes ¶
func (d *DB) GetLocodes(city string) (locodes LocodeList, err error)
Get a list of locodes for the specified city. This methods looks for an exact match.
type Location ¶
Location represents transport location.
type Locode ¶
Locode represents a locode.
func (Locode) MarshalJSON ¶
MarshalJSON represents a locode as a string while marshaling as JSON.
func (*Locode) UnmarshalJSON ¶
UnmarshalJSON restores locode from bytes after marshaling as JSON.
type LocodeList ¶
type LocodeList []Locode
LocodeList reperesents a list of locodes.
func (LocodeList) Bytes ¶
func (l LocodeList) Bytes() []byte
Bytes returns a serialized version of a locode list. First byte represents the length.
[N][locode1][locode2]...[locodeN]
func (*LocodeList) FromBytes ¶
func (l *LocodeList) FromBytes(b []byte) LocodeList
FromBytes constructs a new locode from bytes. First byte reperesents the length.
func (LocodeList) Range ¶
func (l LocodeList) Range(offset, limit int) LocodeList
Range returns a sliced variant of a locode list.
type Zip ¶
Zip represents a zip code.
func (Zip) MarshalJSON ¶
MarshalJSON represents a zip as a string while marshaling as JSON.
func (*Zip) UnmarshalJSON ¶
UnmarshalJSON restores zip code from bytes after marshaling as JSON.
type ZipList ¶
type ZipList []Zip
ZipList reperesents a list of zip codes.
func (ZipList) Bytes ¶
Bytes returns a serialized version of a zip list. First byte represents the length.
[N][zip1][zip2]...[zipN]
Directories ¶
Path | Synopsis |
---|---|
zipimport tool is suited for Bolt DB creation from a gzipped CSV with zip codes.
|
zipimport tool is suited for Bolt DB creation from a gzipped CSV with zip codes. |
zipsearch tool leverages the ziptools package and provides a simple cli interface for searching zip codes and cities.
|
zipsearch tool leverages the ziptools package and provides a simple cli interface for searching zip codes and cities. |