Smarty

https://www.smarty.com/docs
Admin
Smarty provides hyper-accurate address verification, validation, parsing, standardization,...
Tokens:126,137
Snippets:1,727
Trust Score:9.3
Update:1 month ago
Show doc for...
Tokens:
Raw
### Quick start address lookup in Java

Source: https://www.smarty.com/docs/sdks/java

A complete example demonstrating authentication, client initialization, and executing a US Street address lookup.

```java
package com.example;

import com.smartystreets.api.BasicAuthCredentials;
import com.smartystreets.api.ClientBuilder;
import com.smartystreets.api.us_street.*;

import java.util.List;

public class App {
	public static void main(String[] args) throws Exception {
		BasicAuthCredentials credentials = new BasicAuthCredentials(
			System.getenv("SMARTY_AUTH_ID"),
			System.getenv("SMARTY_AUTH_TOKEN")
		);

		try (Client client = new ClientBuilder(credentials).buildUsStreetApiClient()) {
			Lookup lookup = new Lookup();
			lookup.setStreet("1600 Amphitheatre Pkwy");
			lookup.setCity("Mountain View");
			lookup.setState("CA");
			lookup.setZipCode("94043");
			lookup.setMaxCandidates(3);

			client.send(lookup);

			List<Candidate> results = lookup.getResult();

			if (results.isEmpty()) {
				System.out.println("No candidates. This means the address is not valid.");
				return;
			}

			Candidate firstCandidate = results.get(0);
			System.out.println("ZIP Code:  " + firstCandidate.getComponents().getZipCode());
			System.out.println("County:    " + firstCandidate.getMetadata().getCountyName());
			System.out.println("Latitude:  " + firstCandidate.getMetadata().getLatitude());
			System.out.println("Longitude: " + firstCandidate.getMetadata().getLongitude());
		}
	}
}
```

--------------------------------

### Install and Configure Go SDK

Source: https://www.smarty.com/docs/sdks/go

Commands to install the SDK and update module dependencies.

```bash
go get github.com/smartystreets/smartystreets-go-sdk
```

```bash
go mod tidy
```

--------------------------------

### Automation Script Header

Source: https://www.smarty.com/docs/on-prem/us-extract-api

Starting point for a Bash script to automate installation and execution.

```bash
#!/bin/bash
```

--------------------------------

### Install and Import SDK

Source: https://www.smarty.com/docs/sdks/php

Use Composer to install the package and include the autoloader in your PHP script.

```bash
composer require smartystreets/phpsdk
```

```php
require 'vendor/autoload.php';
```

--------------------------------

### Install Smarty Ruby SDK

Source: https://www.smarty.com/docs/sdks/ruby

Commands to install the SDK via RubyGems or Bundler.

```bash
gem install smartystreets_ruby_sdk
```

```ruby
gem 'smartystreets_ruby_sdk'
```

```bash
bundle
```

--------------------------------

### Install Smarty SDK

Source: https://www.smarty.com/docs/sdks/javascript

Install the package via npm.

```bash
npm install smartystreets-javascript-sdk
```

--------------------------------

### Multiple Address Candidates Example

Source: https://www.smarty.com/docs/address-suggestions-candidates

Displays an example of how a single input can resolve to multiple valid address candidates.

```text
Input: 1109 9th Phoenix, AZ
Candidate 1: 1109 S 9th Ave, Phoenix AZ 85007-3646
Candidate 2: 1109 N 9th St, Phoenix AZ 85006-2734
```

--------------------------------

### Business Dataset Summary View Example

Source: https://www.smarty.com/docs/apis/us-enrichment-api/reference

Example JSON response for a business dataset summary query. Use the business_id for detailed lookups.

```json
[
	{
		"smarty_key": "1962995076",
		"data_set_name": "business",
		"businesses": [
			{
				"company_name": "Style Studio",
				"business_id": "GEYTONJTGQYDGMRV"
			},
			{
				"company_name": "EstheticallyBree",
				"business_id": "GI3TMNBWHE3DQMJR"
			},
			{
				"company_name": "Kat Slack Beauty Llc",
				"business_id": "G4ZDINBVGY2TQNA"
			}
		]
	}
]
```

--------------------------------

### Install Smarty Python SDK

Source: https://www.smarty.com/docs/sdks/python

Use pip to install the official Smarty Python SDK package.

```bash
$ pip install smartystreets_python_sdk
```

--------------------------------

### Example API Request URL

Source: https://www.smarty.com/docs/apis/us-zipcode-api/reference

A basic example of a constructed URL for an API lookup request.

```text
https://us-zipcode.api.smarty.com/lookup?auth-id=123&auth-token=abc
```

--------------------------------

### Property Dataset Response Example

Source: https://www.smarty.com/docs/apis/us-enrichment-api/reference

Example JSON response for a property dataset query including financial features.

```json
[
	{
		"smarty_key": "4888552154",
		"data_set_name": "property",
		"attributes": {
			"1st_floor_sqft": "2302",
			"2nd_floor_sqft": "0",
			"acres": "0.3289945",
			"address_info_privacy": "",
			"air_conditioner": "yes",
			"arbor_pergola": "unknown",
			"assessed_improvement_percent": "0.00",
			"assessed_improvement_value": "0",
			"assessed_land_value": "0",
			"assessed_value": "399960",
			"assessor_last_update": "2023-01-05",
			"assessor_taxroll_update": "2022-01-01",
			"attic_area": "405",
			"financial_history": [
				{
					"document_type_description": "deed_of_trust",
					"lender_city": "Bethesda",
					"lender_last_name": "Walker & Dunlop LLC",
					"lender_name": "Walker & Dunlop LLC",
					"lender_state": "MD",
					"lender_zip": "20814",
					"mortgage_amount": "2352000",
					"mortgage_due_date": "2028-04-01",
					"mortgage_lender_code": "564631",
					"mortgage_recording_date": "2022-06-29",
					"mortgage_term": "70",
					"mortgage_term_type": "month",
					"mortgage_type": "commercial"
				},
				{
					"code_title_company": "26",
					"mortgage_amount": "77830000",
					"mortgage_due_date": "2028-04-01",
					"mortgage_lender_code": "87063",
				}
			],
			...
		}
	}
]
```

--------------------------------

### Address Data Processing Examples

Source: https://www.smarty.com/docs/extra-address-info

Examples showing how input address fields are reordered and normalized by the validation service.

```text
address1: leave packages behind bushes on the left
address2: 1402 West Center St
city: orem
state: ut
zip: 84057
```

```text
1402 W Center St.
Leave packages behind bushes on the left
Orem, UT 84057
```

```text
address1: Care of Xavier Institute for Higher Learning
address2: 1407 Greymalkin Lane
city: Salem Center
state: NY
```

```text
1407 Greymalkin Ln.
Care of Xavier Institute for Higher Learning
Salem Center, NY
```

--------------------------------

### User search input example

Source: https://www.smarty.com/docs/apis/us-autocomplete-pro-api/reference

Initial user input for an address search.

```text
1042 W Center
```

--------------------------------

### Example API response

Source: https://www.smarty.com/docs/on-prem/us-zipcode-api

The expected JSON output structure when querying the local API.

```json
[
	{
		"city_states": [
			{
				"city": "Provo",
				"mailable_city": true,
				"state": "Utah",
				"state_abbreviation": "UT"
			},
			{
				"city": "Provo Canyon",
				"mailable_city": true,
				"state": "Utah",
				"state_abbreviation": "UT"
			},
			{
				"city": "Sundance",
				"mailable_city": true,
				"state": "Utah",
				"state_abbreviation": "UT"
			}
		],
		"input_index": 0,
		"zipcodes": [
			{
				"alternate_counties": [
					{
						"county_fips": "49051",
						"county_name": "Wasatch",
						"state": "Utah",
						"state_abbreviation": "UT"
					}
				],
				"county_fips": "49049",
				"county_name": "Utah",
				"default_city": "Provo",
				"latitude": 40.26549,
				"longitude": -111.65821,
				"precision": "Zip5",
				"state": "Utah",
				"state_abbreviation": "UT",
				"zipcode": "84604",
				"zipcode_type": "S"
			}
		]
	}
]
```

--------------------------------

### API Response Example

Source: https://www.smarty.com/docs/on-prem/us-street-address-api

The expected JSON output format for a successful address verification request.

```json
[
	{
		"analysis": {
			"active": "Y",
			"dpv_cmra": "Y",
			"dpv_footnotes": "AABBR1",
			"dpv_match_code": "Y",
			"dpv_vacant": "N"
		},
		"candidate_index": 0,
		"components": {
			"city_name": "Provo",
			"delivery_point": "14",
			"delivery_point_check_digit": "0",
			"plus4_code": "4405",
			"primary_number": "3214",
			"state_abbreviation": "UT",
			"street_name": "University",
			"street_predirection": "N",
			"street_suffix": "Ave",
			"zipcode": "84604"
		},
		"delivery_line_1": "3214 N University Ave",
		"delivery_point_barcode": "846044405140",
		"input_index": 0,
		"last_line": "Provo UT 84604-4405",
		"metadata": {
			"carrier_route": "C016",
			"congressional_district": "03",
			"county_fips": "49049",
			"county_name": "Utah",
			"dst": true,
			"elot_sequence": "0016",
			"elot_sort": "A",
			"latitude": 40.27658,
			"longitude": -111.65759,
			"precision": "Zip9",
			"rdi": "Commercial",
			"record_type": "S",
			"time_zone": "Mountain",
			"utc_offset": -7,
			"zip_type": "Standard"
		}
	}
]
```

--------------------------------

### Manage the local API process

Source: https://www.smarty.com/docs/on-prem/us-zipcode-api

Commands to view help documentation and start the API server with a data path.

```bash
./us-zipcode-api -help
```

```bash
./us-zipcode-api -data "/path/to/extracted/data/package"
```

--------------------------------

### Business Name Search Requests

Source: https://www.smarty.com/docs/apis/us-enrichment-api/reference

Examples of HTTP GET requests for searching businesses by name, using state or zipcode as optional filters.

```http
https://us-enrichment.api.smarty.com/lookup/search/business?auth-id=12345&auth-token=abcdef&business_name=wash+qui+quack&state=ut
```

```http
https://us-enrichment.api.smarty.com/lookup/search/business?auth-id=12345&auth-token=abcdef&business_name=burger+king&zipcode=84058
```

--------------------------------

### Perform an Autocomplete Lookup via cURL

Source: https://www.smarty.com/docs/apis/us-autocomplete/reference

Example of a GET request to the US Autocomplete API using cURL with query parameters and a referer header.

```bash
curl 'https://us-autocomplete.api.smarty.com/v2/lookup?key=YOUR+EMBEDDED+KEY+HERE&search=123+mai&include_only_cities=chicago%2Cil&include_only_states=mi&prefer_states=il' -H 'referer: https://myneatwebsite.com'
```

--------------------------------

### Sending an HTTP GET Request with cURL

Source: https://www.smarty.com/docs/apis/international-postal-code-api/reference

Example of sending address data using query parameters via cURL. Ensure all parameter values are URL-encoded.

```bash
curl -v 'https://international-postal-code.api.smarty.com/lookup?
	auth-id=YOUR+AUTH-ID+HERE&
	auth-token=YOUR+AUTH-TOKEN+HERE&

	locality=Sao+Paulo&
	administrative_area=SP&
	postal_code=02516-040&
	country=Brazil'
```

--------------------------------

### Manage Local API Process

Source: https://www.smarty.com/docs/on-prem/us-street-address-api

Commands for displaying help information and starting the API process.

```bash
./us-street-api -help
```

```bash
./us-street-api
```

--------------------------------

### Install Smarty .NET SDK

Source: https://www.smarty.com/docs/sdks/dotnet

Use the dotnet CLI to add the Smarty SDK package to your project.

```bash
dotnet add package smartystreets-dotnet-sdk
```

--------------------------------

### Initialize API Clients

Source: https://www.smarty.com/docs/sdks/go

Build clients using either SecretKeyCredential for server-side or WebsiteKeyCredential for browser-side applications.

```go
client := wireup.BuildUSStreetAPIClient(
	wireup.SecretKeyCredential(
		os.Getenv("SMARTY_AUTH_ID"), 
		os.Getenv("SMARTY_AUTH_TOKEN")
	),
)
```

```go
client := wireup.BuildInternationalAutocompleteAPIClient(
	wireup.WebsiteKeyCredential(
		os.Getenv("SMARTY_AUTH_WEB"), 
		os.Getenv("SMARTY_AUTH_REFERER")
	),
)
```

--------------------------------

### File Format Request URLs

Source: https://www.smarty.com/docs/datasets/canada-parcel-boundary-data

Examples demonstrating how to specify different file formats in the URL path.

```text
"https://download.api.smarty.com/parcel-data/can-ab/2026/04/gpkg/latest?auth-id=YOUR+AUTH-ID+HERE&auth-token=YOUR+AUTH-TOKEN+HERE"
```

```text
"https://download.api.smarty.com/parcel-data/can-ab/2026/04/parquet/latest?auth-id=YOUR+AUTH-ID+HERE&auth-token=YOUR+AUTH-TOKEN+HERE"
```

```text
"https://download.api.smarty.com/parcel-data/can-ab/2026/04/geojson/latest?auth-id=YOUR+AUTH-ID+HERE&auth-token=YOUR+AUTH-TOKEN+HERE"
```

```text
"https://download.api.smarty.com/parcel-data/can-ab/2026/04/csv/latest?auth-id=YOUR+AUTH-ID+HERE&auth-token=YOUR+AUTH-TOKEN+HERE"
```

--------------------------------

### Sample Preference Strings

Source: https://www.smarty.com/docs/apis/us-autocomplete-pro-api/reference

Examples of query strings used to prioritize specific address suggestions in the result list.

```text
prefer_cities=SEATTLE,REDMOND,WA;RENO,NV
```

```text
prefer_states=CO;OK
```

```text
prefer_zip_codes=84660;90210&prefer_geolocation=none
```

--------------------------------

### Install CA Certificates on Alpine

Source: https://www.smarty.com/docs/on-prem/us-extract-api

Required dependency installation for Alpine Linux containers to support TLS endpoints.

```bash
apk update && apk add ca-certificates
```

--------------------------------

### Extract Packages and Run API

Source: https://www.smarty.com/docs/on-prem/us-street-address-api

Commands to extract the downloaded archives, set the library path, and start the API process.

```bash
mkdir ./data
tar xvf us-street-data.tar.gz -C ./data
```

```bash
tar xvf us-street-api.tar.gz -C .
```

```bash
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:`pwd`/lib
```

```bash
./us-street-api
```

--------------------------------

### Initialize API Clients

Source: https://www.smarty.com/docs/sdks/dotnet

Create clients for server-side or browser-based environments using the appropriate credential pairs.

```csharp
var authId = Environment.GetEnvironmentVariable("SMARTY_AUTH_ID");
var authToken = Environment.GetEnvironmentVariable("SMARTY_AUTH_TOKEN");

using var client = new ClientBuilder(authId, authToken)				
	.BuildUsStreetApiClient();
```

```csharp
var authWeb = Environment.GetEnvironmentVariable("SMARTY_AUTH_WEB");
var authReferer = Environment.GetEnvironmentVariable("SMARTY_AUTH_REFERER");

using var client = new ClientBuilder(authWeb,authReferer)
	.BuildInternationalAutocompleteApiClient();
```

--------------------------------

### Configure Environment Variables

Source: https://www.smarty.com/docs/sdks/go

Export credentials for authentication. Use Secret Keys for server-side and Website Keys for client-side.

```bash
export SMARTY_AUTH_ID="your-auth-id"
export SMARTY_AUTH_TOKEN="your-auth-token"
export SMARTY_AUTH_WEB="your-auth-web"
export SMARTY_AUTH_REFERER="your-auth-referer"
```

--------------------------------

### HTTP GET Single Input Request

Source: https://www.smarty.com/docs/apis/us-zipcode-api/reference

Demonstrates sending a single input using the GET method with URL-encoded query parameters.

```bash
curl -v 'https://us-zipcode.api.smarty.com/lookup?
	auth-id=YOUR+AUTH-ID+HERE&
	auth-token=YOUR+AUTH-TOKEN+HERE&
	city=mountain+view&
	state=CA&
	zipcode=94035'
```

--------------------------------

### Initialize API Clients

Source: https://www.smarty.com/docs/sdks/ios

Create clients for server-side or browser-based environments using the appropriate builder.

```swift
let authId = ProcessInfo.processInfo.environment["SMARTY_AUTH_ID"] ?? ""
let authToken = ProcessInfo.processInfo.environment["SMARTY_AUTH_TOKEN"] ?? ""

let client = ClientBuilder.withBasicAuth(authId: authId, authToken: authToken).buildUsStreetApiClient()
```

```swift
let id = getEnvironmentVar("SMARTY_AUTH_WEB") ?? ""
let hostname = getEnvironmentVar("SMARTY_AUTH_REFERER") ?? ""

let client = ClientBuilder(id: id, hostname: hostname).buildInternationalAutocompleteApiClient()
```

--------------------------------

### GET Request Overview

Source: https://www.smarty.com/docs/cloud/us-address-enrichment-api

The API primarily utilizes the GET method for sending inputs to retrieve address information. It supports standard HTTP headers for content negotiation and caching.

```APIDOC
## GET

### Description
Retrieves address enrichment data for a single input.

### Method
GET

### Headers
- **Content-type** (string) - Required - Describes the data format, e.g., application/json.
- **ETag** (string) - Optional - Used to check if a record has been updated since the last query. If the record has not changed, the API returns a 304 (Not Modified) status.
```

--------------------------------

### GET /lookup

Source: https://www.smarty.com/docs/cloud/us-autocomplete-pro-api

Performs an autocomplete lookup for US addresses.

```APIDOC
## GET /lookup

### Description
Performs an autocomplete lookup for US addresses using the provided key.

### Method
GET

### Endpoint
https://us-autocomplete-pro.api.smarty.com/lookup

### Parameters
#### Query Parameters
- **key** (string) - Required - Your embedded API key.
```

--------------------------------

### CLI Execution Syntax

Source: https://www.smarty.com/docs/command-line-interface

The standard syntax for invoking the smartylist tool with multiple parameters.

```bash
smartylist -[parameter] -[another-parameter]
```

--------------------------------

### GET /v2/lookup

Source: https://www.smarty.com/docs/apis/us-autocomplete/reference

Retrieves autocomplete suggestions for US addresses.

```APIDOC
## GET /v2/lookup

### Description
Retrieves autocomplete suggestions for US addresses. When using embedded key authentication, only the GET method is supported.

### Method
GET

### Endpoint
https://us-autocomplete.api.smarty.com/v2/lookup

### Parameters
#### Query Parameters
- **key** (string) - Required - Your embedded API key.
```

--------------------------------

### Install SDK Dependencies

Source: https://www.smarty.com/docs/sdks/rust

Use Cargo to add the Smarty SDK and necessary asynchronous runtime and serialization dependencies.

```bash
cargo add smarty-rust-sdk
cargo add tokio --features full
cargo add serde_json
```

--------------------------------

### Configure Client Options

Source: https://www.smarty.com/docs/sdks/php

Customize client behavior such as retries, timeouts, proxy settings, and custom headers during initialization.

```php
$client = (new ClientBuilder($credentials))  
	->retryAtMost(10)  
	->withMaxTimeout(30000)  
	->withUrl("https://your-self-hosted-url.example.com")  
	->viaProxy("proxy.example.com", "username", "password")  
	->withCustomHeader("X-Custom-Header", "value")  
	->buildUsStreetApiClient();
```

--------------------------------

### Invalid Address JSON Response

Source: https://www.smarty.com/docs/apis/us-street-api/reference

Example of a response when no addresses are matched.

```json
[]
```

--------------------------------

### Download API and Data Packages

Source: https://www.smarty.com/docs/on-prem/us-street-address-api

Use curl to download the API binary and the required data package. Replace placeholders with your actual authentication credentials.

```bash
curl -L "https://download.api.smarty.com/us-street-api/linux-amd64/latest.tar.gz?auth-id=YOUR_AUTH_ID&auth-token=YOUR_AUTH_TOKEN" -o us-street-api.tar.gz
```

```bash
curl -L "https://download.api.smarty.com/us-street-api/data/latest.tar.gz?auth-id=YOUR_AUTH_ID&auth-token=YOUR_AUTH_TOKEN" -o us-street-data.tar.gz
```

--------------------------------

### API suggestions response

Source: https://www.smarty.com/docs/apis/us-autocomplete-pro-api/reference

Example of address suggestions returned by the API.

```text
1042 W Center St Apt (108 entries) Orem, UT 84057
1042 W Center St Unit (60 entries) Orem, UT 84057
1042 E Center St Orem, UT 84057
1042 W Center St Alma, MI 48801
... (6 more are returned but not show here)
```

--------------------------------

### GET /health

Source: https://www.smarty.com/docs/mcp

Performs a health check on the server to ensure it is operational.

```APIDOC
## GET /health

### Description
Returns the current health status of the server.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - The health status, typically "ok".
```

--------------------------------

### Initialize Server-side Client

Source: https://www.smarty.com/docs/sdks/rust

Configure a US Street Address client using BasicAuthCredential and OptionsBuilder.

```rust
let authentication = BasicAuthCredential::new(
    std::env::var("SMARTY_AUTH_ID").expect("Missing SMARTY_AUTH_ID env variable"),
    std::env::var("SMARTY_AUTH_TOKEN").expect("Missing SMARTY_AUTH_TOKEN env variable"),
);

let options = OptionsBuilder::new(Some(authentication))
    .with_logging()
    .build();

let client = USStreetAddressClient::new(options)?;
```

--------------------------------

### Initialize Credentials

Source: https://www.smarty.com/docs/sdks/python

Load credentials from environment variables for either server-side or client-side authentication.

```python
# Server-side  
auth_id = os.environ['SMARTY_AUTH_ID']  
auth_token = os.environ['SMARTY_AUTH_TOKEN']  
credentials = BasicAuthCredentials(auth_id, auth_token)  
  
# Client-side  
key = os.environ['SMARTY_AUTH_WEB']  
hostname = os.environ['SMARTY_WEBSITE_DOMAIN']  
credentials = SharedCredentials(key, hostname)
```

--------------------------------

### GET /

Source: https://www.smarty.com/docs/apis/us-reverse-geocoding-api/reference

Retrieve address information for a specific set of geographic coordinates.

```APIDOC
## GET /

### Description
Retrieves address information based on the provided latitude and longitude coordinates.

### Method
GET

### Endpoint
/

### Parameters
#### Query Parameters
- **latitude** (decimal) - Required - The latitude portion of the coordinate, between -90.0 and 90.0.
- **longitude** (decimal) - Required - The longitude portion of the coordinate, between -180.0 and 180.0.
- **source** (string) - Optional - Data source filter. Allowed values: 'all' (includes non-postal addresses) or 'postal' (default, limits to postal addresses only).
```

--------------------------------

### Create and Send Lookups

Source: https://www.smarty.com/docs/sdks/go

Define address lookups, append them to a batch, and send the batch via the client.

```go
addresses := []string{
	"1600 Pennsylvania Avenue Washington, DC",
	"1600 Amphitheatre Parkway Mountain View, CA 94043",
}

batch := street.NewBatch()
for _, address := range addresses {
	lookup := &street.Lookup {
		Street: address,
	}
	batch.Append(lookup)
}
```

```go
if err := client.SendBatch(batch); err != nil {
	log.Fatal("Error sending batch:", err)
}
```
Tokens:
Raw