ziptools

package module
v0.0.0-...-e420dba Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 14, 2014 License: MIT Imports: 7 Imported by: 4

README

ziptools, zipimport, zipsearch

GoDoc

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

View Source 
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 CityList 

type CityList []string

CityList reperesents a list of cities.

func (CityList) Range 

func (c CityList) Range(offset, limit int) CityList

Range returns a sliced variant of a city list.

type DB 

type DB struct {
	// contains filtered or unexported fields
}

DB abstracts database access.

func Open 

func Open(path string) (db *DB, err error)

Open opens a Bolt database from a file if it exists.

func (*DB) Close 

func (d *DB) Close()

func (*DB) FindCities 

func (d *DB) FindCities(citypart string) (cities CityList, err error)

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) FindZips 

func (d *DB) FindZips(zippart string) (zips ZipList, err error)

Find all zip codes that match the given substring.

func (*DB) GetCity 

func (d *DB) GetCity(z Zip) (city string, err error)

GetCity gets a city that is assigned to the specified zip code. This methods looks for an exact match.

func (*DB) GetLocation 

func (d *DB) GetLocation(l Locode) (loc *Location, err error)

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.

func (*DB) GetZips 

func (d *DB) GetZips(city string) (zips ZipList, err error)

Get a list of zip codes in the specified city. This methods looks for an exact match.

type Location 

type Location struct {
	Name   string
	State  string
	Locode Locode
}

Location represents transport location.

func (Location) Bytes 

func (l Location) Bytes() []byte

Bytes returns a serialized version of a location.

func (*Location) FromBytes 

func (l *Location) FromBytes(b []byte) *Location

FromBytes constructs a new location from bytes.

type Locode 

type Locode [LocodeLen]byte

Locode represents a locode.

func NewLocode 

func NewLocode(str string) (code Locode)

NewLocode creates a new locode from string.

func (Locode) Bytes 

func (l Locode) Bytes() []byte

Bytes represents a locode as bytes.

func (Locode) MarshalJSON 

func (l Locode) MarshalJSON() ([]byte, error)

MarshalJSON represents a locode as a string while marshaling as JSON.

func (Locode) String 

func (l Locode) String() string

String represents a locode as a string.

func (*Locode) UnmarshalJSON 

func (l *Locode) UnmarshalJSON(b []byte) (err error)

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 

type Zip [ZipLen]byte

Zip represents a zip code.

func NewZip 

func NewZip(str string) (zip Zip)

NewZip creates a new zip code from string.

func (Zip) Bytes 

func (z Zip) Bytes() []byte

Bytes represents a zip as bytes.

func (Zip) MarshalJSON 

func (z Zip) MarshalJSON() ([]byte, error)

MarshalJSON represents a zip as a string while marshaling as JSON.

func (Zip) String 

func (z Zip) String() string

String represents a zip as a string.

func (*Zip) UnmarshalJSON 

func (z *Zip) UnmarshalJSON(b []byte) (err error)

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 

func (z ZipList) Bytes() []byte

Bytes returns a serialized version of a zip list. First byte represents the length. 

[N][zip1][zip2]...[zipN]

func (*ZipList) FromBytes 

func (z *ZipList) FromBytes(b []byte) ZipList

FromBytes constructs a new zip list from bytes. First byte reperesents the length.

func (ZipList) Range 

func (z ZipList) Range(offset, limit int) ZipList

Range returns a sliced variant of a zip list.

Source Files

View all Source files

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.