| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
The Location Resolver takes a free text address and returns the business location at that address, along with an explanation of how the result was reached.
Required fields
The request payload must include the following element:
address: a free text address, at any level of formatting.
Everything else is optional.
Optional fields
Either of the following can be supplied to identify a specific company at the address:
| Field | Description |
|---|---|
company_name | The name of the company you expect to operate at the address. Matched on how closely it resembles the name on record. |
company_id | The Veridion ID of the company you expect to operate at the address. Matched exactly. |
Supplying bothIf both
company_idandcompany_nameare present,company_idtakes precedence, because a Veridion ID is unambiguous.
Example request body:
{
"address": "1521 S. Arlington St., Ohio",
"company_name": "Wendy's"
}
Supplying a company where you have oneA company name or ID is optional, but it changes what the API can do for you. Without one, an address that resolves to a multi tenant building returns the building and its occupant count, because no single business can be isolated. With one, the same address can return the specific business you asked about.
Supplying a company also lets the API search a wider area for it, which improves the chance of finding the right site when the input address resolves slightly off or is rather inaccurate. See How the API resolves an address for details.
Accepted input
The address must identify a place of business or its immediate surroundings:
- a precise building or unit;
- a full street address;
- a road level reference, such as a named street or an intersection;
- a facility access point, such as a gate or an entrance.
Rejected input
Three kinds of input are rejected with a 400 Bad Request, rather than resolved at low confidence.
An address that points only at a broad area, because it cannot identify a place of business. This includes a city or town, a district or neighborhood, a broad postal or ZIP area, and a state, region, or country.
A place or facility name, such as a park, an airport, a landmark, a venue, a port, or a mine. The API resolves addresses, not names. A business inside a large site is reached through its own street address, not through the name of the site it sits in.
Input that cannot be interpreted as an address at all.
Broad areas are rejected even with a companyA broad area input is rejected whether or not a company name or ID is supplied. Finding a company within a city, region, or broad postal area is a search problem: you have criteria rather than a place. The Location Resolver takes a place and tells you what operates there.
If you have an area and a set of criteria, use the Search API.
Successful responses
When the request is successful, a standard 200 OK HTTP status will be sent along with the expected JSON. The response will include the following fields:
resolution: an object holding the outcome, a plain language summary, the confidence score, the signals behind the match, and a reference to anything identified but not returned inline.result: the resolved location, ornullwhen no location is returned.
A 200 OK does not mean a business was found. It means the input was valid and the API reached a conclusion, which may be that the address resolves to a shared building, to a registered address, or to nothing on record.
| Outcome | result | What it means |
|---|---|---|
single_location | the location, or null | One business was isolated. null when you supplied a company and this is not it, in which case a reference to the business is provided instead. |
shared_building | null | Several businesses were found and none could be isolated. A building reference and occupant count are provided. |
registered_address_only | null | No operating business was found, and the address is recognized as a registered company address. |
unresolved | null | Nothing matched. |
Analyzing the responseFor how to read the outcome, the confidence score, and the signals, and how to combine them into filtering criteria, see the How to analyze a result section.
For a comprehensive list of all data points returned, see the Response fields and types page.
Error responses
If the request is unsuccessful, the API will return one of the below HTTP status responses:
400 Bad Request, if the payload is missing the requiredaddressfield, or if the address falls into one of the rejected input categories.- other standard HTTP error responses, detailed in the Response codes section.
For a rejected address, the message field identifies which case applies:
| Case | Message |
|---|---|
| Too broad | The address is too broad to resolve. Provide at least a street-level address (e.g. '12 Market St, Chicago' rather than 'Chicago'). |
| Place or facility name | Place and facility names are not supported. Provide a street address rather than a name. |
| Uninterpretable | The input could not be interpreted as an address. |
Any error response follows a specific structure. Please see the Error response format section for more details.