Lookup calculations

When you use a Smarty API, your usage is measured in lookups. In most cases, a lookup is tied to the amount of address data an API processes. But depending on the API, lookup usage isn't always calculated the same way.

It also helps to understand the difference between a request and a lookup:

• An API request is a single call sent from your application to a Smarty API.
• An address lookup is the unit used to measure usage for billing and plan limits.

In most cases, one API request equates to one lookup.

Sometimes a single request can contain multiple addresses, which may result in consuming multiple lookups.

And in a few cases, lookup usage is based on what the API returns rather than the request itself.

To make this easier to understand, Smarty APIs fall into two groups:

• Standard lookup calculations: The simplest lookup model, where each address processed counts as 1 lookup. Smarty's APIs in this category are:
  • International Postcode API
  • International Street Address API
  • US Street Address API
  • US Reverse Geocoding API
  • US ZIP Code API
• Specialized lookup calculations: The lookup model varies depending on what you're asking the API to do and the output it returns.
  • US Address Autocomplete Pro API
  • International Address Autocomplete API
  • US Address Enrichment API
  • US Extract API

Standard lookup calculation

If you send 1 address, that uses 1 lookup. If you send 10 addresses, that uses 10 lookups.

A single API POST request can contain multiple addresses, but each submitted address still counts as its own lookup.

Specialized lookup calculation

The APIs below count lookups differently because of how they're designed to work. We'll go into detail and provide examples to help clarify how lookups are calculated for non-standard lookup calculations.

US Address Autocomplete Pro API

The US Address Autocomplete Pro API follows the standard rule that each completed API request counts as 1 lookup.

However, this API's default implementation is set to send requests as a user types. It's calculated to send one request per keystroke. That means one search session can generate multiple requests before the user finishes entering an address.

For example, in a default implementation, the US Address Autocomplete Pro API sends one request per keystroke; so a user typing "123 Main" would trigger 8 requests. In that case, 8 lookups would be used.

The total number of lookups depends on how frequently your implementation is configured to send requests.

International Address Autocomplete API

The International Address Autocomplete API works differently from its US counterpart.

Your implementation may send multiple API requests while the user types and the API displays suggestions. However, lookups are only counted when a final selected address is submitted.

*A final entry could be an entire address, but in the case of addresses with secondary indicators, a user may need to select a container for secondaries before a final address is selected. If users select a container for secondaries, lookups are not consumed until a secondary from the expanded list is selected.

Essentially, each selected address uses 1 lookup.

That means typing and viewing suggestions may involve multiple API calls, but no lookups are consumed from your account balance until the user chooses an address.

US Extract API

The US Extract API calculates lookups based on the number of addresses it detects and checks in the user-submitted text.

The number of lookups used matches the address_count value in the API response.

Each detected address counts as 1 lookup. If no address is found, no lookups are consumed. If multiple addresses are detected, the number of addresses detected will equal the number of address lookups consumed.

For example:

• If the API finds 1 address, 1 lookup is used.
• If the API finds 3 addresses, 3 lookups are used.
• If the API finds no addresses, 0 lookups are used.

US Address Enrichment API

The US Address Enrichment API includes multiple datasets, such as:

• /property
• /geo-reference
• /geo-reference/2010
• /geo-reference/2020
• /secondary
• /secondary/count

With the exception of /secondary, these endpoints use the standard lookup calculation. That means each submitted address counts as 1 lookup.

The /secondary endpoint is different. For that endpoint, each secondary address returned counts as 1 lookup.

For example, if you submit one address and the API returns 14 secondary addresses, then 14 lookups are consumed. This is commonly found in large buildings where many secondary indicators, like unit, apartment, suite numbers, and more, all exist within one location.

If you don't know how many secondary addresses a location may return, Smarty recommends using /secondary/count first. That endpoint uses only 1 lookup to determine the number of secondary addresses available. You can then decide whether you'd like a fully fleshed-out list of all secondary addresses available at that location, or if you'll need to purchase additional lookups first.

Quick summary

Here is the simplest way to think about lookup calculations:

• Most Smarty APIs calculate usage using 1 lookup per address processed.
• US Address Autocomplete Pro API may use multiple lookups for one user search because it often sends requests per keystroke as the user types.
• International Address Autocomplete API only uses a lookup when a final address is selected from the dropdown menu.
• US Extract API uses 1 lookup per detected address. If no addresses are detected in the submitted text, no lookups are consumed.
• US Address Enrichment API usually follows the standard address lookup calculation model, except for /secondary, which counts 1 lookup per returned secondary address.

Understanding how your API calculates lookups helps you estimate usage more accurately and choose the right implementation for your use case.

For more information regarding lookup calculations or implementation configurations, contact your account executive or a technical support representative.