Processing Model

Initialize the engine from a configuration, submit records in the structure your configuration expects, and read structured results back — optionally across multiple threads.

Engine lifecycle

Whatever language you use, the flow is the same. You create an engine instance from a configuration, use it to process records, and release it when done:

  1. Initialize — construct the engine with your configuration. This loads reference data and allocates resources, so it's done once and reused, not per record.
  2. Process — submit one or more records and receive structured results.
  3. Shut down — release the engine to free its resources.
Note: Because initialization is relatively expensive and processing is cheap, initialize once and process many records against the same engine instance.

Input types

The engine accepts three shapes of input. Your records must match the input style declared in the configuration you started the engine with:

  • Discrete — each address component is supplied in its own field (primary number, street name, city, state, ZIP, and so on).
  • Multiline — the address is supplied as free-form lines, as it might appear on a label.
  • Hybrid — a mix of discrete components and free-form lines.
Important: Input structure and configuration must agree. If you initialized the engine for multiline input, submit multiline records — not discrete component fields.

Single & multi-record

You can process a single record at a time or submit records in batches, and results come back as structured JSON or XML (per your Data_Format setting). The shipped output examples include both single- and multi-record forms, and each output example enumerates the complete set of possible fields the engine can return.

See Output & Result Codes for how to interpret what comes back.

Threading

The engine is built to support multi-threaded processing for throughput. Your application implements the actual threading; the configuration's Initial_Thread_Count and Max_Threads settings tell the engine how many threads' worth of internal resources to allocate up front and at most.

  • Use the thread-aware interface provided for your language (for example, a dedicated threading type in the C++, Java, or .NET binding) rather than sharing a single non-thread-aware instance across threads.
  • Size the thread counts to your hardware; as with any engine, adding threads yields diminishing returns past the point your CPU and I/O can sustain.
Note: The exact threading classes and calling conventions differ by language and are documented in the language-specific HTML documentation that ships with the SDK.
PreviousConfigurationNext Output & Result Codes