Page tree
Skip to end of metadata
Go to start of metadata



Returns parsed and validated address elements along with a list of potential secondary numbers for a given input address. The operation can be leveraged in conjunction with the GetBestMatches operation to find secondary numbers for input data that has either missing or incorrect unit information. For an example workflow please see the Workflow section below.


URL Endpoints


JSON

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

XML

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

GetSecondaryNumbers Inputs


Name

Type

Description

Address

String

Address line of the address to validate.  
For example, "123 Main Street".

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


GetSecondaryNumbers Outputs


SecondaryNumbersResponse

Name

Type

Values

Description

Address1

String

Varies

The corrected address line 1.

City

String

Varies

The corrected city name.

StateStringVariesThe corrected state name.
ZipStringVariesThe corrected zip code + 4.
TotalCountStringVariesThe total number of secondary numbers found for the input address.
SecondaryNumbersString[]VariesA list of possible secondary numbers for the input address.

Error

Error

Varies

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


Typical Example Workflow


1) Validate an address using the recommended GetBestMatches operation.

2) If GetBestMatches returns a DPV 3 or 4:

3

The apartment or rural route box number is not valid, although the house number or rural route is valid

4

The input record is a valid mailing address, but is missing the apartment or rural route box number

3) Get a list of potential secondary numbers using the GetSecondaryNumbers operation.


The example below helps to illustrate how GetBestMatches and GetSecondaryNumbers tie together. The input "Address" field is missing the unit information for the office building.


Input FieldValue
Address27 E Cota St
CitySanta Barbara
StateCA
PostalCode93101


GetBestMatches XML Response - DPV 4 - The input record is a valid mailing address, but missing the apartment or rural route box number

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

<BestMatchesResponse xmlns="http://www.serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Addresses>
<Address>
<Address1>27 E Cota St</Address1>
<Address2/>
<City>Santa Barbara</City>
<State>CA</State>
<Zip>93101-7603</Zip>
<IsResidential>false</IsResidential>
<DPV>4</DPV>
<DPVDesc>The input record is a valid mailing address, but is missing the apartment or rural route box number</DPVDesc>
<DPVNotes>11,22,26,39</DPVNotes>
<DPVNotesDesc>
Default ZIP+4 record used to certify the address,Address exists but mail is being returned,The input address matched the ZIP+4 record,Highrise apartment/office building address
</DPVNotesDesc>
<Corrections/>
<CorrectionsDesc/>
<BarcodeDigits>931017603992</BarcodeDigits>
<CarrierRoute>C006</CarrierRoute>
<CongressCode>24</CongressCode>
<CountyCode>083</CountyCode>
<CountyName>Santa Barbara</CountyName>
<FragmentHouse>27</FragmentHouse>
<FragmentPreDir>E</FragmentPreDir>
<FragmentStreet>Cota</FragmentStreet>
<FragmentSuffix>St</FragmentSuffix>
<FragmentPostDir/>
<FragmentUnit/>
<Fragment/>
<FragmentPMBPrefix/>
<FragmentPMBNumber/>
</Address>
</Addresses>
<IsCASS>true</IsCASS>
</BestMatchesResponse>


GetSecondaryNumbers - 9 different suite options found

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

<SecondaryNumbersResponse xmlns="http://www.serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Address1>27 E Cota St</Address1>
<City>Santa Barbara</City>
<State>CA</State>
<Zip>93101</Zip>
<SecondaryNumbers>
<string>STE 100</string>
<string>STE 101</string>
<string>STE 200</string>
<string>STE 201</string>
<string>STE 401</string>
<string>STE 500</string>
<string>STE 501</string>
<string>STE 502</string>
<string>STE 503</string>
</SecondaryNumbers>
<TotalCount>9</TotalCount>
</SecondaryNumbersResponse>


References


  • No labels