Oracle Integration Cloud Usage Guide

This guide covers using the GBG Loqate Reach and GBG Loqate Verify adapters inside an Oracle Integration flow: adding the action, mapping data into it, and working with what comes back. If you have not installed an adapter and created a connection yet, start with the Integration Guide.

Adding the Verify address action

Both adapters expose a single action, Verify address, and both are invoke only. You call them from inside a flow. Neither adapter can start an integration.

Open an integration

Open or create an integration. Any style works, including app driven, scheduled, and event driven.

Add the connection

Drag your Loqate connection onto the flow at the point where you want the address verified.

Name the endpoint

Give the endpoint a name and click Continue.

Select the action

Select the Verify address action and click Continue, then Finish.

Map the request

Open the mapper for the new invoke and map your source fields onto the request.

Request

Both adapters accept the same two fields.

Field	Type	Required	Notes
`address`	String	Yes	The address to verify. A single line containing the whole address is acceptable, and is usually the easiest thing to map
`country`	String	Yes	ISO 3166-1 alpha-2 country code, for example `GB`, `US`, `MY`. Map it on every call, see the warning below

Always map country. Neither adapter works it out from the address. Leave it unmapped and GBG Loqate Reach raises a Verification service error (502) fault, while GBG Loqate Verify returns a normal response with an empty verified address, no AVC and no match quality. The Verify case raises no fault, so it is easy to mistake for success.

You do not need to split the address into components before calling. Loqate parses the input itself, so mapping a concatenated address line, or a single free text field captured from a form, works well.

{
  "address": "1600 Amphitheatre Parkway, Mountain View, CA 94043",
  "country": "US"
}

Response: GBG Loqate Reach

Field	Type	Description
`verified_address`	String	The cleaned, standardised address as a single line
`confidence`	Number	Confidence score from 0.0 to 1.0
`recommendation`	String	The policy-aware decision to branch on: `accept`, `review`, or `reject`
`match_level`	String	How precisely the address matched. One of `premise`, `delivery_point`, `thoroughfare`, `locality`, `admin_area`, `country`, `none`
`avc`	String	The full Loqate Address Verification Code
`fields`	Object	Standardised address components

{
  "verified_address": "1600 Amphitheatre Pkwy, Mountain View CA 94043-1351",
  "confidence": 0.97,
  "recommendation": "accept",
  "match_level": "premise",
  "avc": "V44-I44-P7-100",
  "fields": {
    "address1": "1600 Amphitheatre Pkwy",
    "locality": "Mountain View",
    "administrative_area": "CA",
    "postal_code": "94043-1351",
    "premise": "1600",
    "thoroughfare": "Amphitheatre Pkwy",
    "country": "US",
    "country_name": "United States"
  }
}

Response: GBG Loqate Verify

Field	Type	Description
`verified_address`	String	The cleaned, standardised address as a single line
`avc`	String	The full Loqate Address Verification Code
`match_quality`	String	The Loqate Address Quality Index
`fields`	Object	Standardised address components

Verify does not return confidence, recommendation, or match_level. If your flow needs a decision rather than raw codes, use the Reach adapter instead, or derive your own rules from the AVC.

Address components

Both adapters return the same fields object. Loqate fills in components that were missing from the input when the reference data supplies them, so expect fields you did not send. In the example above, the request had no country_name or ZIP+4, but the response has both. A component is returned empty only when it does not apply to that country or the reference data cannot supply it.

Field	Description
`address1`	First address line
`address2`	Second address line
`premise`	House or building number
`thoroughfare`	Street name
`locality`	City or town
`sub_administrative_area`	County or sub region
`administrative_area`	State or province
`postal_code`	Postal or ZIP code
`country`	ISO 3166-1 alpha-2 country code
`country_name`	Full country name

Neither adapter returns geographic coordinates. If you need latitude and longitude, use the Loqate geocoding services directly. See Address Verify.

Reading the AVC

Every verification returns an Address Verification Code, which is far more informative than a simple pass or fail. The leading letter is the verification status.

Status	Meaning
`V`	Verified. A complete match against a single reference record
`P`	Partially verified. A partial match against a single reference record
`A`	Ambiguous. More than one close reference match was found
`R`	Reverted. Could not be verified to the minimum acceptable level
`U`	Unverified. Unable to verify

In V44-I44-P7-100:

V is the verification status (Verified).
44 are the post-processed and pre-processed match levels, from 0 for none up to 5 for delivery point. 4 is premise.
I44 is the parsing status, followed by the lexicon and context identification match levels.
P7 is the postcode status. P7 means the primary postal code was verified and the secondary postal code was added or changed. Here, Loqate verified 94043 and added the ZIP+4 suffix 1351.
100 is the matchscore, from 0 to 100, indicating how much the input had to change. 100 means no changes were needed.

The full breakdown is in the Address Verification Code reference.

Branching on the recommendation

The most common pattern with the Reach adapter is a switch immediately after the invoke, routing on recommendation.

Recommendation	Suggested handling
`accept`	Write the verified address back to your system and continue
`review`	Route to a manual review queue, or present the corrected address to the user for confirmation
`reject`	Stop and ask for re-entry, or record the failure and continue depending on how critical the address is

Because the thresholds behind these values come from the policy set on the connection, you can make a flow stricter or more forgiving without touching the integration itself. If you need two different levels of strictness in the same instance, create two connections with different policies and use whichever the flow requires.

Write verified_address and the fields components back to the source record, rather than keeping the original input. That is what gives you the standardisation benefit. An address that verifies but is never written back leaves the poor quality data in place.

Error handling

Both adapters convert Loqate service conditions into faults that Oracle Integration can catch, so you can handle them in a scope with a fault handler rather than inspecting response codes yourself.

GBG Loqate Reach

Fault	Raised when
Unauthorized (401)	The Loqate API key is missing or was rejected
Invalid request (400)	The request to the verification service was malformed
Verification service error (502)	The upstream Loqate service returned an unexpected error

GBG Loqate Verify

Fault	Raised when
Unauthorized (401)	The Loqate API key is missing or was rejected
No match (404)	The address could not be verified against reference data
Verification service error (502)	The Loqate Verify service returned an unexpected error

The two adapters treat an unverifiable address differently. Verify raises a No match (404) fault, so an address that cannot be verified is an exception your flow must catch. Reach returns a normal response carrying a reject recommendation, so the same address flows through as data rather than as a fault. Design your error handling accordingly: with Reach you branch, with Verify you catch.

Throughput

Each Verify address call verifies one address. To process many addresses in a single integration run, loop over your collection and call the action per record, keeping the usual Oracle Integration considerations in mind for large loops. For bulk cleansing of large datasets, calling the Loqate batch API directly is more efficient than looping inside an integration, since it verifies many addresses per request.

Troubleshooting

Symptom	Likely cause	Resolution
Adapter missing from the Adapters list after installing	Catalogue cache not refreshed	Wait, or have an administrator force a catalogue refresh
ICS-18541 during installation	A privately registered adapter already uses the same identifier	Remove the private registration, then install from the Store
Connection test fails immediately	Endpoint unreachable from the instance, or endpoint URL edited	Restore the default endpoint and confirm outbound access to the host
Unauthorized (401) at runtime, though the test passed	Key revoked, expired, or out of entitlement since the test	Confirm the key is still valid and has remaining entitlement
Every address returns `reject` or a `U` status AVC	Wrong country code, so the address is matched against another country’s reference data	Check the value being mapped into `country`
Verification service error (502) on every GBG Loqate Reach call	`country` is not mapped	Map `country`. Reach rejects a request without it
GBG Loqate Verify returns a blank address and no AVC, with no fault	`country` is not mapped	Map `country`. Without it the Verify service returns an empty match
Components come back empty but the address verified	The country’s reference data does not populate that component	Compare against the AVC match level rather than assuming a fault
No match (404) faults on addresses you expect to verify	New build, unusual format, or genuinely unverifiable input	Confirm with the same address through the Loqate API directly to isolate the adapter from the data

Support

For questions about the adapters or the Loqate service, email LoqateSupport@gbgplc.com. Both adapters are published by GB Group plc.

​Adding the Verify address action

​Request

​Response: GBG Loqate Reach

​Response: GBG Loqate Verify

​Address components

​Reading the AVC

​Branching on the recommendation

​Error handling

​GBG Loqate Reach

​GBG Loqate Verify

​Throughput

​Troubleshooting

​Support

Adding the Verify address action

Request

Response: GBG Loqate Reach

Response: GBG Loqate Verify

Address components

Reading the AVC

Branching on the recommendation

Error handling

GBG Loqate Reach

GBG Loqate Verify

Throughput

Troubleshooting

Support