The findAddress method provides address suggestions based on partial input, such as a street name, postal code, and country. It uses external validation sources to return a list of potential matches, allowing users to select the correct address and enhance data quality.

Method Signature

Method name: findAddress

global AddressFindOutput_v1 findAddress(AddressFindInput_v1 addressFind)

Parameters

Output

The AddressFindOutput_v1 object serves as the main container for address search results, holding a List<AddressFindOutputItem_v1> that contains individual address suggestions. Each AddressFindOutputItem_v1 represents a single suggested address, including key details such as address, description, and a container value, which can be used for further refinement via the Retrieve API.

Apex Example

This Apex example searches for address suggestions based on a partial input, retrieves possible matches, and logs the suggested addresses for further selection or refinement.

// Initialize the Record Validation API
recordval.RecordValidationAPI_v1 api = new recordval.RecordValidationAPI_v1();
System.debug('Record Validation API initialized.');

// Create the AddressFindInput object
recordval.AddressFindInput_v1 input = new recordval.AddressFindInput_v1();
input.address = 'Jansbuitensingel 6';  // Partial input
input.country = 'NL';          // Country for the search (optional)
input.note = 'Testing the Find API';  // Optional note for tracking
input.container = ''; // Optional: Retrieve sub-addresses in a container
System.debug('Address Find Input prepared: ' + input);

// Execute the findAddress method
recordval.AddressFindOutput_v1 output;
try {
    output = api.findAddress(input);
    System.debug('Address suggestions retrieved successfully.');
} catch (Exception e) {
    System.debug('Error during address suggestion: ' + e.getMessage());
    return;
}

// Log the suggestions
if (output.suggestions != null && !output.suggestions.isEmpty()) {
    System.debug('Address Suggestions:');
    for (recordval.AddressFindOutputItem_v1 suggestion : output.suggestions) {
        System.debug('Suggested Address: ' + suggestion);
    }
} else {
    System.debug('No suggestions returned.');
}

Find & Retrieve logic

the Find and Retrieve APIs collaborate to refine and validate address data. When a user inputs partial address information, the Find API returns a list of suggestions, each with a type and a container ID. If a suggestion’s type is "Address", the associated container ID can be used in the Retrieve API to obtain the full, validated address details. For suggestions where the type is not "Address" (e.g., "Street" or "Building"), the container ID should be used in a subsequent Find API call to drill down further and retrieve more specific address suggestions within that broader location. This iterative process continues until a complete address is identified, at which point the Retrieve API can be used to validate and enrich the address data.