zipfetcher

README

zipfetcher

Is a Golang library for fetching USA ZIP codes and some data about them from an official source - The USPS postal service.

Allows you to check resource updates by date and receive data in the format of an array of ZipCode struct

type ZipCode struct {
    Code       string // 5 digits zip code
    State      string // two-letter state designation
    City       string // city name
    LocaleName string // useful for filtering out military zones
}

Usage examples

Running examples, both of them use USPS as a source:

• first way, used default provider

    zf := zipfetcher.Create()
	zips, err := zf.GetAllZips()
	if err != nil {
		// ...
	}
	fmt.Println(zips)

• second way, explicitly declare the provider

    zf := zipfetcher.Create(zipfetcher.WithProvider(zipfetcher.CreateUspsProvider()))
	zips, err := zf.GetAllZips()
	if err != nil {
		// ...
	}
	fmt.Println(zips)

A little about the USPS:

The USPS updates xls table approximately every month: https://postalpro.usps.com/ZIP_Locale_Detail . However, they don't provide explanation for data. The table contains 3 sheets with different column sets. None of them contains classification column. I guess the codes are allocated on the page as follows:

• "ZIP_DETAIL" sheet contains Standard and Post office box-only ZIPs
• "Unique_ZIP_DETAIL" - Unique ZIPs such as governmental agencies, universities, businesses, or buildings receiving sufficiently high volumes of mail and also Santa Claus code is here
• "Others" - Military and Post office box-only ZIPs

All sheets contain: ZIP code, state, city and locale name. For my purposes this is enough. I use locale name to identify Military codes (APO or DPO value).

Documentation

Index

• Variables
• func WithProvider(provider ZipProvider) func(*ZipFetcher)
• type UspsProvider
  • func CreateUspsProvider() *UspsProvider
  • func (usps *UspsProvider) GetLastModificationDate() (time.Time, error)
  • func (usps *UspsProvider) GetZips() ([]ZipCode, error)
• type ZipCode
• type ZipFetcher
  • func Create(provider ...func(*ZipFetcher)) *ZipFetcher
  • func (zf *ZipFetcher) CheckIfModifiedSince(date string) (bool, error)
  • func (zf *ZipFetcher) GetAllZips() ([]ZipCode, error)
  • func (zf *ZipFetcher) GetAllZipsIfModifiedSince(date string) ([]ZipCode, error)
• type ZipProvider

Variables

var CityColumn = map[string]int{
	"ZIP_DETAIL":        7,
	"Unique_ZIP_DETAIL": 7,
	"Other":             11,
}

CityColumn used to allocate which column in each page contains city

Pay attention military zones data don't contain real physical location

var LocaleNameColumn = map[string]int{
	"ZIP_DETAIL":        5,
	"Unique_ZIP_DETAIL": 5,
	"Other":             7,
}

LocaleNameColumn used to allocate which column in each page contains locale name

var StateColumn = map[string]int{
	"ZIP_DETAIL":        8,
	"Unique_ZIP_DETAIL": 8,
	"Other":             12,
}

StateColumn used to allocate which column in each page contains states Pay attention military zones data don't contain real physical location

var ZipColumn = map[string]int{
	"ZIP_DETAIL":        4,
	"Unique_ZIP_DETAIL": 4,
	"Other":             5,
}

ZipColumn used to allocate which column in each page contains zips

Functions

func WithProvider

func WithProvider(provider ZipProvider) func(*ZipFetcher)

Types

type UspsProvider

type UspsProvider struct {
	LastUpdateDate  time.Time
	LastRequestDate time.Time
	XlsPath         string
	// contains filtered or unexported fields
}

func CreateUspsProvider

func CreateUspsProvider() *UspsProvider

func (*UspsProvider) GetLastModificationDate

func (usps *UspsProvider) GetLastModificationDate() (time.Time, error)

func (*UspsProvider) GetZips

func (usps *UspsProvider) GetZips() ([]ZipCode, error)

type ZipCode

type ZipCode struct {
	Code       string // 5 digits zip Code
	State      string // two-letter State designation
	City       string
	LocaleName string // useful for identifying military
}

type ZipFetcher

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

func Create

func Create(provider ...func(*ZipFetcher)) *ZipFetcher

default provider - UspsProvider

func (*ZipFetcher) CheckIfModifiedSince

func (zf *ZipFetcher) CheckIfModifiedSince(date string) (bool, error)

CheckIfModifiedSince checking if data was modified after the date

date format: yyyy-mm-dd

func (*ZipFetcher) GetAllZips

func (zf *ZipFetcher) GetAllZips() ([]ZipCode, error)

GetAllZips return all zips

func (*ZipFetcher) GetAllZipsIfModifiedSince

func (zf *ZipFetcher) GetAllZipsIfModifiedSince(date string) ([]ZipCode, error)

GetAllZipsIfModifiedSince return all zips if data was modified after the date.

If not modified, would return empty list without error

type ZipProvider

type ZipProvider interface {
	GetLastModificationDate() (time.Time, error)
	GetZips() ([]ZipCode, error)
}