AD – FindAddress – Recommended

Returns parsed and validated address elements. This operation’s primary concern is to return an address to you if your input address fails. If your input address is valid, then the service is done and the validated and standardized address is returned. Additional data source results will not override the address found from your inputs. Any found addresses should match in some way to the input address.

If your address could not be found by USPS, we will use the additional clues like Phone and Name to try to return the “correct” address to you.

URL Endpoints

JSON:
- https://trial.serviceobjects.com/AD/api.svc/FindAddressJson?Address1={ADDRESS1}&Address2={ADDRESS2}&City={CITY}&State={STATE}&PostalCode={POSTALCODE}&BusinessName={BUSINESSNAME}&PhoneNumber={PHONENUMBER}&FullName={FULLNAME}&Firstname={FIRSTNAME}&LastName={LASTNAME}&LicenseKey={LICENSEKEY

XML:
- https://trial.serviceobjects.com/AD/api.svc/FindAddress?Address1={ADDRESS1}&Address2={ADDRESS2}&City={CITY}&State={STATE}&PostalCode={POSTALCODE}&BusinessName={BUSINESSNAME}&PhoneNumber={PHONENUMBER}&FullName={FULLNAME}&Firstname={FIRSTNAME}&LastName={LASTNAME}&LicenseKey={LICENSEKEY

FindAddress Inputs

Name	Type	Description
Address1	String	Address line of the address to validate. For example, “123 Main Street”.
Address2	String	This line is for address information that does not contribute to DPV coding an address. For example “C/O John Smith” does not help validate the address, but is still useful in delivery.
City	String	The city of the address to validate. For example, “New York”. The city isn’t required, but if one is not provided, the Zip code is required.
State	String	The state of the address to validate. For example, “NY”. This does not need to be contracted, full state names will work as well. The state isn’t required, but if one is not provided, the Zip code is required.
PostalCode	String	The zip code of the address to validate. A zip code isn’t required, but if one is not provided, the City and State are required.
BusinessName	String	If this is a business address, add the business name here. It can help with the identification of a proper address.
PhoneNumber	String	The phone number for the contact.
FullName	String	If you don’t have first and last names parsed separately, you can instead place the full name into this field for parsing.
FirstName	String	If you have first and last names separated, place the first name here.
LastName	String	If you have first and last names separated, place the last name here.
LicenseKey*	String	Your license key to use the service. Sign up for a free trial key at https://www.serviceobjects.com/address-detective/

FindAddress Outputs

Name	Type	Values	Description
Addresses	FixedAddress[]	Varies	The corrected address candidates.
Errors	String	Varies	Error object indicating why the service could not return a result. See “Errors” page for more information.

FixedAddress

Name

Type

Values

Description

Address

String

Varies

The corrected Address line 1.

City

String

Varies

The corrected city name.

State

String

Varies

The corrected state name.

Zip

String

Varies

The corrected zip code + 4.

DPV* ^[1] ^[2]

String

Varies

Number that correlates to a DPV(Delivery Point Validation) result. An indicator displaying whether
or not the address is recognized as deliverable by the USPS.

DPVDesc*

String

Varies

A description of the DPV number.

DPVNotes*

String

Varies

Number that correlates to DPV notes description. Service Objects may add or change Note
descriptions, but will never modify existing codes.

DPVNotesDesc*

String

Varies

Details about the DPV result. Service Objects may add or change Note descriptions, but will never
modify existing codes.

Corrections*

String

Varies

Number that correlates to a Corrections Description. Service Objects may add or change Correction
descriptions, but will never modify existing codes.

CorrectionsDesc*

String

Varies

Description of what was corrected in an address. Linked to the Corrections number. Service Objects
may add or change Correction descriptions, but will never modify existing codes.

Notes

String

Varies

Not currently used.

NotesDesc

String

Varies

Not currently used.

BarcodeDigits ^[3]

String

Varies

The post office delivery barcode digits.

Barcode Example: 931011445011

931011445	01	1
Zip+4	Deliver Point Code	Checksum Digit

CarrierRoute

String

Varies

4 chars: 1 for the route type, 3 for the route code. Identifies a group of addresses when prepended
by 5-digit Zip.

CongressCode

String

Varies

The congress code of the given address.

CountyCode

String

Varies

The county code of the given address.

CountyName

String

Varies

The name of the county in which the given address lies.

FragmentHouse

String

Varies

The parsed house number of the given address.

123 in 123 North Main St West Apt A

FragmentPreDir

String

Varies

The parsed pre-directional of the address's street.

North in 123 North Main St West Apt A

FragmentStreet

String

Varies

The parsed name of the street in the given address.

Main in 123 North Main St West Apt A

FragmentSuffix

String

Varies

The parsed suffix of the street in the given address.

St in 123 North Main St West Apt A

FragmentPostDir

String

Varies

The parsed post-directional of the address's street.

West in 123 North Main St West Apt A

FragmentUnit

String

Varies

The parsed unit type (e.g. “Apt” or “Ste”)

Fragment

String

Varies

The parsed “Fragment” box, apartment or unit number. Same as FragmentPMBNumber.

FragmentPMBPrefix

String

Varies

The parsed type of the apartment, box, unit, etc.

Apt in 123 North Main St West Apt A

FragmentPMBNumber

String

Varies

The parsed apartment, box, unit, etc. number of the given address.

A in 123 North Main St West Apt A

*See section on DPV, DPV Notes and Corrections for possible values/descriptions

References

1.CASS and DPV: A Higher Standard for Address Accuracy

2.Delivery Point Validation Explained

3.Address Deduplication Using USPS Barcodes