Primary API reference

Pseudocode example of Pro API

This section provides an overview of how a program using the Pro API works on a conceptual level. The pseudocode used is programming language independent.

The example below uses many of the Pro API functions, so that you can see how they work together. In practice, however, you might not want or need to use every function.

The pseudocode does not include all the available functions.

Six functions are described in the pseudocode. The main function starts an instance of the API, and gives the user a choice of performing a Singleline or Typedown search. It then frees resources after each result has been retrieved. Each search recursively calls five further functions: Display Error, which retrieves and displays the message associated with the returned error code; User Action, which displays prompts (commonly an instruction as to what should be entered by the user); Display results, which retrieves picklists of results from the search; SelectResults, which allows the user to step into picklist items; and ReturnAddress, which formats and returns the final address, using the rules specified in the active layout. These functions are:

The primary API is instance based, where each instance is referenced with a handle. To create a new instance of the API, the function QA_Open must be called and the unique handle that it returns must be used with subsequent API calls. If multiple instances of the API are required, such as for use with multithreading, then QA_Open needs to be called multiple times.

Open an instance of the API [QA_Open]

As with all API calls, the open could fail for various reasons. The most common reasons for this to occur are that the product is not installed or configured properly. If open fails, address matching will not be available. When writing integrations of the primary API, it will be useful to enable logging.

For brevity in the pseudocode we will leave out the error checking for each API function call. However, in an integration all API calls should check the error returned.

If open failed
    Call Display error
    close API instance [QA_Close]
    shutdown API [QA_Shutdown]
    exit procedure
End If

Once an open has been performed, the settings that are going to be used should be applied to the instance. The user may or may not be able to control which dataset and search engine to use. Both of these should be set before searching begins. The active dataset and search engine can be changed between searches if required.

set active dataset to search upon [QA_SetActiveData]
set engine to use for searching [QA_SetEngine]

The layout to be used for formatting will need to be set, although this defaults to an internal layout that will be valid but probably not suitable. It is wise to set the active dataset before choosing the layout to use with formatting, as some layouts may only be defined for individual data sets.

Any engine options, such as search timeout or picklist thresholds should also be set at this point if the default values are not desired.

set layout to use for formatting [QA_SetActiveLayout]
set engine options [QA_SetEngineOption]

The recommended method for handling searching with the API is to recursively display any picklist results, and then to allow the user to either search upon the results further, or to step into a result until the user has the address they require. Formatting can then be applied, and the address returned.

Repeat

The results should be displayed before the search is performed, as there may be some information returned to the user by the API before searching. This is commonly done by the Typedown search engine.

Call Display results

There are two essential requests that a user can make that need to be handled. The first is giving some text to search upon. The second is to select an item to either step into or format. Other actions can be coded at the integrator's discretion, such as stepping out of a result to go back, or to exit the address searching.

Call User action
If action was search text
    search with text [QA_Search]
Else If action was to select an item
    Call Select Result
End If

Until user has obtained address

After a search has been completed, it is essential to call the end search function before starting another in the instance.

end the search [QA_EndSearch]

Once all address searching has been performed with the instance, the instance should be closed.

close the instance [QA_Close]

If no more instances are required, the API needs to be shutdown, which will close all instances anyway.

shutdown the API [QA_Shutdown]

Almost every primary API function call returns an error code which should be checked. If an error occurs then the method associated with the returned error code can be retrieved and displayed to the user.

retrieve error message [QA_ErrorMessage]
display error message to user
Return to calling function

In order to aid the user when they are interacting with the integration, the Primary API can return prompts to display to the user. These will commonly be an instruction of what should be entered, such as 'Enter postcode or place' when using the Typedown engine at the beginning of a search. The prompt should be displayed to the user in some manner before requesting input.

In order to aid the user when they are interacting with the integration, the Primary API can 'return' (codes) prompts to 'display' (typed) to the user. These will commonly be an instruction of what should be entered, such as Enter postcode or place when using the Typedown engine at the beginning of a search. The prompt should be displayed to the user in some manner before requesting input.

retrieve prompt text [QA_GetPrompt]
display prompt to user
obtain action from user
Return to calling function

To display results, first obtain a count of the available results and then retrieve and display each one. The integration may choose to display different types of results in different ways. For example, it is common to indicate to the user which results can be stepped into, or which results are full addresses that will be used if selected.

get a count of available [QA_GetSearchStatus]
For Each result
    retrieve the result [QA_GetResult]
    display the result to the user
End For
Return to calling function

When a user selects a result the action that the integration should take is determined by the attributes associated with the result in question. The two most important attributes are whether the result can be stepped into, and whether it is a final address. Other result attributes may be handled at the integrator's discretion.

get the attributes of the result [QA_GetResult]
If result can be stepped into
    step into result [QA_StepIn]
Else If result is a final address
    Call Return address
End If
Return to calling function

When a user has selected a final address, it should be formatted and returned in the appropriate manner. The address will be formatted using the rules specified in the active layout.

format result and retrieve line count [QA_FormatResult]
For Each formatted line
    retrieve the line text [QA_GetFormattedLine]
    return text to the user
End For
Return to calling function

Handling errors

Every Primary API function except for QA_Shutdown returns an integer error code value. This value will be within the following ranges:

Value Description
0 Function succeeded
less than 0 Function encountered errors

Experian strongly recommends that every function call is checked for errors. Although the majority of errors are generated by mistakes in an integration which would be picked up through testing, some are unpredictable. For example, the failure of a client-server link, running out of memory, or a data file expiry.

All Primary API functions will set their output parameters to defined values if an error occurs. Integer output variables will be set to zero, and string output variables will be set to blank.

The LogErrors configuration setting is a useful way of locating the cause of an error. Experian recommends that you enable error logging while writing and debugging an integration.

The QA_ErrorMessage function provides a textual description of error codes returned from the API.

The handling of errors should typically be split into two categories. These are described below.

  1. An error returned from a call to QA_Open. This means that address capture is unavailable.

    This could be caused by many things, such as configuration or administration errors. Experian recommends that you call QA_Shutdown and locate the source of the problem using the LogErrors setting.

  2. An error returned from a call to QA_Open because, although address capture is available, the current search has failed for some reason. This could be due to a lack of resources, or to an administration error. Experian recommends that you call QA_EndSearch to end the current search.

    Note that you do not have to shut down the system, and that address capture may still be available. For example a client-server link may have failed, losing the current search. In that case attempting a new search would reestablish the connection and your integration would continue functioning correctly.

If you are writing a client-server integration of Pro, it is very important to react to errors after QA_Open as described above. An error will be returned from an API function if a connection to the server in use is lost, as the search results will not be retrievable.

API instances

The Primary API is based on the concept of instances. An instance of the API is created through calling QA_Open, and is destroyed by calling QA_Close. Once an instance is created, it is referenced through an integer handle that is returned from QA_Open. All subsequent functions that use the instance must be passed through this handle. Once all instances have been closed using QA_Close, the API should be shut down using QA_Shutdown.

Each instance of the API that is created is independent from other instances. Any action that is performed upon one instance will not affect the state of another instance. Actions can be performed upon separate instances simultaneously.

If you want to have a multithreading integration that performs multiple searches concurrently, you should create multiple instances of the API. Each thread will typically perform the following actions:

  • Create an instance using QA_Open
  • Perform one or more searches
  • Close the instance using QA_Close

Once all threads have finished, call QA_Shutdown.

Flags returned

Many API functions, such as QA_GetSearchStatus, pass information back using 'flags'.

Flags are a means of communicating multiple pieces of information back to the caller using a single parameter.

The value returned consists of multiple values ORed together.

QA_GetResult returns information about a picklist item. If a picklist item is informational and can be stepped into, the following flags are returned:

qaresult_CANSTEP                    4
qaresult_INFORMATION               1024

The value of rlFlags will be:

4 OR 1024 = 1028

To check for a specific flag the integrator should AND the returned set of flags with the flag they wish to test for. If the result is zero, the flag was not present. If the result is non-zero, the flag was present.

Testing for qaresult_CANSTEP (4) in returned value 1028:
1028 AND 4 = 4 (non-zero)
Therefore the picklist item can be stepped into.

Testing for qaresult_ALIASMATCH (8) in returned value 1028:
1028 AND 8 = 0 (zero)
Therefore the picklist item is not an alias match.

In C:

if (rlFlags & 1024)
{
...
}

In VB:

If (rlFlags And 1024) Then
    ...
EndIf

Some functions have accompanying 'Detail' functions; for example, QA_GetResult has the accompanying function QA_GetResultDetail. These allow the caller to inquire about a single specific attribute and is useful for languages that cannot perform bitwise operations such as AND, or for integration that require extra information.

If rsDetail or rlDetail are not used in a particular call to a 'Detail' function, it will return a blank string or zero as appropriate.

Example:

QA_GetResultDetail        ( iHandle,
                             iResult,
                             qaresultint_ISINFORMATION,
                             &lDetail,
                             NULL,
                             0 );

This will return qavalue_True or qavalue_False in parameter lDetail, depending on whether the given picklist item is informational or not.

Automatic stepping and formatting

To help you locate addresses faster and more effectively, the Primary API supports automatic stepping into and formatting of picklist items generated from an initial search. For example, if you were to perform a search that generated only a single exact result, the integration can automatically step into that item instead of prompting you to do it manually, which speeds up the address capture process.

Automatic stepping in and formatting is not required for a successful integration, and it is therefore at your discretion whether you act upon the returned flags.

The Primary API will output one of the following four flags from the function QA_GetSearchStatus.

The flag qastate_AUTOSTEPINSAFE is returned when a search or step in has produced a picklist containing only one match that itself can be stepped into. Experian recommends that the integration should call QA_StepIn upon the first item in the picklist when this flag is returned, as it will speed up the address capture process.

The flag qastate_AUTOSTEPINPASTCLOSE is returned when a search or step in has produced a picklist containing only one exact match, and also multiple non-exact matches. You may choose to call QA_StepIn on the first item in the picklist when this flag is returned, as it may speed up the address capture process.

The flag qastate_AUTOFORMATSAFE is returned when a search or step in has produced a picklist containing only a single match that is a final address item. If the integration allows you to go back to the picklist after selecting a final address, then Experian recommend that QA_FormatResult should be called upon the first picklist item and the address returned.

The flag qastate_AUTOFORMATPASTCLOSE is returned when a search or a step in has produced a picklist containing only one exact match that is a final address item, and also multiple non-exact matches. If the integration allows you to go back to the picklist after selecting a final address, then you can choose to call QA_FormatResult on the first item in the picklist and on the address returned.

Asynchronous searching

The Primary API supports two different threading models for performing searches: synchronous and asynchronous.

Synchronous searching is the default threading model, and is used by the majority of integrations. Using synchronous searching, the function QA_Search and/or QA_StepIn return to the caller once the search has been completed. You can then immediately access the results.

Asynchronous searching is an alternative threading model where the calls to the searching functions are returned as soon as the search has begun. The search is performed using a background thread.

There are three engine options that control asynchronous searching:

  1. The qaengopt_ASYNCSEARCH engine option allows the integrator to control whether an initial search using QA_Search on the Singleline engine is asynchronous. This is the most commonly used option for asynchronous searching.
  2. The qaengopt_ASYNCSTEPIN engine option allows the integrator to control whether stepping into picklist items using QA_StepIn is asynchronous.
  3. The qaengopt_ASYNCREFINE engine option allows the integrator to control whether picklist refinement using QA_Search after the first result for the Singleline engine, and all searches using the Typedown engine, are asynchronous. This will be used less frequently, as picklist refinement is a fast process.

The search must be complete before you can retrieve the results. The caller needs to check periodically whether the search has been completed by calling QA_GetSearchStatus, and checking whether the flag qastate_STILLSEARCHING is present. Typically, you should check every 100ms to see whether the search has completed.

The following diagram demonstrates polling:

Polling example

Asynchronous searching is useful, although not essential, for graphical user interface integrations where the caller wants to be able to perform tasks while the search is in progress, and does not want to use multithreaded code. For example, this could be used to react to search cancel requests.