Returns parsed and validated address elements along with a list of potential secondary numbers for a given input address. The operation can be used with GetBestMatches to find secondary numbers for addresses missing or containing incorrect unit information.

URL Endpoints

Coding Resources

GitHub

 

 

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/address-validation/

GetSecondaryNumbers Outputs

SecondaryNumbersResponse

Name Type Values Description
Address1 String Varies Corrected address line 1.
City String Varies Corrected city name.
State String Varies Corrected state name.
ZIP String Varies Corrected zip + 4.
TotalCount String Varies Total number of secondary numbers found.
SecondaryNumbers String[] Varies List of secondary numbers.
Error Error Varies Object indicating service failure. See “Errors”.

Typical Example Workflow

  1. Validate address using GetBestMatches.
  2. If DPV 3 or 4 returned:
3 Apartment or box number invalid, but main address valid.
4 Valid mailing address, but missing unit number.

Then, use GetSecondaryNumbers to retrieve potential unit numbers.

Example: input address missing unit info for an office building.

Input field Value
Address 136 West Canon Perdido St
City Santa Barbara
State CA
PostalCode 93101

Example workflow in Python

import requests

API_KEY = 'YOUR_API_KEY_HERE'

# Step 1: Call GetBestMatches
def get_best_matches(address, city, state, zip_code):
    url = 'https://trial.serviceobjects.com/av3/api.svc/GetBestMatchesJson'
    params = {
        'Address': address,
        'City': city,
        'State': state,
        'PostalCode': zip_code,
        'LicenseKey': API_KEY
    }
    response = requests.get(url, params=params)
    return response.json()

# Step 2: Call GetSecondaryNumbers
def get_secondary_numbers(address, city, state, zip_code):
    url = 'https://trial.serviceobjects.com/av3/api.svc/GetSecondaryNumbersJson'
    params = {
        'Address': address,
        'City': city,
        'State': state,
        'PostalCode': zip_code,
        'LicenseKey': API_KEY
    }
    response = requests.get(url, params=params)
    return response.json()

# Input address
address = "136 West Canon Perdido St"
city = "Santa Barbara"
state = "CA"
zip_code = "93101"

# Step 1: Validate the address
best_match_result = get_best_matches(address, city, state, zip_code)

# Extract DPV code
try:
    match = best_match_result['BestMatches'][0]
    dpv_code = match['DPV']
    print(f"DPV Code: {dpv_code}")
    
    # Step 2: If DPV indicates missing (4) or incorrect (3) secondary number
    if dpv_code in ['3', '4']:
        print("Secondary number is missing or incorrect. Fetching possible secondary numbers...")
        secondary_numbers_result = get_secondary_numbers(address, city, state, zip_code)
        print("Possible secondary numbers:")
        for sec in secondary_numbers_result.get('SecondaryNumbers', []):
            print(f" - {sec}")
    else:
        print("Address is complete and valid.")
except (KeyError, IndexError) as e:
    print("Error parsing response:", e)

GetBestMatches JSON Response – DPV 4

{
  "Addresses": [
    {
      "Address1": "136 W Canon Perdido St",
      "Address2": "",
      "City": "Santa Barbara",
      "State": "CA",
      "Zip": "93101-3242",
      "IsResidential": "false",
      "DPV": "4",
      "DPVDesc": "The input record is a valid mailing address, but is missing the apartment or rural route box number",
      "DPVNotes": "11,22,24,26,39",
      "DPVNotesDesc": "Default ZIP+4 record used to certify the address,Address exists but mail is being returned,SuiteLink did not find Suite or Unit data to append to the address,The input address matched the ZIP+4 record,Highrise apartment/office building address",
      "Corrections": "",
      "CorrectionsDesc": "",
      "BarcodeDigits": "931013242997",
      "CarrierRoute": "C008",
      "CongressCode": "24",
      "CountyCode": "083",
      "CountyName": "Santa Barbara",
      "FragmentHouse": "136",
      "FragmentPreDir": "W",
      "FragmentStreet": "Canon Perdido",
      "FragmentSuffix": "St",
      "FragmentPostDir": "",
      "FragmentUnit": "",
      "Fragment": "",
      "FragmentPMBPrefix": "",
      "FragmentPMBNumber": ""
    }
  ],
  "IsCASS": true
}

GetSecondaryNumbers – 8 different suite options found

{
  "Address1": "136 W Canon Perdido St",
  "City": "Santa Barbara",
  "State": "CA",
  "Zip": "93101",
  "SecondaryNumbers": [
    "STE A",
    "STE B",
    "STE C",
    "STE D",
    "STE E",
    "STE B1",
    "STE B2",
    "STE D2"
  ],
  "TotalCount": 8
}

References