US Autocomplete API

Data Validation / API Key Intermediate HTTPS CORS
Varies by plan (check documentation)

Overview

Smarty's US Autocomplete Pro API provides real-time US address suggestions as users type, returning up to 10 valid USPS-deliverable address candidates per query to reduce data entry errors and speed up checkout flows. It uses USPS data to ensure every suggested address is a real, deliverable location rather than a guess. A free plan is available with a limited number of lookups per month.

Beginner Tip

Sign up at smarty.com for a free API key (embedded key). The endpoint is `https://us-autocomplete-pro.api.smarty.com/lookup?key=YOUR_KEY&search=123+Main`. Pass the partial address as the `search` parameter. Each keystroke query counts as one lookup — debounce your input handler to avoid burning through your free quota quickly.

Available Data

vehicle make and model
year and specifications
fuel economy
VIN decode data

Example Response

JSON Response
{
  "make": "Toyota",
  "model": "Camry",
  "year": 2025,
  "engine": "2.5L 4-cylinder",
  "fuel_economy": {
    "city_mpg": 28,
    "highway_mpg": 39
  },
  "msrp": 28400
}

Field Reference

suggestions Array of address suggestion objects matching the partial input.
suggestions[].street_line The suggested street address line (e.g., `123 Main St`).
suggestions[].secondary Secondary address info such as apartment or suite number, if applicable.
suggestions[].city City name for the suggested address.
suggestions[].state Two-letter US state abbreviation.
suggestions[].zipcode Five-digit ZIP code for the suggested address.

Implementation Example

Request
const url = "https://www.smarty.com/docs/cloud/us-autocomplete-pro-api";
// Replace headers or query params with the values required by this API.
const response = await fetch(url, {
  headers: {
  "X-API-Key": "YOUR_API_KEY"
  }
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = await response.json();
console.log(data);

What Can You Build?

Note: These code examples are AI-generated and unverified. Always refer to the official API documentation for accurate usage.

Common Errors & Troubleshooting

401 Unauthorized or bad credentials Using a server-side secret key instead of an embedded/browser key, or the key has not been assigned the Autocomplete Pro product.
In your Smarty dashboard, generate an `Embedded Key` specifically for autocomplete. Server-side keys are restricted and require IP whitelisting.
Empty suggestions array for valid addresses Query string is too short (less than 3 characters) or contains only numbers without a street name.
Wait until the user has typed at least 3 characters including part of a street name before making the API call.
Exceeded lookup quota Burning through free lookups by calling the API on every keypress.
Debounce input events to fire only after 300ms of inactivity, and set a minimum query length of 3 characters. Cache repeated identical queries.

Metadata Score Breakdown

Estimated from metadata — endpoint not independently tested

This score is estimated from observable metadata — HTTPS support, authentication model, declared CORS, and documentation reachability — because the API requires authentication or exposes no publicly testable endpoint. The five-signal breakdown is only shown for live-tested APIs.

Metadata estimate · endpoint not independently tested

Technical Specifications

Auth API Key
HTTPS REQUIRED
CORS YES
Category Data Validation
Difficulty Intermediate
Verified: 2026-04-04

Related Tags

Similar APIs

View All →