zipcodes

README

zipcodes - Zip Code Lookups

A Zipcode lookup package that uses the GeoNames Postal Code dataset from http://www.geonames.org . You can initialize it with a Postal Code dataset downloaded from http://download.geonames.org/export/zip .

Install

Install with

go get github.com/TerraTech/zipcodes/v2

Initialize Struct

Initializes a zipcodes struct. It will throw an error if:

• The file does not exist / wrong format.
• Some of the lines contain less that 12 elements (in the readme.txt of each postal code dataset, they define up to 12 elements).
• Where latitude / longitude value are contains a wrong format (string that can not be converted to float64).

zipcodesDataset, err := zipcodes.New("path/to/my/dataset.txt")

-OR-

zipcodesDataset, err := zipcodes.LoadDataset("path/to/my/dataset.txt")

Initialize Struct by specific ISO Country Code

Initializes a zipcodes struct. It will throw an error if:

• The file does not exist / wrong format.
• Some of the lines contain less that 12 elements (in the readme.txt of each postal code dataset, they define up to 12 elements).
• Where latitude / longitude value are contains a wrong format (string that can not be converted to float64).

zipcodesDataset, err := zipcodes.LoadDatasetByCountry("path/to/my/dataset.txt", "US")

Lookup

Looks for a zipcode inside the map interface we loaded. If the object can not be found by the zipcode, it will return an error. When a object is found, returns its zipcode, place name, administrative name, latitude and longitude:

location, err := zipcodesDataset.Lookup("10395")

DistanceInKm

Returns the line of sight distance between two zipcodes in kilometers:

zlA, err := zipcodesDataset.Lookup("01945")
...
zlB, err := zipcodesDataset.Lookup("03058")
...
distance := zipcodesDataset.DistanceInKm(zlA, zlB) // 49.87

DistanceInMiles

Returns the line of sight distance between two zipcodes in miles:

zlA, err := zipcodesDataset.Lookup("01945")
...
zlB, err := zipcodesDataset.Lookup("03058")
...
distance := zipcodesDataset.DistanceInMiles(zlA, zlB) // 30.98

DistanceInKmToZipCode

Calculates the distance between a zipcode and a give lat/lon in Kilometers:

zl, err := zipcodesDataset.Lookup("01945")
...
distance := zipcodesDataset.DistanceInKmToZipCode(zl, 51.4267, 13.9333) // 1.11

DistanceInMilToZipCode

Calculates the distance between a zipcode and a give lat/lon in Miles:

zl, err := zipcodesDataset.Lookup("01945")
...
distance := zipcodesDataset.DistanceInMilToZipCode(zl, 51.4267, 13.9333) // 0.69

GetZipcodesWithinKmRadius

Returns a list of zipcodes within the radius of this zipcode in Kilometers:

zl, err := zipcodesDataset.Lookup("01945")
...
zipcodes := zipcodesDataset.GetZipcodesWithinKmRadius(zl, 50) // ["03058"]

GetZipcodesWithinMlRadius

Returns a list of zipcodes within the radius of this zipcode in Miles:

zl, err := zipcodesDataset.Lookup("01945")
...
zipcodes := zipcodesDataset.GetZipcodesWithinMlRadius(zl, 50) // ["03058"]

Documentation

Overview

zipcodes is a package that uses the GeoNames Postal Code dataset from http://www.geonames.org in order to perform zipcode lookup operations

Index

• Variables
• func DistanceBetweenPoints(latitude1, longitude1, latitude2, longitude2, radius float64) float64
• func IsMulti(zipcodeLocations ZipCodeLocations) bool
• type ZipCodeLocation
• type ZipCodeLocations
  • func (zcl ZipCodeLocations) IsMulti() bool
• type Zipcodes
  • func LoadDataset(datasetPath string) (Zipcodes, error)
  • func LoadDatasetByCountry(datasetPath, country string) (Zipcodes, error)
  • func New(datasetPath string) (Zipcodes, error)
  • func NewByCountry(datasetPath, country string) (Zipcodes, error)
  • func (zc Zipcodes) CalculateDistance(zipcodeLocationA, zipcodeLocationB ZipCodeLocation, radius float64) float64
  • func (zc Zipcodes) DistanceInKm(zipcodeLocationA ZipCodeLocation, zipcodeLocationB ZipCodeLocation) float64
  • func (zc Zipcodes) DistanceInKmToZipCode(zipcodeLocation ZipCodeLocation, latitude, longitude float64) float64
  • func (zc Zipcodes) DistanceInMilToZipCode(zipcodeLocation ZipCodeLocation, latitude, longitude float64) float64
  • func (zc Zipcodes) DistanceInMiles(zipcodeLocationA, zipcodeLocationB ZipCodeLocation) float64
  • func (zc Zipcodes) FindZipcodesWithinRadius(zipcodeLocation ZipCodeLocation, maxRadius, earthRadius float64) []string
  • func (zc Zipcodes) GetZipcodesWithinKmRadius(zipcodeLocation ZipCodeLocation, radius float64) []string
  • func (zc Zipcodes) GetZipcodesWithinMlRadius(zipcodeLocation ZipCodeLocation, radius float64) []string
  • func (zc Zipcodes) Lookup(zipCode string) (ZipCodeLocations, error)

Variables

var (
	ErrMultipleLatLon  = errors.New("zipcode has multiple lat/lon coordinates")
	ErrZipcodeNotFound = errors.New("zipcode not found")
)

Functions

func DistanceBetweenPoints

func DistanceBetweenPoints(latitude1, longitude1, latitude2, longitude2, radius float64) float64

DistanceBetweenPoints returns the distance between two lat/lon points using the Haversine distance formula.

func IsMulti

func IsMulti(zipcodeLocations ZipCodeLocations) bool

IsMulti returns if there are multiple lat/lon coordinates for a zipcode

Types

type ZipCodeLocation

type ZipCodeLocation struct {
	ZipCode   string
	PlaceName string
	AdminName string
	Lat       float64
	Lon       float64
	StateCode string
}

ZipCodeLocation struct represents each line of the dataset

type ZipCodeLocations

type ZipCodeLocations []ZipCodeLocation

ZipCodeLocations slice represents a zipcode with multiple lat/lon coordinates

func (ZipCodeLocations) IsMulti

func (zcl ZipCodeLocations) IsMulti() bool

IsMulti returns if there are multiple lat/lon coordinates for a zipcode

type Zipcodes

type Zipcodes struct {
	DatasetList map[string]ZipCodeLocations
}

Zipcodes contains the whole list of structs representing the zipcode dataset

func LoadDataset

func LoadDataset(datasetPath string) (Zipcodes, error)

LoadDataset reads and loads the dataset into a map interface

func LoadDatasetByCountry

func LoadDatasetByCountry(datasetPath, country string) (Zipcodes, error)

LoadDatasetByCountry reads and loads the dataset into a map interface filtered by ISO Country Code

func New

func New(datasetPath string) (Zipcodes, error)

New loads the dataset and returns a struct that contains the dataset as a map interface

func NewByCountry

func NewByCountry(datasetPath, country string) (Zipcodes, error)

NewByCountry loads the dataset, filtered by country, and returns a struct that contains the dataset as a map interface

func (Zipcodes) CalculateDistance

func (zc Zipcodes) CalculateDistance(zipcodeLocationA, zipcodeLocationB ZipCodeLocation, radius float64) float64

CalculateDistance returns the line of sight distance between two zipcode locations in Kilometers

func (Zipcodes) DistanceInKm

func (zc Zipcodes) DistanceInKm(zipcodeLocationA ZipCodeLocation, zipcodeLocationB ZipCodeLocation) float64

DistanceInKm returns the line of sight distance between two zipcode locations in Kilometers

func (Zipcodes) DistanceInKmToZipCode

func (zc Zipcodes) DistanceInKmToZipCode(zipcodeLocation ZipCodeLocation, latitude, longitude float64) float64

DistanceInKmToZipcode calculates the distance between a zipcode and a give lat/lon in Kilometers

func (Zipcodes) DistanceInMilToZipCode

func (zc Zipcodes) DistanceInMilToZipCode(zipcodeLocation ZipCodeLocation, latitude, longitude float64) float64

DistanceInMilToZipcode calculates the distance between a zipcode and a give lat/lon in Miles

func (Zipcodes) DistanceInMiles

func (zc Zipcodes) DistanceInMiles(zipcodeLocationA, zipcodeLocationB ZipCodeLocation) float64

DistanceInMiles returns the line of sight distance between two zipcode locations in Miles

func (Zipcodes) FindZipcodesWithinRadius

func (zc Zipcodes) FindZipcodesWithinRadius(zipcodeLocation ZipCodeLocation, maxRadius, earthRadius float64) []string

FindZipcodesWithinRadius finds zipcodes within a given radius

func (Zipcodes) GetZipcodesWithinKmRadius

func (zc Zipcodes) GetZipcodesWithinKmRadius(zipcodeLocation ZipCodeLocation, radius float64) []string

GetZipcodesWithinKmRadius get all zipcodes within the radius of this zipcode

func (Zipcodes) GetZipcodesWithinMlRadius

func (zc Zipcodes) GetZipcodesWithinMlRadius(zipcodeLocation ZipCodeLocation, radius float64) []string

GetZipcodesWithinMlRadius get all zipcodes within the radius of this zipcode

func (Zipcodes) Lookup

func (zc Zipcodes) Lookup(zipCode string) (ZipCodeLocations, error)

Lookup looks for a zipcode inside the map interface