How to analyze a result

Every response from the Location Resolver explains itself. Each result provides an outcome (outcome), a plain language summary (summary), a confidence score (confidence_score), the signals behind the match (signals), and a linked reference to anything identified but not returned inline (linked_reference).

This section will guide you on how to use these attributes effectively to filter and refine the results according to your specific requirements.

Each response contains two objects:

resolution: what the API found, how confident it is, and the signals behind the match.
result: the resolved location, when one is returned. It is null otherwise.

Outcome

The outcome field reports what kind of place the address resolved to.

📖
The outcome reports what was established at the address, not whether your company matched
outcome answers a single question: what was the API able to establish about business presence at this address? Whether it isolated one business, found several without being able to isolate one, found only a registration signal, or found nothing at all.
Whether the company you supplied was found is reported separately, by operator_match. Whether the location is returned inline is reported by result. This is why an outcome of single_location can arrive with result: null: one business operates at the address, but it is not the company you asked about.

Outcome	Meaning	`result`
`single_location`	One business location was isolated at the address.	Returned, unless you supplied a company and this is not it.
`shared_building`	Several business locations were found at the address, and no single one could be isolated.	`null`
`registered_address_only`	No operating business was found, but the address is recognized as a company's registered address.	`null`
`unresolved`	The input was precise enough to attempt resolution, but nothing matched.	`null`

Summary

The summary field is a short, plain language sentence describing the outcome, written to be shown directly to an end user. It is drawn from a fixed set, determined by the outcome and by whether a supplied company was found, and it points to the follow up call where one is available.

Outcome	Company match	Summary
`single_location`	matched, or none supplied	A single business was identified at the requested address.
`single_location`	`no_match`	A business was identified at the requested address, but it does not match the requested company. Use `linked_reference.location_id` to retrieve it.
`shared_building`	none supplied	The requested address resolves to a building with multiple businesses; no single location could be identified. Use `linked_reference.building_id` to list the occupants.
`shared_building`	`no_match`	The requested company was not found among the business locations at this building. Use `linked_reference.building_id` to list the occupants.
`registered_address_only`	any	This appears to be a registered legal address, not an operating location. The resolver reports operational presence only, and we couldn't find any on record here.
`unresolved`	any	No business location or building was found at or near the requested address.

Confidence score

The confidence_score attribute is a numerical value ranging from 0 to 1, which indicates how well the API matched the input you supplied. A score closer to 1 indicates a higher level of confidence in the match.

The input consists of the address, together with the company name or ID when one is provided. Two factors are considered:

How well the address matched a place

Both the precision of the input and the way the resolved point related to the matched place contribute here. An input that pinned an exact building and landed inside that building's footprint is the strongest case. An input that resolved only to a street, and was matched to a nearby building by proximity, scores lower, because the search covered a wider area and the place is less tightly pinned.

For a registered address result, this factor reflects how strongly the input matched the registered address on record instead.

How well the company matched

This factor applies only when a company name or ID was supplied. A Veridion company ID is matched exactly. A company name is scored on how closely it resembles the name on record, so exact names are strongest, close variants score slightly lower, and a name matched only through a secondary source, such as a linked online profile rather than the legal or operating name, is reduced further.

A company that was not found at the address contributes nothing to the score. Results where the company was not found will therefore always score lower than a confirmed match at the same address.

What the score does and does not tell you

A high score does not mean a business was found. With no company supplied, the score reflects the address alone, so a perfectly matched address can score 1.0 and still return result: null, because it resolved to a shared building or to a registered address. Use confidence_score to judge the match, and outcome to decide whether the answer is useful.

With a company supplied, the score tracks the outcome. Any result that depends on the company not being found will score in the lower part of the range, however well the address itself was matched. This is intended: you asked for a specific business and did not get it. It does mean the score stops being a pure measure of address quality once a company is in the request.

One number will not tell you what went wrong. A precise address with the wrong company, and a rough address with the right one, can land in the same range from opposite directions. The signals are where that breakdown lives.

The score is present for every resolution except unresolved, for which it is null.

👍
Tip
By using the confidence_score, you can establish a threshold to filter out results that do not meet your desired level of confidence.
For example, setting a min_confidence_score parameter of 0.6 will exclude any result with a lower overall confidence score.

Signals

The signals object breaks the score down into the individual judgements behind it. Where confidence_score tells you how good the match was overall, the signals tell you what made it good or weak.

Field	Description	Possible values
`signals.location.precision`	How precisely the input address landed.	`exact_building`, `street_address`, `road_level`
`signals.location.spatial_match`	How the resolved point related to the matched place.	`inside_footprint`, `near_footprint`, `nearest_location`, `null`
`signals.location.distance_m`	Distance in meters from the resolved point to the matched place.	`0`, any positive number, `null`
`signals.operator_match`	Whether a supplied company was found operating at the resolved place.	`company_id`, `company_name`, `no_match`, `null`

Each is described in full below.

Location precision

signals.location.precision reports how precisely the input address landed, before any matching took place.

Value	Meaning
`exact_building`	The input pinned a specific premises, suite, or unit.
`street_address`	The input was a full street address, with a street and a number.
`road_level`	The input was a named street, an intersection, or a facility access point such as a gate or an entrance.

Spatial match

signals.location.spatial_match reports how the resolved point related to the place that was matched.

Value	Meaning
`inside_footprint`	The point fell within a building's outline. The place is contained rather than merely nearby, which is the strongest spatial match.
`near_footprint`	The point fell outside any outline, and the nearest building in range was matched instead.
`nearest_location`	No building was involved, and the nearest business location in range was matched by its coordinates.
`null`	Nothing was matched spatially.

Distance

signals.location.distance_m reports the distance in meters from the resolved point to the matched place. It is 0 for a contained match, positive for a proximity match, and null when nothing was matched spatially.

👍
Reading distance in context
Because the search area adapts to how built up the surrounding area is, the same distance means different things in different places. 400 m in a city center means the API looked well past many closer options. 400 m in a rural area may mean it was the only candidate that existed.
See Resolution methodology for how the search area is determined.

Company match

signals.operator_match reports whether the company you supplied, as either company_name or company_id, was found operating at the resolved place. The operator is the business that runs the site, which is what the API resolves to.

Value	Meaning
`company_id`	Matched on the supplied Veridion company ID.
`company_name`	Matched on the supplied company name.
`no_match`	A company was supplied, but no business at the resolved place matched it.
`null`	No company was supplied.

📘
Why a company might not match
A no_match does not necessarily mean the company is unrelated to the address. It can arise when:

the company is registered at the address but operates elsewhere, a common pattern at mail drop, virtual office, and self storage addresses;

the company does operate there, but the data does not yet link it to the place, or the supplied name is too far from the name on record to be matched with confidence;

the address resolves to a shared building where the specific unit could not be isolated, and none of the known occupants matches the company.

In all three cases the API still reports what is genuinely at the address, so you can see what is there and decide for yourself.

Linked reference

When the API identifies something it does not return inline, linked_reference gives you the ID needed to retrieve it in a follow up call.

Value	When it appears
`{ location_id }`	A business location was identified but withheld, because you supplied a company and this is not it. Retrieve it with the location by ID endpoint.
`{ building_id, occupant_count }`	The address resolved to a shared building and no company was supplied in the input, or the supplied company did not many any of the building's tenants. Retrieve the full list of businesses with the building locations endpoint.
`null`	Nothing was withheld. Either the location is in `result`, or there was nothing to return.

Reading a response

The three axes are independent, and reading them together is what makes a result actionable.

You want	Filter on
Only confirmed companies	`outcome` is `single_location` and `operator_match` is `company_id` or `company_name`
Only results anchored to a building you can trust	`spatial_match` is `inside_footprint`
Only results you can act on without a follow up call	`result` is not `null`
Everything at a site, including co-occupants	Take the building ID and call the building locations endpoint. It is available either from `linked_reference.building_id` on a `shared_building` result, or from `result.building.building_id` when a location was returned
Results above a quality bar	`confidence_score`, or the `min_confidence_score` parameter on the request

👍
Tip
Combining the outcome, the confidence score, and the signals lets you build filtering criteria tailored to your workflow.
For instance, a match on a company name variant may be acceptable when the point fell inside the building's footprint, but not when it was reached by proximity several hundred meters away.