Returns parsed and validated address elements including Delivery Point Validation (DPV), Residential Delivery Indicator (RDI), and Suite data. GetBestMatches will attempt to validate the input address against a CASS approved engine, and make corrections where possible. Multiple address candidates may be returned if a definitive decision cannot be made by the service.


URL Endpoints


JSON


https://trial.serviceobjects.com/AV3/api.svc/GetBestMatchesJson?BusinessName={BUSINESSNAME}&Address={ADDRESS}&Address2={ADDRESS2}&City={CITY}&State={STATE}&PostalCode={POSTALCODE}&LicenseKey={LICENSEKEY}

XML

https://trial.serviceobjects.com/AV3/api.svc/GetBestMatches?BusinessName={BUSINESSNAME}&Address={ADDRESS}&Address2={ADDRESS2}&City={CITY}&State={STATE}&PostalCode={POSTALCODE}&LicenseKey={LICENSEKEY}


GetBestMatches Inputs


Name

Type

Description

BusinessName

String

Name of business associated with this address. Used to append Suite data.

Address

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.

LicenseKey*

String

Your license key to use the service.  
Sign up for a free trial key at https://www.serviceobjects.com/products/address-geocoding/usps-address-validation


GetBestMatches Outputs


BestMatchesResponse

Name

Type

Values

Description

Addresses

Address[]

Varies

The corrected address candidates.

IsCASS

String

"true" or "false"

Indicates if the unaltered input address is CASS certified. See “What is CASS?” below for more information.

Error

Error

Varies

Error object indicating why the service could not return a result. See “Errors” below for more information.


Address

Name

Type

Values

Description

Address1

String

Varies

The corrected address line 1.

Address2

String

Varies

The corrected address line 2.

City

String

Varies

The corrected city name.

State

String

Varies

The corrected state name.

Zip

String

Varies

The corrected zip code + 4.

IsResidential

String

“true” or “false”

Indicates if the address is for a residence.

String

1-4

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

Explains DPV result.

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. Service Objects may add or change Correction descriptions, but will never modify existing codes.

String

Varies


<button class="accordion">The post office delivery barcode digits.</button>
<div class="panel">
  <p><b>Barcode Example: 931011445011</b>
<table>
<thead>
<tr class="row-1 odd">
	<th class="column-1">931011445</th><th class="column-2">01</th><th class="column-3">1</th>
</tr>
</thead>
<tbody class="row-hover">
<tr class="row-2 even">
	<td class="column-1">Zip+4</td><td class="column-2">Deliver Point Code </td><td class="column-3">Checksum Digit </td>
</tr>
</tbody>
</table>
&nbsp;
&nbsp;
</div>


CarrierRoute

String

4 chars

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 is the congressional district number.

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


<button class="accordion">The parsed house number of the given address.</button>
<div class="panel">
  <br />
  <p><b>123</b> in <b>123</b> North Main St West Apt A</p>
  <br />
</div>


FragmentPreDir

String

Varies


<button class="accordion">The parsed pre-directional of the address's street.</button>
<div class="panel">
  <br />
  <p><b>North</b> in 123 <b>North</b> Main St West Apt A</p>
  <br />
</div>


FragmentStreet

String

Varies


<button class="accordion">The parsed name of the street in the given address.</button>
<div class="panel">
  <br />
  <p><b>Main</b> in 123 North <b>Main</b> St West Apt A</p>
  <br />
</div>


FragmentSuffix

String

Varies


<button class="accordion">The parsed suffix of the street in the given address.</button>
<div class="panel">
  <br />
  <p><b>St</b> in 123 North Main <b>St</b> West Apt A</p>
  <br />
</div>


FragmentPostDir

String

Varies


<button class="accordion">The parsed post-directional of the address's street.</button>
<div class="panel">
  <br />
  <p><b>West</b> in 123 North Main St <b>West</b> Apt A</p>
  <br />
</div>


FragmentUnit

String

Varies

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

Fragment

String

Varies

The parsed "Fragment" box, apartment or unit number.

FragmentPMBPrefix

String

Varies


<button class="accordion">The parsed type of the apartment, box, unit, etc.</button>
<div class="panel">
  <br />
  <p><b>Apt</b> in 123 North Main St West <b>Apt</b> A</p>
  <br />
</div>


FragmentPMBNumber

String

Varies


<button class="accordion">The parsed apartment, box, unit, etc. number of the given address.</button>
<div class="panel">
  <br />
  <p><b>A</b> in 123 North Main St West Apt <b>A</b></p>
  <br />
</div>



References

<style>
.accordion {
  background-color: #f7f7f7 !important;
  color: #444 !important;
  cursor: pointer !important;
  padding: 18px !important;
  border: none !important;
  width: 100%;
  text-align: left !important;
  outline: none !important;
  font-size: 15px !important;
  transition: 0.4s !important ;
}

.active, .accordion:hover {
  background-color: #efefef !important; 
}

.panel {
  padding: 0 18px  !important;
  display: none ;
  background-color: white !important;
  border: none !important;
  overflow: hidden  !important;
}


.accordion:after {
  content: '\02795'; /* Unicode character for "plus" sign (+) */
  font-size: 13px ;
  color: #777 ;
  float: right ;
  margin-left: 5px;
}

.active:after {
  content: "\2796" ; /* Unicode character for "minus" sign (-) */
}

</style>
<script>

var acc = document.getElementsByClassName("accordion");
var i;

for (i = 0; i < acc.length; i++) {
  acc[i].addEventListener("click", function() {
    this.classList.toggle("active");
    var panel = this.nextElementSibling;
    if (panel.style.display === "block") {
      panel.style.display = "none";
    } else {
      panel.style.display = "block";
    }
  });
}
</script>