usps

Documentation

Index

• Variables
• type Address
  • func (address *Address) FromGeoValues(geoValues api.GeocodeValues)
  • func (address *Address) ToResult(geoValues api.GeocodeValues) (result api.GeocodeResult)
• type AddressValidateRequest
  • func (r AddressValidateRequest) ToXMLString() string
• type AddressValidateResponse
• type ErrUSPSSystem
  • func (e ErrUSPSSystem) Error() string
• type Error
• type ErrorResponse
• type Geocoder
  • func (g Geocoder) Validate(geoValues api.GeocodeValues) (api.GeocodeResults, error)

Variables

var (
	// Endpoint is that base address for the USPS API
	Endpoint = "https://secure.shippingapis.com/ShippingAPI.dll"

	// VerifyAPI is the name of that API that handles address verifications
	VerifyAPI = "Verify"

	// ErrorCodes contains USPS code mapping to eApp error codes
	ErrorCodes = map[string]string{
		"-2147219400":     "error.geocode.city",
		"-2147219401":     "error.geocode.notfound",
		"-2147219403":     "error.geocode.multiple",
		"Generic":         "error.geocode.generic",
		"Default Address": "error.geocode.defaultAddress",
		"Partial":         "error.geocode.partial",
		"System":          "error.geocode.system",
		"80040B19":        "error.geocode.system.xml",
	}
)

Types

type Address

type Address struct {
	// XMLName refers to the name to give the XML tag
	XMLName xml.Name `xml:"Address"`
	// Up to 5 address verifications can be included per transaction.
	// <Address ID="0"></Address><Address ID="1"></Address>
	ID int64 `xml:"ID,attr"`

	// Maximum characters allowed: 38
	FirmName string `xml:"FirmName,omitempty"`

	// Address Line 1 is used to provide an apartment or suite number, if applicable.  Maximum characters allowed: 38
	Address1 string `xml:"Address1"`

	// Street address. Maximum characters allowed: 38
	Address2 string `xml:"Address2"`

	// Maximum characters allowed: 15.  Either <City> and <State> or <Zip5> are required.
	City string `xml:"City"`

	// Maximum characters allowed: 2. Either <City> and <State> or <Zip5> are required.
	State string `xml:"State"`

	// Maximum characters allowed: 28. For Puerto Rico addresses only.
	Urbanization string `xml:"Urbanization"`

	// Maximum characters allowed: 5. Either <City> and <State> or <Zip5> are required.
	Zip5 string `xml:"Zip5"`

	// Input tag exactly as presented, not all caps.  Maximum characters allowed:
	Zip4 string `xml:"Zip4"`

	// Stores error information for an address. USPS returns errors within the address block if they
	// exist. We set this to a pointer so that we can check for <nil>
	Error *Error `xml:"Error"`

	// Stores additional information that is not necessarily an error. Some instances may include where an apartment
	// number used does not correspond to a valid base address
	ReturnText string `xml:"ReturnText,omitempty"`
}

Address represents the structure for the <Address> element information in a USPS request and response. With a successful response, the following is returned

<Address>
  <Address2></Address2>
  <City></City>
  <State></State>
  <Zip5></Zip5>
  <Zip4></Zip4>
</Address>

When there's an error with the address information, the <Error> block is nested within the <Address /> element like the following <AddressValidateResponse>

<Address>
    <Error>
        <Number>-2147219401</Number>
        <Source>clsAMS</Source>
        <Description>Address Not Found.  </Description>
        <HelpFile/>
        <HelpContext/>
    </Error>
</Address>

</AddressValidateResponse>

Therefore, we include an Error field in the Address struct. We make it a pointer so that we can check for <nil> if the value is not populated (no error has occurred).

func (*Address) FromGeoValues

func (address *Address) FromGeoValues(geoValues api.GeocodeValues)

FromGeoValues populates a Address using Values

func (*Address) ToResult

func (address *Address) ToResult(geoValues api.GeocodeValues) (result api.GeocodeResult)

ToResult generates a Result struct and determines whether it is a partial match. A partial match occurs when there's a mismatch in values between each corresponding field

type AddressValidateRequest

type AddressValidateRequest struct {
	XMLName xml.Name `xml:"AddressValidateRequest"`
	UserID  string   `xml:"USERID,attr"`
	Address Address
}

AddressValidateRequest contains the information necessary to execute an address validation webservice request The USERID refers to the api key that must be sent with each request

func (AddressValidateRequest) ToXMLString

func (r AddressValidateRequest) ToXMLString() string

ToXMLString creates a string representation of the xml request

type AddressValidateResponse

type AddressValidateResponse struct {
	XMLName xml.Name `xml:"AddressValidateResponse"`
	Address Address  `xml:"Address"`
}

AddressValidateResponse contains the information returned from a successful webservice request

type ErrUSPSSystem

type ErrUSPSSystem struct {
	Message string
}

ErrUSPSSystem is the expected structure of the USPS system.

func (ErrUSPSSystem) Error

func (e ErrUSPSSystem) Error() string

Error returns the USPS error message.

type Error

type Error struct {
	// The error number generated by the Web Tools server.
	Number string `xml:"Number"`

	// The component and interface that generated the error on the Web Tools server.
	Source string `xml:"Source"`

	// The error description
	Description string `xml:"Description"`

	// [reserved for future use according to USPS docs]
	HelpFile string `xml:"HelpFile"`

	// [reserved for future use according to USPS docs]
	HelpContext string `xml:"HelpContext"`
}

Error is the structure for responses resulting in an error

type ErrorResponse

type ErrorResponse struct {
	XMLName xml.Name `xml:"Error"`
	Error
}

ErrorResponse stores a system level error

type Geocoder

type Geocoder struct {
	Env api.Settings
	Log api.LogService
}

Geocoder geocodes address information using the United States Post Office webservice API docs can be found https://www.usps.com/business/web-tools-apis/address-information-api.htm

func (Geocoder) Validate

func (g Geocoder) Validate(geoValues api.GeocodeValues) (api.GeocodeResults, error)

Validate takes values to be geocoded and executes a web service call