Smarty US Street Address API

smarty · Location

Location API Key Financial Services Insurance Retail & E-Commerce Address Validation Geocoding Location

Validate, standardize, and geocode US street addresses against the USPS database. Returns deliverability status (DPV), rooftop-level latitude/longitude, and the USPS-standardized form of the address.

Authentication

API Key authentication Two credentials required: auth-id and auth-token, both passed as query parameters. Obtain them from account.smarty.com. Free tier includes 250 lookups/month with no credit card.

Parameter name: auth-id (in query)

Sample Requests

GET Validate a US address

Validates and standardizes a US street address. dpv_match_code: Y=deliverable, S/D=missing unit, N=not deliverable.

https://us-street.api.smarty.com/street-address?city=Cupertino&state=CA&street=1 Infinite Loop&auth-id=YOUR_AUTH_ID&auth-token=YOUR_AUTH_TOKEN&candidates=1

Hover any highlighted part to learn what it does

curl -X GET "https://us-street.api.smarty.com/street-address?city=Cupertino&state=CA&street=1%20Infinite%20Loop&auth-id=YOUR_AUTH_ID&auth-token=YOUR_AUTH_TOKEN&candidates=1"

import requests
params = {
    "city": "Cupertino",
    "state": "CA",
    "street": "1 Infinite Loop",
    "auth-id": "YOUR_AUTH_ID",
    "auth-token": "YOUR_AUTH_TOKEN",
    "candidates": "1"
}
response = requests.get(
    "https://us-street.api.smarty.com/street-address",
    params=params,
)
print(response.json())

const url = new URL('https://us-street.api.smarty.com/street-address');
url.searchParams.set('city', 'Cupertino');
url.searchParams.set('state', 'CA');
url.searchParams.set('street', '1 Infinite Loop');
url.searchParams.set('auth-id', 'YOUR_AUTH_ID');
url.searchParams.set('auth-token', 'YOUR_AUTH_TOKEN');
url.searchParams.set('candidates', '1');

const response = await fetch(url); 
const data = await response.json();
console.log(data);

package main

import (
	"fmt"
	"io"
	"net/http"
	"net/url"
)

func main() {
	baseURL, _ := url.Parse("https://us-street.api.smarty.com/street-address")
	q := baseURL.Query()
	q.Set("city", "Cupertino")
	q.Set("state", "CA")
	q.Set("street", "1 Infinite Loop")
	q.Set("auth-id", "YOUR_AUTH_ID")
	q.Set("auth-token", "YOUR_AUTH_TOKEN")
	q.Set("candidates", "1")
	baseURL.RawQuery = q.Encode()
	targetURL := baseURL.String()
	req, _ := http.NewRequest("GET", targetURL, nil)

	client := &http.Client{}
	resp, _ := client.Do(req)
	defer resp.Body.Close()
	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

require "net/http"
require "json"

uri = URI("https://us-street.api.smarty.com/street-address")
uri.query = URI.encode_www_form({
  "city" => "Cupertino",
  "state" => "CA",
  "street" => "1 Infinite Loop",
  "auth-id" => "YOUR_AUTH_ID",
  "auth-token" => "YOUR_AUTH_TOKEN",
  "candidates" => "1"
})

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = uri.scheme == "https"

req = Net::HTTP::Get.new(uri)

res = http.request(req)
puts JSON.parse(res.body)

<?php
$url = "https://us-street.api.smarty.com/street-address?" . http_build_query([
    "city" => "Cupertino",
    "state" => "CA",
    "street" => "1 Infinite Loop",
    "auth-id" => "YOUR_AUTH_ID",
    "auth-token" => "YOUR_AUTH_TOKEN",
    "candidates" => "1"
]);
$opts = ["http" => [
    "method" => "GET",
]];
$ctx = stream_context_create($opts);
$res = file_get_contents($url, false, $ctx);
print_r(json_decode($res, true));

GET Validate by ZIP only

Pass street and zipcode — Smarty resolves city/state from the ZIP automatically.

https://us-street.api.smarty.com/street-address?street=3003 Rainier Ave S&auth-id=YOUR_AUTH_ID&zipcode=98144&auth-token=YOUR_AUTH_TOKEN&candidates=3

Hover any highlighted part to learn what it does

curl -X GET "https://us-street.api.smarty.com/street-address?street=3003%20Rainier%20Ave%20S&auth-id=YOUR_AUTH_ID&zipcode=98144&auth-token=YOUR_AUTH_TOKEN&candidates=3"

import requests
params = {
    "street": "3003 Rainier Ave S",
    "auth-id": "YOUR_AUTH_ID",
    "zipcode": "98144",
    "auth-token": "YOUR_AUTH_TOKEN",
    "candidates": "3"
}
response = requests.get(
    "https://us-street.api.smarty.com/street-address",
    params=params,
)
print(response.json())

const url = new URL('https://us-street.api.smarty.com/street-address');
url.searchParams.set('street', '3003 Rainier Ave S');
url.searchParams.set('auth-id', 'YOUR_AUTH_ID');
url.searchParams.set('zipcode', '98144');
url.searchParams.set('auth-token', 'YOUR_AUTH_TOKEN');
url.searchParams.set('candidates', '3');

const response = await fetch(url); 
const data = await response.json();
console.log(data);

package main

import (
	"fmt"
	"io"
	"net/http"
	"net/url"
)

func main() {
	baseURL, _ := url.Parse("https://us-street.api.smarty.com/street-address")
	q := baseURL.Query()
	q.Set("street", "3003 Rainier Ave S")
	q.Set("auth-id", "YOUR_AUTH_ID")
	q.Set("zipcode", "98144")
	q.Set("auth-token", "YOUR_AUTH_TOKEN")
	q.Set("candidates", "3")
	baseURL.RawQuery = q.Encode()
	targetURL := baseURL.String()
	req, _ := http.NewRequest("GET", targetURL, nil)

	client := &http.Client{}
	resp, _ := client.Do(req)
	defer resp.Body.Close()
	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

require "net/http"
require "json"

uri = URI("https://us-street.api.smarty.com/street-address")
uri.query = URI.encode_www_form({
  "street" => "3003 Rainier Ave S",
  "auth-id" => "YOUR_AUTH_ID",
  "zipcode" => "98144",
  "auth-token" => "YOUR_AUTH_TOKEN",
  "candidates" => "3"
})

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = uri.scheme == "https"

req = Net::HTTP::Get.new(uri)

res = http.request(req)
puts JSON.parse(res.body)

<?php
$url = "https://us-street.api.smarty.com/street-address?" . http_build_query([
    "street" => "3003 Rainier Ave S",
    "auth-id" => "YOUR_AUTH_ID",
    "zipcode" => "98144",
    "auth-token" => "YOUR_AUTH_TOKEN",
    "candidates" => "3"
]);
$opts = ["http" => [
    "method" => "GET",
]];
$ctx = stream_context_create($opts);
$res = file_get_contents($url, false, $ctx);
print_r(json_decode($res, true));

Postman Setup Guide

Get Postman ↗

Sign up at smarty.com — free tier is 250 lookups/month, no credit card required
Log in to account.smarty.com and navigate to API Keys
Copy your Auth ID and Auth Token
In Postman, set the URL to https://us-street.api.smarty.com/street-address
Add query params: auth-id and auth-token
Add query params: street, city, state (or zipcode instead of city/state)
Set candidates=1 for best match only, or up to 10 for ambiguous addresses
Check dpv_match_code in the response to confirm deliverability

What can you build with Smarty US Street Address API?

Smarty US Street Address API is a Location API. Developers commonly use location APIs for:

tracking assets and vehicles in real time
building delivery and logistics apps
finding nearby businesses or services
geo-fencing and location-based notifications
address validation and autocomplete

API Key authentication. You'll receive a key after signing up. Send it with every request — in a header or query parameter. Keep it out of client-side code and never commit it to version control.

New to APIs? Read our beginner's guide

Open documentation ↗