this toolkit is offline, and the datasets are mostly acquired from U.S. government, all data is compiled into the library.
because of this design choice, almost all functions end up executing in <100 nano seconds. run the benchmarks yourself to see what I mean.
at this time, there is no methodology for updating the datasets, and they are bound to become out of date, and may be incomplete.
this should be used for ultra-fast assessment potentially pending further online data queries.
package main
import "github.com/yunginnanet/usps"
func main() {
entries, _ := usps.LookupCityAreaCodes("CHICAGO")
for _, entry := range entries {
println(entry.City)
println(entry.Code)
println(entry.State)
println(entry.Country)
println(entry.Latitude, entry.Longitude)
}
}EAST CHICAGO
219
INDIANA
US
+4.163920e+001 -8.745476e+001
WEST CHICAGO
312
ILLINOIS
US
+4.188475e+001 -8.820396e+001
WEST CHICAGO
331
ILLINOIS
US
+4.188475e+001 -8.820396e+001
WEST CHICAGO
630
ILLINOIS
US
+4.188475e+001 -8.820396e+001
WEST CHICAGO
773
ILLINOIS
US
+4.188475e+001 -8.820396e+001
CHICAGO HEIGHTS
708
ILLINOIS
US
+4.150615e+001 -8.763560e+001
NORTH CHICAGO
224
ILLINOIS
US
+4.232558e+001 -8.784118e+001
NORTH CHICAGO
847
ILLINOIS
US
+4.232558e+001 -8.784118e+001
const AreaCodeLength = 3func ExtractZipCodesFromString(s string) ([]string, bool)func GetAreaCodeInt(number string) intGetAreaCodeInt returns the area code of the given phone number or string as an int. If invalid, returns 0.
func GetCityZipStrings(city string) []stringGetCityZipStrings returns a slice of zip codes in string form associated with a city when given a city in string form. Data is loaded from the USPS dataset on first call and cached in memory.
func GetStateZipStrings(state string) []stringGetStateZipStrings returns a slice of zip codes in string form associated with a state when given a state in string form. Data is loaded from the USPS dataset on first call and cached in memory.
func InitAreaCodes()func InitStates()func InitZipCodes()func LongHand(short string) stringfunc PhoneNumberAreaCode(number string) stringPhoneNumberAreaCode returns the area code of the given phone number. This function will return an empty string if the number is invalid or isn't a known USA area code.
func PhoneNumberCity(number string) stringfunc PhoneNumberState(number string) stringPhoneNumberState returns the state that the given phone number is in. This is probably the most useful function in this package, and the one you're looking for. This function will return an empty string if the number is invalid.
func ShortHand(long string) stringfunc StateListLong() []stringfunc StateListShort() []stringfunc StateToShort(long string) stringtype AreaCode struct {
Code, State, City, Country string
Latitude, Longitude float64
}AreaCode is a struct representing an area code.
func LookupAreaCode(code string) ([]*AreaCode, bool)LookupAreaCode returns a slice of AreaCode types that match the given area code.
func LookupCityAreaCodes(city string) ([]*AreaCode, bool)LookupCityAreaCodes returns a slice of AreaCode types that match the given city. Note! This is not a perfect match. If a city is not found, it will attempt to find a city that contains the query..
func LookupStateAreaCodes(state string) ([]*AreaCode, bool)LookupStateAreaCodes returns a slice of AreaCode types that match the given state.
type GeoPoint2D struct {
Lon float64 `json:"lon"`
Lat float64 `json:"lat"`
}type State struct {
State string `json:"state"`
Abbrev string `json:"abbrev"`
Short string `json:"code"`
}func StateByLong(long string) Statefunc StateByShort(short string) Statefunc StateList() []Statetype ZipCode struct {
ZipCode string `json:"zip_code"`
City string `json:"usps_city"`
StateShort string `json:"stusps_code"`
State string `json:"ste_name"`
Zcta string `json:"zcta"`
ParentZcta interface{} `json:"parent_zcta,omitempty"`
Population float64 `json:"population,omitempty"`
Density float64 `json:"density,omitempty"`
PrimaryCotyCode string `json:"primary_coty_code,omitempty"`
PrimaryCotyName string `json:"primary_coty_name,omitempty"`
CountyWeights string `json:"county_weights,omitempty"`
CotyNames []string `json:"coty_name,omitempty"`
CtyCodes []string `json:"cty_code,omitempty"`
Imprecise string `json:"imprecise"`
Military string `json:"military"`
Timezone string `json:"timezone"`
GeoPoint2D GeoPoint2D `json:"geo_point_2d,omitempty"`
}ZipCode is a struct representing a zipcode, this is based on the USPS dataset.
func GetCityZips(city string) []*ZipCodeGetCityZips returns a slice of pointers to ZipCode structs associated with a city when given a city in string form. Data is loaded from the USPS dataset on first call and cached in memory.
func GetStateZips(state string) []*ZipCodeGetStateZips returns a slice of pointers to ZipCode structs associated with a state when given a state in string form. Data is loaded from the USPS dataset on first call and cached in memory.
func GetZipCode(zip string) (*ZipCode, bool)GetZipCode returns a pointer to a ZipCode struct when given a zip code in string form. Data is loaded from the USPS dataset on first call and cached in memory.
func LookupAllZipCodesInString(s string) ([]*ZipCode, bool)func ZipExtract(data string) []*ZipCodeZipExtract is just an adapter for LookupAllZipCodesInString to not break things, this was a duplicate function
func (z *ZipCode) Bytes() []bytefunc (z *ZipCode) MustMarshalJSON() []bytefunc (z *ZipCode) Pretty() []bytefunc (z *ZipCode) String() string