AV3 – GetSecondaryNumbers

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

GetSecondaryNumbers Outputs

SecondaryNumbersResponse

Typical Example Workflow

1. Validate address using GetBestMatches.
2. If DPV 3 or 4 returned:

Then, use GetSecondaryNumbers to retrieve potential unit numbers.

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

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